claude-code - 💡(How to fix) Fix Per-agent MCP server gating (subagents inherit full MCP context)

The problem

Subagents (Agent tool) inherit the parent session's full MCP server set with no ability to opt out. Each subagent invocation opens fresh MCP connections to every configured server and pays the full tools/list + initialize.instructions cost in its own context — even when the agent's task can't possibly use those tools (e.g. an Explore-style search-only agent doesn't need our knowledge-store capture/graph tools).

In our deployment (~50 brain MCP tools, ~30k chars of tools/list), every subagent fan-out duplicates ~7,500 tokens of unused tool context. A 5-way parallel review means ~37k tokens of duplicated MCP context across the spread, on top of each agent's actual work.

Why it's not solvable client-side today

• .mcp.json config is global per-workspace; agents can't opt out of specific servers
• disabledMcpjsonServers setting is workspace-level, not per-agent
• The agent definition file (.claude/agents/<name>.md) has frontmatter for model, tools (built-in tool gating), and description — but no mcpServers allowlist or denylist
• MCP initialize.clientInfo.name is claude-code for both parent and subagents — no agent-type identification, so servers can't auto-discriminate

Proposed shape

Allow agent definitions to declare MCP server scope. Two equivalent shapes:

Option A — frontmatter list:

---
name: reviewer
description: Reviews code...
tools: [Read, Grep, Glob]
mcpServers: []        # disable all MCP for this agent
---

---
name: knowledge-explorer
mcpServers: [brain]   # allow only the brain server
---

Option B — pass-through to MCP server via clientInfo: Send clientInfo.name = "claude-code-agent/reviewer" (or include subagent name in a structured field) on initialize when an MCP connection originates from a subagent. Servers can then apply per-agent profiles server-side without Claude Code having to know about them.

Option A is cleaner UX. Option B is a one-line change in Claude Code that unlocks server-side flexibility without per-agent config sprawl.

Why this matters beyond our use case

Any MCP server with a non-trivial tool surface (GitHub MCP, Notion, databases) incurs the same multiplier. As MCP server adoption grows, this is going to become a routine token-budget problem for users running parallel agents. A client-level fix is much cheaper than every server building its own auto-discrimination.

Workarounds we're using today

• Register multiple MCP server URLs with different scope query strings (?packs=core vs ?packs=all) and toggle via disabledMcpjsonServers per workspace --- clumsy, doesn't help inside a single workspace
• Server-side aggressive defaults to keep tools/list small for everyone, even when some sessions actually need the long tail

Both leave performance on the table. Per-agent gating is the clean fix.

Happy to discuss implementation tradeoffs or contribute a docs PR clarifying the current behavior if useful.