feat(mcp): manage MCP servers per provider and per agent

[Juliusolsson05]

Problem

Agent Code could not add, configure or switch off a third-party MCP server. A user who wanted, say, the Beeper Desktop MCP server had to hand-edit ~/.claude.json / ~/.codex/config.toml outside the app. The server then landed on every agent of that provider, could not be turned off for one agent, and never appeared in Agent Code. Built-in MCP choices were also spread across eight Settings rows and ten palette commands, and each command reloaded the agent on its own.

What this does

One MCP interface for every MCP server

• Settings → MCP (new category): Agent Code's built-in servers (TLDR, Goal, Goal Loop, Orchestration, Transcripts, Agent Management, AI Workspace, Workflows) and the user's own servers share one grid, with one column per provider enabled in Settings → Providers (feat(usage): provider enablement, Grok and z.ai usage readers, scaled usage modal #1126).
  • Every checkbox means the same thing: "new agents of this provider get it".
  • Built-in defaults are now per provider. A pre-existing flat list is copied to every provider, so upgrading changes nobody's agents.
  • The External operator MCP row moves here unchanged.
• Add MCP Server…: paste the config from a server's README. mcpServers blocks, the VS Code servers/inputs form, a bare map, or a single entry all work.
  • Any stdio, Streamable HTTP or SSE server can be added. SSE is Claude-only, because Codex has no SSE transport.
  • Every env and header value is moved into an encrypted secret, referenced as ${input:id} (VS Code's syntax). README placeholders such as YOUR_TOKEN_HERE are recognized and left unset.
• Agent MCP Servers…: one picker for the focused agent covering built-in and user servers. Changes are staged and applied with one reload.
  • Root Management still goes through its confirmation dialog, which now applies the other staged choices in the same reload.
  • Removing Goal Loop's tools still ends a running loop first (the feat(goal-loop): a per-agent Goal Loop MCP command, and the overlay chord off ⌘⇧Y #1045 rule).
  • It retires use-global-mcp-settings and the eight enable-*-mcp toggles. They are listed in RETIRED_BUILT_IN_COMMAND_IDS so stale overrides are pruned.
• Servers the CLIs already load from ~/.claude.json / config.toml are listed read-only, with every value withheld. Copy in imports one as a managed server.
• A server that cannot attach produces a toast naming the server and the reason.

Agents can manage it too (off by default)

• A new mcp_servers built-in capability gives agents mcp_servers_list/add/update/remove/set_secret, through the same service Settings uses.
• An agent proposes, the user approves. Anything an agent adds, or points at a different URL, command, arguments or environment, is saved switched off and flagged "waiting for your review". Only the user can turn a server on.
• No tool returns a secret or a raw entry: agents see redacted summaries. Every agent change raises a toast.
• Orchestration children cannot be given mcp_servers or root_management unless the parent holds them. This closes a path around off-by-default; the same hole existed for root_management before this PR.

Delivery at launch, no provider config writes

• Main owns mcp-servers.json (mode 0600) and the safeStorage secret blobs. The renderer only sends a pane's explicit per-agent choices, as user:<id> keys in the existing override map.
• At launch, main applies:
  • the master switch and per-provider defaults;
  • secret readiness and transport support;
  • Codex name collisions;
  • Claude's enterprise MCP policy.
• It reports what actually attached (userMcpServerIds), the same way builtInMcpDomains is reported.
• Claude: resolved user entries go into the same private 0600 --mcp-config file as the built-in server, never into Claude's environment.
  • Claude's environment is inherited by every MCP child and by the model's Bash tool.
  • The file is deleted once Claude is ready, on stop and on rollback, and swept at startup after a crash.
• Codex: --config mcp_servers.<name>.*. Headers go through env_http_headers, and stdio secrets through env_vars. No secret reaches argv.
  • Every carried secret is excluded from Codex's model shells via shell_environment_policy. It uses whichever form (filters or legacy exclude) the user's own config across all layers already uses, because mixing the two fails Codex's config load.
• Secret redirection: changing anything about where a server connects (any literal in the entry) forgets its stored secrets.
• A bad or unready server never fails an agent launch. It is dropped with a reason (user-mcp-unavailable toast, journal entry).

Design decisions

The full evidence and rationale are in docs/superpowers/specs/2026-09-22-user-mcp-servers-design.md; see the Revision 2 section for the unified interface.

• Launch-time injection instead of writing provider config.
  • No race with live Claude processes rewriting ~/.claude.json.
  • No codex mcp add table rewrite.
  • A per-agent subset comes free.
• No aggregator/proxy (MetaMCP, 1MCP…). One would break each CLI's native OAuth, rename tools and add a runtime we would have to supervise.
• No new dependency. add-mcp's per-client transform idea was copied, not depended on, because its Codex transform is wrong.
• OAuth is delegated to the CLIs. The edit dialog shows a copyable codex mcp login <name> -c … command and Claude /mcp guidance. Generated secret variable names are deterministic, so Claude's OAuth token key (name|hash(type,url,headers)) stays stable across launches.
• User choices live in the existing override map under user: keys. Every path that already carries per-agent MCP choices (spawn, reload, recovery, undo, provider switch, duplicate, control API) carries them without being re-threaded.

Review

Two adversarial rounds, each with 2 Claude, 1 Grok and 2 OpenCode reviewers; findings files are in the branch's git-ignored tmp/review/. Every valid finding was fixed. Round 1 was mostly secret delivery and editor state; round 2 was mostly the agent tools' authority. Accepted residuals:

• Codex hooks and notify inherit Codex's full environment, including carried secrets. Closing that needs a file-fed wrapper (follow-up).
• Downgrading and re-upgrading resets the per-provider built-in defaults.

Verification

• npx tsc -b: clean. npm run test:contract and check:keybindings: OK.
• Full npm test: 5,756 passed. The 10 failures in the first run were tests pinning the retired commands and the old flat default shape; all are fixed here and re-run green.
• New tests use Beeper's official published snippets as fixtures:
  • importer and validation;
  • translators, including "no token in argv" and "no token in the config file";
  • service resolution rules;
  • SessionManager (dropped servers never fail a launch; a resolver failure is tolerated);
  • the Settings grid, the dialog and the per-agent picker.
• Real binary: codex mcp list --json (codex-cli 0.155.1) parsed the generated overrides for an HTTP server (env_http_headers, auth_status: bearer_token) and a stdio mcp-remote server (env_vars) exactly as intended.
• Not verified against a live Claude process. claude mcp list ignores --mcp-config, and a real check needs a model call. The file uses the same shape as the built-in server's working private config, and was checked against Claude's zod schema and ${VAR} expansion in vendor/claude-code-src.
• The app was not launched (repo rule). The UI is covered by renderer tests only.

Known limitations / follow-ups

• Changes need an agent reload; neither TUI reloads MCP config live.
• User servers are Claude + Codex only. OpenCode and Grok show "not supported yet".
• Claude's persistent disabledMcpServers (set via /mcp in a repo) also applies by name to injected servers.
• Secrets reach the agent's process environment, so the agent's own tools can read them. This is the same as the built-in bearer, and the UI says so.
• Follow-ups: Add from MCP Registry, OpenCode/Grok user servers, workflow subagents, project-scope native listing, Host user-authored MCP servers as Agent Code extensions #244 hosted servers.

Fixes #1143
Refs #244

🤖 Generated with Claude Code