> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modusbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Connect ModusBrain to Claude Code via MCP.

# Connect ModusBrain to Claude Code

> New to this? The [Give your coding agent a memory](../tutorials/connect-coding-agent.md)
> tutorial walks both paths (local-from-nothing and connect-to-an-existing-brain)
> end to end, plus the brain-first protocol that makes it worth it. This page is
> the connection reference.

## Option 1: Local (recommended, zero server needed)

```bash theme={null}
claude mcp add modusbrain -- modusbrain serve
```

That's it. Claude Code spawns `modusbrain serve` as a stdio subprocess. No server, no
tunnel, no token needed. Works with both PGLite and Supabase engines.

## Option 2: Remote, one command (fastest from a bearer token)

If ModusBrain is running somewhere as an HTTP server (`modusbrain serve --http`, see the
[ngrok-tunnel recipe](../../recipes/ngrok-tunnel.md)) and you have a bearer token,
let `modusbrain connect` generate the wire-up for you.

On the host (or anywhere `modusbrain` is installed), mint a token and print the block:

```bash theme={null}
modusbrain auth create "claude-code"
modusbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --token modusbrain_xxx
```

`modusbrain connect` prints a short, copy-paste block. Paste it into Claude Code — it
runs the `claude mcp add` for you and tells the agent to call `get_brain_identity`
and `list_skills` so it immediately knows what the brain can do.

Already on the machine you want to wire up? Skip the copy-paste and let `connect`
do it directly, with a built-in token smoke-test:

```bash theme={null}
modusbrain connect https://YOUR-DOMAIN.ngrok.app --token modusbrain_xxx --install
```

(`--install` runs `claude mcp add`, then verifies the token by calling
`get_brain_identity` — so a wrong or expired token fails now, not silently on the
agent's first request. The URL is normalized: a bare host without `/mcp` gets it
appended; pass an explicit `https://` scheme.)

Pipe-friendly machine output (token redacted unless `--show-token`):

```bash theme={null}
modusbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --token modusbrain_xxx --json
```

## Option 3: Remote, manual `claude mcp add`

Equivalent to what `modusbrain connect` generates, if you'd rather run it yourself:

```bash theme={null}
claude mcp add modusbrain -t http \
  https://YOUR-DOMAIN.ngrok.app/mcp \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Replace `YOUR-DOMAIN` with your ngrok domain and `YOUR_TOKEN` with a token from
`modusbrain auth create "claude-code"`.

> A `modusbrain auth create` token is a long-lived, full-access secret. Keep it
> private (it lands in `~/.claude.json`), and prefer a scoped/short-lived token
> where your host supports one.

## Verify

In Claude Code, try:

```
search for [any topic in your brain]
```

You should see results from your ModusBrain knowledge base.

> **`list_skills` returns nothing?** Skill discovery is gated by `mcp.publish_skills`
> on the host. New brains from `modusbrain init` default it ON; brains upgraded from an
> older release stay OFF until you opt in. Enable it on the host with
> `modusbrain config set mcp.publish_skills true`. The core tools (search, query,
> get\_page, put\_page, think, find\_experts) work regardless. Note: `capture` is a
> CLI-only command, not an MCP tool — the agent writes over MCP with `put_page`.

## Remove

```bash theme={null}
claude mcp remove modusbrain
```