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.

Sign in to manage personal MCP tokens. The step 2 instructions still work with an existing token.
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.

Shell profile only
# Brain Researcher MCP (add to ~/.bashrc, ~/.zshrc, or ~/.profile) export BR_MCP_TOKEN="brk_<kid>.<secret>" export BR_MCP_AUTH_HEADER="Bearer ${BR_MCP_TOKEN}"
Add this export block to your shell setup file, such as ~/.bashrc, ~/.zshrc, or ~/.profile. Start your client from an environment that inherits BR_MCP_TOKEN. Do not paste these export lines into the MCP config file.
mcp.json only
Paste only this config into mcp.json. It reads BR_MCP_TOKEN from your client environment.
{
  "mcpServers": {
    "brain-researcher": {
      "type": "http",
      "url": "https://brain-researcher.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BR_MCP_TOKEN}",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}
Client-specific notes
Cursor uses Authorization: Bearer ${env:BR_MCP_TOKEN}. Start it from an environment that inherits BR_MCP_TOKEN.
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.
Cursor prompt
@brain-researcher: call server_info and system_self_test, then summarize whether the Brain Researcher MCP server is ready.
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.
  • MCP stays available from your configured coding-agent environment.
  • 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