# mcp

Use this when several agent tools need the same MCP servers and you want to maintain them in one place.

Every agent tool reads its MCP servers from a different file in a different shape. `brigadestack mcp`
keeps one canonical catalog and merges it into each tool's native config, so the same servers are
wired everywhere from a single source.

If you are comparing approaches before installing anything, start with the plain-English answer page:
[sync MCP servers across coding agents](/compare/sync-mcp-servers-across-coding-agents).

It is the one place BrigadeStack writes runtime config into tool-owned files. Sync is dry-run by default, merges by server key (servers you added by hand are preserved), and never inlines secrets: env values are written as `${VAR}` references.

## The canonical catalog

`.brigade/mcp.json` is tracked and shared. Ownership of which server keys BrigadeStack manages in each
tool file is tracked in the gitignored `.brigade/mcp/state.json`.

```jsonc
{
  "version": 1,
  "servers": {
    "github": {
      "transport": "stdio",
      "enabled": true,
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": { "ref": "GITHUB_TOKEN" } },
      "timeout": 60
    }
  }
}
```

## Supported tools

Fifteen adapters ship: seven that write a file in the repo or the Antigravity user config, and eight user-global ones that write the per-user config a tool reads everywhere. User-scope adapters are only written with `--user-scope`.

| Adapter | File | Shape |
|------|------|-------|
| `claude` | `.mcp.json` | JSON `mcpServers` |
| `cursor` | `.cursor/mcp.json` | JSON `mcpServers` |
| `codex` | `.codex/config.toml` | TOML `[mcp_servers.*]`, surgical merge |
| `grok` | `.grok/config.toml` | TOML `[mcp_servers.*]` |
| `vscode` | `.vscode/mcp.json` | JSON `servers` + `inputs[]` for secrets |
| `opencode` | `opencode.json` | JSON `mcp`, command-array shape |
| `antigravity` | `~/.gemini/config/mcp_config.json` | JSON `mcpServers`, `serverUrl` for remote (user-scoped) |
| `claude-user` | `~/.claude.json` | JSON `mcpServers` (user-scoped) |
| `cursor-user` | `~/.cursor/mcp.json` | JSON `mcpServers` (user-scoped) |
| `kimi-user` | `~/.kimi-code/mcp.json` | JSON `mcpServers` (user-scoped) |
| `opencode-user` | `~/.config/opencode/opencode.json` | JSON `mcp` (user-scoped) |
| `codex-user` | `~/.codex/config.toml` | TOML `[mcp_servers.*]` (user-scoped) |
| `grok-user` | `~/.grok/config.toml` | TOML `[mcp_servers.*]` (user-scoped) |
| `openclaw` | `~/.openclaw/openclaw.json` | JSON `mcp.servers` (user-scoped) |
| `hermes` | `~/.hermes/config.yaml` | YAML `mcp_servers` (user-scoped) |

## Commands

```bash
brigadestack mcp init                       # scaffold the catalog + sidecar, update .gitignore
brigadestack mcp add --name github \
  --command npx --args "-y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ref:GITHUB_TOKEN --timeout 60
brigadestack mcp list
brigadestack mcp plan                       # preview (read-only)
brigadestack mcp sync                       # dry-run across every configured tool
brigadestack mcp sync --write               # merge into each tool's config
brigadestack mcp sync --write --user-scope  # also write the user-global configs
brigadestack mcp doctor
brigadestack mcp import cursor --merge      # read an existing config into the catalog
brigadestack operator sync-mcp --write      # validate -> sync -> summary, one receipt
```

## Merge and ownership

BrigadeStack owns only the server keys it recorded. A server you added to a tool config yourself is
preserved untouched. A server BrigadeStack manages but you then edited is a conflict, skipped unless you
pass `--force`. Servers removed from the catalog are deleted only with `--prune`, and only when they
still match what BrigadeStack wrote. If the sidecar is lost (a fresh clone), a live server identical to
what BrigadeStack would write is reconciled back to owned, so re-syncing does not spuriously conflict.

Secrets are written as references, never values: `${VAR}` for most tools, a `${input:VAR}` plus a
top-level `inputs[]` entry for VS Code. `brigadestack mcp import` demotes any literal-looking secret in an
existing config to a reference and never copies the value into the catalog.

## Serving Brigade's own MCP servers

BrigadeStack also ships two MCP servers of its own, separate from the catalog sync above.

- `brigadestack memory serve-mcp` serves memory cards and handoffs. Its tools are `list_cards`, `get_card`, `search_cards`, `memory_status`, `work_brief`, and `write_handoff`. Cards come from the repo store and a user store under `BRIGADE_HOME`, and are served only when their real path stays inside the store. `write_handoff` writes to the repo's handoff inbox (`--inbox` picks the alias or path), caps content at 256 KiB, and caps facts and evidence at 50 items each. `work_brief` builds its keys from local git and session state only and never contacts the backend.
- `brigadestack skills serve-mcp` serves the skill registry read-only.

`--target` for the memory server defaults to the nearest directory above the working directory that holds `.brigade/config.json` or `.brigade/memory-care.toml`, never the home directory. Run without `--stdio` or `--http` to print the contract instead of starting a server (add `--json` for machine-readable output).

```bash
brigadestack memory serve-mcp --stdio
brigadestack skills serve-mcp --stdio
```

For MCP hosts that cannot spawn a stdio process, pass `--http` to serve a stateless Streamable HTTP endpoint on loopback instead: `POST /mcp` for requests and `GET /healthz` for a health check. The memory server defaults to port 8931 and the skills server to 8932. Use `--port` to change it, and `--host` to choose `127.0.0.1`, `::1`, or `localhost`.

```bash
export BRIGADE_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
brigadestack memory serve-mcp --http --port 8931
```

- The server requires a bearer token from `BRIGADE_MCP_HTTP_TOKEN`. The token must be 32 characters or more and is read from the environment only, never from a flag.
- It binds only `127.0.0.1` or `::1`, rejects non-loopback `Host` and `Origin` headers, and caps request bodies at 1 MiB.
- `--stdio` behaves as before.