Connect Claude Code over MCP

In this tutorial you’ll connect a running brain to Claude Code so the model can call any of the seventeen brain_* tools. The transport is stdio, so there’s nothing to host, no keys to manage, and no port to open.

This is the canonical wiring path. For other MCP clients (Cursor, custom rmcp clients) the shape of the config is identical; only the location of the config file differs.

Before you start

• You’ve completed Build your first brain — there’s a ~/brain.db somewhere.
• You’re on macOS or Linux. (Windows MCP hosting is deferred; the CLI works fine there but gbrain serve returns UnsupportedPlatformError.)
• Claude Code is installed and you can edit its MCP config.

Fast path

01

Confirm gbrain serve runs

You should see the server hold the terminal open, waiting for stdio. Ctrl-C to exit. If it errors immediately, the brain probably has the wrong model recorded — see troubleshooting.

Sanity check

GBRAIN_DB=~/brain.db gbrain serve

02

Add the MCP server to Claude Code

Replace the path with the absolute path to your brain.db. Claude Code spawns gbrain serve as a child process and speaks JSON-RPC 2.0 over its stdin/stdout.

claude_desktop_config.json (or equivalent)

{
"mcpServers": {
  "gbrain": {
    "command": "gbrain",
    "args": ["serve"],
    "env": { "GBRAIN_DB": "/Users/you/brain.db" }
  }
}
}

03

Restart Claude Code

Most MCP clients only re-read the config on startup. Quit and relaunch Claude Code so it picks up the new server entry.

04

Confirm the tools are available

If the server doesn’t appear, check the Claude Code logs for spawn errors. The most common issue is command: “gbrain” not being on PATH for the spawned shell — use the absolute path (/Users/you/.local/bin/gbrain) if needed.

In Claude Code

# Within Claude Code:
# /mcp list         (see "gbrain" in the list of servers)
# /mcp tools        (see all 17 brain_* tools)

05

Try it

Ask Claude Code something only your brain knows: “Use brain_query to find people interested in offline-first knowledge.” It should call brain_query with your phrasing and return your Alice page.

What just happened

• Claude Code spawned gbrain serve as a child process.
• The child opened your brain.db, validated the recorded embedding model, and started listening on stdio.
• Claude Code issued an MCP handshake (initialize → tools/list) and got back the seventeen brain_* tool definitions.
• When you asked a question, the model picked the appropriate tool, made a tools/call, and rendered the result.

There is no daemon, no port, no auth layer. The trust boundary is “anything Claude Code can spawn”.

Common adjustments

A different brain per project

Put a .mcp.json in your project directory with a project-scoped brain path:

Project-scoped MCP config

{
"mcpServers": {
  "gbrain": {
    "command": "gbrain",
    "args": ["serve"],
    "env": { "GBRAIN_DB": "./brain.db" }
  }
}
}

Claude Code merges project and user MCP configs. Per-project brains are how you keep your work, side-projects, and personal notes separate.

A pinned model on the online build

If you’ve initialized a brain with a non-default model (e.g. large), the serve process must use the same --model. Either set GBRAIN_MODEL=large in the env block or pass it as an arg:

Pinned model

{
"mcpServers": {
  "gbrain": {
    "command": "gbrain",
    "args": ["serve", "--model", "large"],
    "env": { "GBRAIN_DB": "/Users/you/brain.db" }
  }
}
}

Read-only mode

There isn’t a CLI flag for it, but if you point Claude Code at a brain inside a read-only collection (gbrain collection add … --read-only), every mutating tool call will return CollectionReadOnlyError. Useful for pairing an agent with someone else’s brain you’ve snapshotted locally.

What the agent now sees

Once connected, Claude Code can:

• Read any page (brain_get, brain_search, brain_query, brain_list, brain_timeline, brain_backlinks, brain_graph).
• Write pages, links, tags, and raw data (brain_put, brain_link, brain_link_close, brain_tags, brain_raw) — subject to the collection write-gate.
• Run intelligence checks (brain_check, brain_gap, brain_gaps, brain_stats, brain_collections).

This is the full brain. Anything you can do at the CLI, the agent can do over MCP — and vice versa. See the MCP tool reference for parameter shapes.

Now go customize the workflow

The agent quickstart covers the recommended skill load order and the sensitivity contract; the skills how-to shows how to override default workflows for your brain.

Agent quickstart Customize skills