Subagent MCP Scoping - Claude Code

MCP scoping lets you expose a given MCP server only to the subagents that should see it. The main session - and other subagents - don't even know it exists.

What it does

You declare the MCP servers a subagent has access to in its frontmatter. Other agents and the main session operate without those tools loaded. This is how you keep a database-writing MCP out of the researcher role, or a secrets-access MCP limited to a single privileged agent.

When to use it

• Isolating sensitive MCP servers to a narrow set of roles.
• Reducing context overhead by not loading irrelevant MCP tools in every agent.
• Building specialist agents that pair naturally with specific integrations.
• Team setups where different roles should see different data.

Gotchas

• Scoping is enforced at load time. If you change scopes mid-session, restart.
• Unknown MCP server names in frontmatter fail silently. Double-check spelling.
• Don't rely on scoping alone for secrets - combine with network and auth boundaries.

Official docs: https://code.claude.com/docs/en/sub-agents.md#scope-mcp-servers-to-a-subagent