Feature Request: Agent-Scoped MCP Servers to Prevent Context Window Overflow

Hey, this is a really well-thought-out feature request. I completely agree that as you add more MCP servers, the context window for the main agent can get incredibly cluttered. Your proposed solution seems like a perfect way to handle this.

I was just digging through the docs to see what's possible today, and it looks like you've accurately described the current limitation.

Based on the Subagents documentation (en/docs/claude-code/sub-agents), it seems the current implementation for tool management is:

tools: Comma-separated list of specific tools. If omitted, inherits all tools from the main thread.

And it specifically mentions:

MCP Tools: Subagents can access MCP tools from configured MCP servers. When the tools field is omitted, subagents inherit all MCP tools available to the main thread.

This confirms your point – it's either all or nothing, or you have to manually list every single tool name. There's no way to scope an entire MCP server connection to just one agent.

Potential (but clunky) Workaround

For now, the closest you could probably get to your goal is a two-step process:

1. Define all your MCP servers at the project level in .claude/mcp.json so they're available.
2. For each specialized agent, like your sonar-agent, you would have to manually list every tool from that server in the frontmatter to restrict its context.

For your sonar-agent.md:

---
name: sonar-agent
description: Code quality analysis agent
tools: mcp__sonarqube__tool1, mcp__sonarqube__tool2, mcp__sonarqube__tool3 # Manually list all tools
---

# SonarQube Analysis Agent
...

This would at least prevent the SonarQube tools from polluting the context of other agents (assuming they also have explicit tools lists), but it's not nearly as clean or self-contained as your proposal. The server configuration is still separate, and you have to manually maintain the tool list.

That said, I'm a huge fan of your idea to put the mcpServers block directly in the agent's markdown file. It makes the agent truly self-contained and is a much more scalable solution.

Fingers crossed the dev team sees this and considers it for a future release! It would be a massive improvement for anyone building out a serious suite of specialized agents.

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

This is still a big request!

Like mentioned in #14722, it would be fabulous to have Agent-scoped MCP servers that are only activated inside the sub-agent's context. The use-case that got me to this issue is being able to access the Linear MCP only inside a Linear sub-agent I would want to invoke.

Problems I oversee:

• OAuth for the MCP server would be required. Given sub-agents are opaque, this will need to be handled appropriately.
• Choice of tools: If I want to create a linear exploration agent, ideally I would only want linear MCP tools and not want CRUD tools to be enabled. Perhaps the tools: option could be a way to do it.

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

This issue was closed incorrectly despite recent human comments. This behavior of the bot is reported at https://github.com/anthropics/claude-code/issues/16497. Please upvote that issue, so maybe it gets noticed.

@marcindulak Done, upvoted

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.