Run Brain Researcher with MCP

Brain Researcher hands workflows off to whatever coding agent you already use. Configure your client once below, then hand off from any workflow, dataset, or KG view.

Paste this into your IDE's MCP configuration:

mcp.json

{
  "mcpServers": {
    "brain-researcher": {
      "type": "http",
      "url": "https://brain-researcher.com/mcp",
      "headers": {
        "Authorization": "Bearer brk_<kid>.<secret>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Works with: Cursor · Windsurf · Codex · Claude Code

Cursor and Windsurf work best with the full token pasted directly into the JSON config.

Codex uses ~/.codex/config.toml with BR_MCP_TOKEN in the shell and the Accept header under [http_headers].

Claude Code keeps Authorization: Bearer ${BR_MCP_TOKEN} in the hosted HTTP JSON config.

Personal MCP token

One active token per user. Generating a new token rotates the previous one immediately.

Checking sign-in status for MCP token management…

Shell environment

# Brain Researcher MCP export BR_MCP_TOKEN="brk_<kid>.<secret>" export BR_MCP_AUTH_HEADER="Bearer ${BR_MCP_TOKEN}"

Use your personal token value (format: brk_<kid>.<secret>). Do not include the Bearer prefix in BR_MCP_TOKEN. This shell export is for Codex and Claude Code. Cursor and Windsurf paste the full token directly into JSON.

View docs →

Terminal setup and live checks

Run Brain Researcher with MCP

Configure the token once, connect Codex, Cursor, or Claude Code, then ask the agent to run health checks before requesting workflow recipes.

Keep BR_MCP_TOKEN as the raw brk_... token. Do not put Bearer inside the token value.

1. Put the token in your shell

Use ~/.zshrc on macOS/zsh, or the matching shell profile for your terminal.

Terminal

nano ~/.zshrc

# Brain Researcher MCP
export BR_MCP_TOKEN="brk_<kid>.<secret>"
export BR_MCP_AUTH_HEADER="Bearer ${BR_MCP_TOKEN}"

source ~/.zshrc
test -n "$BR_MCP_TOKEN" && echo "BR_MCP_TOKEN is set"

2. Check the connection in your agent

Start the interactive client after reloading the shell, then paste one of these prompts.

Codex prompt

show me the status of brain_researcher_mcp. Use the Brain Researcher MCP server_info and system_self_test tools. Keep the answer concise.

Claude Code prompt

show me the status of brain_researcher_mcp. Use the brain-researcher MCP server_info and system_self_test tools. Keep the answer concise.

Expected result: server_info returns ok=true, and system_self_test returns overall=pass. If a client cannot see those tools, ask it to inspect the exposed MCP tool names before trying another function.

3. Ask for a workflow handoff

This example prepares a recipe. It should not be described as completed hosted execution unless artifacts are actually produced and inspected.

Example MCP handoff prompt

Use Brain Researcher MCP to prepare a runnable recipe for resting-state connectivity on ds000114. First inspect the available MCP tools, then call server_info and system_self_test. Use workflow_search for resting-state connectivity and then get_execution_recipe with tool_id="workflow_rest_connectome_e2e", target_runtime="python", params={"dataset_id":"ds000114"}. Return the exact recipe command, required inputs, expected artifacts, and any blockers before claiming execution is possible.

Agent rules to give users

These are the public-facing version of the repo's Brain Researcher MCP agent rules.

Required first check

Confirm the Brain Researcher MCP server is active.
Inspect the actual exposed tool names before invoking a function.
Run health checks before claiming execution, validation, or data access.
If MCP is unavailable, say that directly and continue with the closest fallback.

Execution boundary

get_execution_recipe returns a recipe, not a completed analysis.
Hosted Studio may be credit-gated, degraded, or blocked while MCP remains usable.
Success means expected artifacts, logs, and run manifests were produced and checked.
Dangerous/admin execution tools should only be used when the user asks for them.

Common MCP functions

The active client may expose only a subset. Ask it to inspect the tool list first.

Open starter repo

Health checks

Use before claiming the MCP server is connected, healthy, or able to access runtime resources.

server_infosystem_self_test

Find workflows and evidence

Use to map a user question to workflows, tools, datasets, tasks, and KG evidence.

workflow_searchtool_searchkg_search_nodeskg_search_datasets

Prepare execution handoff

Use for runnable local, container, Neurodesk, or cluster recipes. These tools prepare plans; they do not prove execution happened.

get_execution_recipeplan_preflightplan_create

Validate before running

Use when a plan or implementation needs schema, path, modality, ordering, or domain checks.

pipeline_plan_validatepipeline_plan_reviewqsm_implementation_review

Inspect runs and artifacts

Use only when the active MCP client exposes run or artifact tools for the relevant persisted run.

run_getrun_logsartifact_listartifact_read_text