feat: Model Context Protocol (MCP) client support

[woai3c]

Summary

Adds end-to-end MCP client support to xc so users can plug community / custom MCP servers (filesystem, git, Sentry, Linear, GitHub, custom in-house tools, …) into the agent loop. Configuration shape is intentionally aligned with Claude Code / Gemini CLI so existing mcpServers snippets migrate verbatim.

// ~/.x-code/config.json
{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] },
    "sentry":     { "url": "https://mcp.sentry.dev" }
  }
}

Discovered tools appear to the model as mcp__<server>__<tool> and route through the existing permission / loop-guard / abortSignal pipeline. MCP Resources are surfaced via two built-in tools (listMcpResources / readMcpResource) so they're pulled on demand, not auto-injected into context.

What's in

Transports

• stdio (local subprocess; covers ~90% of community servers)
• Streamable HTTP — optional OAuth 2.1 with automatic token refresh (~/.x-code/mcp-auth.json mode 0600)

Trust & security

• Project-level .x-code/config.json requires explicit consent on first launch (readline-based dialog showing the actual command strings). Trusted paths persist to ~/.x-code/trusted-projects.json.
• Per-tool permission: every MCP tool starts at ask; "always allow" choices persist to ~/.x-code/mcp-permissions.json.
• Plan mode denies all MCP tools (their side effects are opaque to us, so we can't honor plan's read-only invariant otherwise).

Slash commands

Command	Behavior
/mcp / /mcp list	per-server connection status
/mcp tools [server]	list discovered tools
/mcp auth <name>	OAuth flow guidance (auto-triggered at next launch)
/mcp logout <name>	clear stored tokens for one server
/mcp refresh	reminds the user to restart (we intentionally don't hot-reload — see below)

System prompt

Added a {mcpCapabilities} placeholder to BASE_SYSTEM_PROMPT. When no MCP is configured it expands to "", leaving the prompt byte-identical to pre-MCP — preserving prefix-cache hits on OpenAI-compatible providers (DeepSeek, Moonshot, Alibaba, etc.). When MCP is active, a ## MCP Tools section is appended.

Design decisions worth flagging

• Frozen registry, no hot-reload. Same constraint as sub-agents (CLAUDE.md). /mcp refresh doesn't actually rebuild the registry in-place — it prints "restart to apply" — because mid-session changes would force systemPromptCache to invalidate, and OpenAI-compatible providers' prefix caches would miss for the next API call. Codex/Gemini take the same line; only Claude Code (Anthropic-only) auto-watches the config file.
• MCP tools are dispatched manually, not via the AI SDK's execute() path. They're declared without execute, so processToolCalls gets them in result.toolCalls and can gate every call through applyLoopGuard + the MCP permission store + abortSignal threading — same pattern as shell/writeFile/edit.
• Tool name mangling: mcp__<server>__<tool>, sanitized + truncated to 64 chars + collision-resolved with a hash suffix. Picked __ (double underscore) over _ to avoid colliding with common server tool names like read_file.
• OAuth tokens stored as 0600 file, not OS keychain. Linux keychain (libsecret/dbus) availability is too uneven across distros for a v1 default; the file lives under ~/.x-code so practical leak surface is bounded to the same user.

What's NOT in (intentional)

• MCP Prompts → slash commands. Almost no community server actually exposes prompts; dynamic slash registration would add real complexity to App.tsx's flat-switch dispatch.
• MCP sampling. Niche; rarely wired up by server authors.
• Hot-reload of mcpServers config. See above.
• tmp/mcp-implementation-plan.md — kept out of the commit because tmp/ is gitignored; was an interactive design artifact, not durable docs.

Test plan

• pnpm typecheck — clean
• pnpm lint — clean (one pre-existing unrelated warning)
• pnpm test — 434 passing (45 new in 6 MCP files, the rest unchanged)
  • mcp-name-mangling.test.ts (7) — sanitize / truncation / collision resolution
  • mcp-expand-env.test.ts (8) — ${VAR} / ${VAR:-default} / missing-var error
  • mcp-config-schema.test.ts (9) — stdio / http / both-fields / neither-field paths
  • mcp-trust.test.ts (11) — persistence, path normalization, dialog branching
  • mcp-permissions.test.ts (6) — session vs persisted, atomic write, sort order
  • mcp-integration.test.ts (4) — real child process implementing the protocol; connect → listTools → callTool → readResource → close
• pnpm build — clean
• pnpm test:e2e --list — new scenario 24-mcp-stdio auto-discovered

Not yet run (requires API key + token spend, deferred to reviewer or CI):

• pnpm test:e2e --filter mcp — drives xc -p against an inline mock MCP server, asserts the model quotes a random server-stamped marker (catches "model didn't actually wait for the tool result")
• Manual smoke: install @modelcontextprotocol/server-filesystem, declare it in mcpServers, ask the model to read a file via it
• Manual OAuth: point at a real OAuth-protected server (e.g. Sentry), verify browser opens + token persists

Files changed

+1,700 / -2  across 31 files

• New: packages/core/src/mcp/ (14 files: types, schema, env expansion, name mangling, client, registry, loader, trust, permissions, tool-bridge, resources + oauth/{provider,callback-server,token-storage}.ts)
• Modified: core/src/{agent/loop.ts, agent/system-prompt.ts, agent/tool-execution.ts, config/index.ts, types/index.ts, index.ts}, cli/src/{index.ts, ui/components/App.tsx}
• Tests: 6 new vitest files + 1 e2e scenario + 1 fixture (mock-mcp-server.mjs)
• Dep: @modelcontextprotocol/sdk@^1.29.0