claude-code - 💡(How to fix) Fix [FEATURE] Agent-scoped MCP server configuration — allow agents to override or isolate MCP configs via frontmatter

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Agents (both --agent CLI sessions and sub-agents spawned via the Agent tool) cannot define their own MCP server configurations independently from the global/user-level config. The current behavior is:

1. mcpServers in agent frontmatter is additive — it can spin up new servers, but if a server name collides with one already in ~/.claude.json, the global client wins silently. The agent's custom command/args/env are discarded.

2. --agent inherits all global MCP servers — there is no way to launch an agent session with only the MCP servers the agent declares. The agent gets every globally-configured server whether it needs them or not.

Known workarounds

These work for some scenarios but none solve the core problem:

• Give each agent's server a unique name so it doesn't collide with global config — it'll connect with the agent's own command/args as a separate client. Works but fragile, pollutes the global namespace, and requires users to pre-configure every variant.
• --strict-mcp-config --mcp-config <path> — skips the ~/.claude.json merge and uses only the config you pass. Works for --agent CLI but not for sub-agents, and requires maintaining separate JSON config files outside the agent definition.
• CLAUDE_CONFIG_DIR per agent — external launcher scripts that set isolated config directories before exec'ing claude. Heavyweight, requires tooling outside Claude Code, and doesn't help sub-agents within a session.

None of these let an agent definition be self-contained.

Why this matters

Some agent workflows require the same MCP server binary with different arguments per agent. For example:

• A code review agent needs an MCP server configured with --include-tools lint,review while a deployment agent needs the same server with --include-tools deploy,rollback
• A documentation agent needs an MCP server pointed at --paths /docs while a testing agent needs --paths /tests
• An orchestrator spawns specialized sub-agents that each need different tool subsets from the same MCP server, filtered via server-side args

Today, if the user has that MCP server configured globally (common for general-purpose servers), every agent silently gets the global config instead of its own. The agent's specialized args are discarded without warning.

Proposed Solution

Option A: isolatedMcp: true — full MCP isolation

A top-level boolean that opts the agent out of global MCP inheritance entirely. Combined with mcpServers, the agent defines its complete MCP environment.

---
name: deploy-agent
description: Deployment specialist
isolatedMcp: true
mcpServers:
  my-server:
    command: npx
    args: ["my-server", "--include-tools", "deploy,rollback"]
  monitoring:
    command: npx
    args: ["monitoring-mcp"]
---

• isolatedMcp: true means: do NOT inherit global MCP servers — only use what's declared in this agent's mcpServers
• Equivalent to the existing --strict-mcp-config CLI behavior, but declarative within the agent definition
• Enables fully self-contained, distributable agent definitions
• Clear mental model: the agent controls its entire MCP environment

Option B: mcpOverride — agent-level overrides for matching server names

A new top-level frontmatter field that explicitly declares "for these server names, use my config instead of global."

---
name: review-agent
description: Code review specialist
mcpOverride:
  my-server:
    command: npx
    args: ["my-server", "--include-tools", "lint,review", "--context", "/reviews"]
---

• Servers listed in mcpOverride replace the global config for matching names within this agent's session
• mcpServers retains its current additive behavior for new servers
• Useful when the agent needs most global servers but needs to customize one or two

Option C: Both

isolatedMcp for full isolation, mcpOverride for surgical per-server overrides. They serve different use cases — isolation is for "I want to control my entire MCP environment," override is for "I need this one server configured differently."

Design considerations

Precedence model: The simplest mental model for isolation is: the agent's mcpServers is the MCP config, period. No merging, no surprises. For overrides, it's local-wins for matching names (mirroring how project .env overrides global, .npmrc in project overrides user-level, etc.).

Sub-agent scope: Ideally this extends to sub-agents spawned via the Agent tool within a session. Today, sub-agents inherit the parent's MCP clients. An agent definition that declares MCP isolation or overrides should have those apply when spawned as a sub-agent, not just when launched via --agent.

Distributable agents: Full isolation makes agent definitions portable — the agent specifies everything it needs, independent of the user's global MCP setup. This is important for shared agent definitions (e.g., installed from a registry).

Alternative Solutions

1. Just change the precedence — make existing mcpServers frontmatter override (not add to) global config for matching names. Zero schema changes, solves the name collision problem, but doesn't address isolation and changes existing behavior.

2. Server aliasing — allow agents to reference a global server under a different internal name with custom args. Avoids the override question but adds indirection.

3. Extend --strict-mcp-config to frontmatter — a strictMcpConfig: true boolean (matching the existing CLI flag name). Simple, but all-or-nothing and doesn't cover the "override one server" case.

Related Issues

• #25200 — Custom agents cannot use deferred MCP tools (ToolSearch not available). Different root cause but compounds this problem.
• #47118 — Parent MCP server registrations leak into sub-agent tool output. The flip side of the isolation problem.
• #34698 / #44183 — --agent CLI doesn't activate agent's mcpServers on the main thread.
• #37785 — MCP tools not available in spawned sub-agents.
• #24054 — Scoped MCP servers for skills and subagents (closed).

Priority

High - Blocks agent specialization patterns where different agents need different tool configurations from the same MCP server.

Feature Category

MCP server integration / Agent system

Use Case Example

1. User has my-server configured globally in ~/.claude.json with default args
2. User creates ~/.claude/agents/review-agent.md that needs my-server with --include-tools lint,review --context /reviews
3. User creates ~/.claude/agents/deploy-agent.md that needs my-server with --include-tools deploy,rollback
4. User runs claude --agent review-agent — expects review-specific tools
5. Actual: Agent gets the global my-server config. Review-specific args are silently discarded.
6. Expected: Agent's frontmatter overrides global config for my-server. Agent gets review-specific tools as declared.

The same problem occurs when an orchestrator agent spawns these as sub-agents — each sub-agent should get its own MCP server config, not the parent's global config.