Docs / Reference
mcp
Sync one canonical MCP server catalog into each tool's native config file.
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.
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.
{
"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
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-mcpserves memory cards and handoffs. Its tools arelist_cards,get_card,search_cards,memory_status,work_brief, andwrite_handoff. Cards come from the repo store and a user store underBRIGADE_HOME, and are served only when their real path stays inside the store.write_handoffwrites to the repo’s handoff inbox (--inboxpicks the alias or path), caps content at 256 KiB, and caps facts and evidence at 50 items each.work_briefbuilds its keys from local git and session state only and never contacts the backend.brigadestack skills serve-mcpserves 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).
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.
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.1or::1, rejects non-loopbackHostandOriginheaders, and caps request bodies at 1 MiB. --stdiobehaves as before.