Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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.

AdapterFileShape
claude.mcp.jsonJSON mcpServers
cursor.cursor/mcp.jsonJSON mcpServers
codex.codex/config.tomlTOML [mcp_servers.*], surgical merge
grok.grok/config.tomlTOML [mcp_servers.*]
vscode.vscode/mcp.jsonJSON servers + inputs[] for secrets
opencodeopencode.jsonJSON mcp, command-array shape
antigravity~/.gemini/config/mcp_config.jsonJSON mcpServers, serverUrl for remote (user-scoped)
claude-user~/.claude.jsonJSON mcpServers (user-scoped)
cursor-user~/.cursor/mcp.jsonJSON mcpServers (user-scoped)
kimi-user~/.kimi-code/mcp.jsonJSON mcpServers (user-scoped)
opencode-user~/.config/opencode/opencode.jsonJSON mcp (user-scoped)
codex-user~/.codex/config.tomlTOML [mcp_servers.*] (user-scoped)
grok-user~/.grok/config.tomlTOML [mcp_servers.*] (user-scoped)
openclaw~/.openclaw/openclaw.jsonJSON mcp.servers (user-scoped)
hermes~/.hermes/config.yamlYAML 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-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).

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.1 or ::1, rejects non-loopback Host and Origin headers, and caps request bodies at 1 MiB.
  • --stdio behaves as before.