Skip to content

MCP servers

A pack can define MCP servers once, in mcp/servers.toml, and apply writes them into each tool's own config. brainrc core ships none; they come from your packs. Only the full profile installs them, and full is the default (configuration).

Add a server

In your pack's mcp/servers.toml:

[servers.acme-github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env_from = ["GITHUB_PERSONAL_ACCESS_TOKEN"]   # names only; the value stays in your environment
harnesses = ["claude", "codex"]               # optional; default: every tool brainrc writes MCP servers for

[servers.acme-docs]
url = "https://docs.example.com/mcp"          # an HTTP server instead of a command

A server's name starts with the pack's prefix, like its other items. Then run brainrc apply. Close Claude Code first: it rewrites ~/.claude.json while it runs, and apply refuses to write a file that changed under it.

Where they go

Tool File Written as
Claude Code ~/.claude.json mcpServers
Codex ~/.codex/config.toml a marked [mcp_servers] block
OpenCode ~/.config/opencode/opencode.json mcp (opencode.jsonc when only that exists, keeping its comments)

Antigravity and Cursor aren't supported yet.

Secrets stay out of files

env_from names environment variables; brainrc writes a reference the tool expands when it starts the server (${NAME}, env_vars or {env:NAME}), never the value. validate rejects a server with an env table, which would hold values.

Your own servers are safe

brainrc only replaces or removes servers it wrote itself (it keeps a list in ~/.config/brainrc/mcp-owned.json). If you already defined a server of the same name, apply reports a CONFLICT and leaves yours alone. A backup of the file is written before every change.

Pin their tools

An MCP server can change what its tools do after you approved it. brainrc pin-mcp guards against that for Claude Code:

brainrc pin-mcp

It starts each stdio server brainrc installs, lists its tools, shows what changed since the last pin, and on your yes records a hash of each tool's definition. At the start of each Claude Code session a hook checks the tools again. If one changed, it warns you and tells the model not to call it until you run pin-mcp again. HTTP servers aren't pinned, and the check gets 4 seconds for all servers together: a server it can't reach in that time is skipped (guardrails).

apply names each stdio server whose tools aren't pinned yet.

The full format is in formats.