Brain Researcher

Connect Brain Researcher to your coding agent

Four steps: 1) generate a personal token, 2) paste the config into Cursor, Codex, or Claude Code, 3) verify the connection, then 4) hand off a workflow. After setup you can hand off from any workflow, dataset, or KG view.

1

Generate your personal token

One active token per user. Generating a new one rotates the previous immediately — the full secret is shown only once, so copy it now.

Checking sign-in status for MCP token management…
Sign in to view or manage MCP tokens.
2

Add Brain Researcher to your coding agent

Pick your client, then keep shell exports and MCP config files separate.

mcp.json only
Paste the raw brk_<kid>.<secret> token directly into this JSON config. Do not add a Bearer prefix or a shell export block.
{
  "mcpServers": {
    "brain-researcher": {
      "type": "http",
      "url": "https://brain-researcher.com/mcp",
      "headers": {
        "Authorization": "Bearer brk_<kid>.<secret>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}
Client-specific notes
Cursor and Windsurf work best with the full token pasted directly into the JSON config. They do not need the shell export unless your own environment uses it.
Codex uses ~/.codex/config.toml with bearer_token_env_var = "BR_MCP_TOKEN". Define that variable in your user shell profile, not in the Codex TOML. Keep the Accept header under [http_headers].
Claude Code keeps the Authorization: Bearer ${BR_MCP_TOKEN} in the hosted HTTP JSON config, but the variable itself still belongs in your user shell profile before launching Claude Code.
View docs →
3

Verify the connection

Start your agent after reloading the shell, then paste one of these prompts to confirm the tools are live.

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.
4

Run a workflow handoff

This prepares a recipe. It is not 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.

Reference · agent rules

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.

Reference · common 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