Allow MCP tools to be available only to subagent

Hey,

This is a fantastic feature request, and something I've run into myself. It's a great point that specialized tools, especially verbose ones managed via MCP, can really clutter up the main agent's context when you only ever intend to delegate tasks to a subagent.

From my understanding of the current implementation, based on the Subagents documentation, a subagent's toolset is defined by the tools property in its configuration file. If that property is omitted, the subagent inherits all of the main agent's tools. If it's specified, the subagent gets a subset of the main agent's tools. There doesn't seem to be a way to do the inverse—to make a tool available exclusively to a subagent but hidden from the main agent.

Your point about preserving precious context space is the key issue here. Having all those Playwright tool definitions loaded for the main agent, which will never (and should never) use them, is inefficient.

I think a configuration flag for this would be the perfect solution. Maybe something in the claude mcp add command or within the .mcp.json file, like a flag subagentOnly: true. This would prevent the tool from being exposed to the main agent's context but would keep it available for any subagents that are configured to use it.

Definitely adding a +1 to this. It would be a huge improvement for building more complex, modular agentic workflows.

+1 on this - I'm running into the exact same thing. I use the github MCP server for a reviewer subagent, however it consumes ~30k tokens, which is excessive for being constantly enabled. It would be great to just enable it for the subagent.

<img width="524" height="273" alt="Image" src="https://github.com/user-attachments/assets/5b37e175-afa0-4ece-8ac8-c2eca356ab80" />

Big plus! This will make so much room for the main agents context window

I think this is absolutely needed. Being able to fully control the initial context of subagents is essential in my opinion, MCPs are part of it

I've been trying to implement this on my own and I'm honestly surprised there's no support for it out of the box.

This is one of the few missing features that I've realized is crucial after you introduced the /context command.

The /context command clearly shows how much unnecessary noise MCP tools add to the main thread when they're only needed for specific agents. Being able to configure MCP exclusively for agents would keep the main context
clean and focused, while still allowing specialized agents to leverage powerful MCP integrations when needed.

Without this feature I've found out better to avoid MCP integration entirely and focus on cli tools I can get an agent to train itself on (updating its own agent md file) to avoid filling the main Claude context window at all.

Without this feature I've found out better to avoid MCP integration entirely and focus on cli tools I can get an agent to train itself on (updating its own agent md file) to avoid filling the main Claude context window at all.

I've found this is a good stop gap approach. From the perspective of keeping the primary agent's context slim, it makes sense to load in specific documentation for cli / api usage within the sub-agent rather than to try and use mcp servers.

Sub-agent delegation is far more powerful and foundational than mcp servers, so the lack of this feature seems to pave over the mcp innovation entirely.

I’ve been running into this as well when trying to use Claude Code with MCP tools. Specifically, I’m attempting to isolate a tool so that only a subagent has access to it. However, the main agent still ends up invoking the tool and polluting the context, which defeats the purpose of separating responsibilities between the main agent and subagents

Completely agree that this would be a highly impactful and desirable feature. Currently, I'm forced to choose between including an MCP that I only use occasionally but impacts my context, or not using the MCP at all. It would be pretty convenient if I could, say, restrict the Playwrite MCP to strictly a Frontend Tester agent and therefore limit the context pollution.

I need this, claude code becomes useless very fast when using playwright-mcp.

Also GitHub MCP takes up a huge share of the default context window; a dedicated GitHub agent would be sick

Second this, granular control of tools per main/subagent would be consistent with Anthropic's latest engineering blog post

Adding my support +1 for this feature.
The current approach is to selectively enable mcp tools before asking or invoking subagents to use them then disabling once its done. for certain activiites it is good enough but definitely forces more Human in the Loop for things that can be configured away (a little human in the loop isn't bad imho)

Facilitating a method for grouping subsets of tools from the server would be very useful too

Thank you @claude for leading the pack.

Strong +1 for this FR too. There's a bunch of different tools that I'd prefer to wrap as MCP servers but I don't want to unnecessarily bloat the context.

+1

It makes a lot of sense to keep specific MCPs pinned only to subagents to keep the main agent's context lean, +1

+1

Sub-agent MCP servers make no sense without this feature.

I've just read this good article about subagents: https://faafospecialist.substack.com/p/vb-04-subagents-from-basic-to-deep

# Key takeaways - Context Management / Context Engineering is critical! - Context Rot: LLM performance degrades as input length increases. - Protect the Main Context at all costs. - Use the File System as Memory to streamline context. - Process for building up useful context: “Explore - Planning - Execute.” - Common Mistake: Using Sub Agents for Implementation. - Sub Agents are an army of useful information collectors! (Context Collector Army) [...] As you can see: None of the agents handle the IMPLEMENTATION itself! All agents now only serve to collect useful information for the Main Context Window of the primary agent (Claude Code). Then, they feed the plans/reports back to the primary agent (Claude Code itself) to begin execution

I feel it would be very useful to have a subagent that uses Serena to explore the project and explain things about it to Claude.

But the context usage of the MCP on the main agent is crazy, so I am also trying to figure out how to enable Serena _only_ for a subagent.

I hope that a solution to this problem doesn't have the same problem the main agent does:

claude mcp add serena -- \
uvx --from git+https://github.com/oraios/serena serena \
start-mcp-server --context ide-assistant --project "$(pwd)"

Claude Code is interactive for a long time before the MCP is ready! Leading to a conversation like this:

> Are you using Serena MCP?

⏺ No, I'm not currently using Serena MCP. I don't see any MCP (Model Context Protocol) servers connected in this session.

MCP-provided tools would appear with an "mcp__" prefix in my available tools. If you'd like to use Serena MCP or any other MCP server with Claude Code, you would need to configure
it in your settings.

Are you looking to set up an MCP server, or were you checking for a specific functionality that Serena MCP provides?

> What about now? Check again

⏺ You're right! Yes, I do have access to Serena MCP. Looking at my available tools, I can see many tools with the mcp__serena__ prefix, including:

• Symbol-based code navigation and editing tools (find_symbol, replace_symbol_body, insert_after_symbol, etc.)
• Semantic search capabilities (search_for_pattern, find_referencing_symbols)
• Code overview tools (get_symbols_overview)
• Memory management for storing project information
• Project management tools

These tools are designed for intelligent, token-efficient code exploration and editing by working with code symbols (classes, methods, functions) rather than just raw text. This
allows me to navigate and modify codebases more precisely.

Sorry for the confusion in my initial response - Serena MCP is indeed active and available for this session!

I worry that in a naive set up of an subagent with mcp, the subagent would start getting to work before it even has the tools you want it to have

My hope is still there

I think the hopes are off because it feels the path forward is to replace subagents with the new sklils thing

Don’t lose hope 😉 Agents help maintain context in long conversations, and skills add the right context at the right time.

I am looking for other tools that manage MCP tools, switch pre-defined profiles, and orchestrate coding agents, precisely because this functionality is not supported. This would obviously take Claude Code to the next level.

I am looking for other tools that manage MCP tools, switch pre-defined profiles, and orchestrate coding agents, precisely because this functionality is not supported. This would obviously take Claude Code to the next level.

Did you already test other tools, any experience to share? 🙂

Did you already test other tools, any experience to share? 🙂

I've tried many other tools, but only two workarounds worked perfectly.

1. Invoke Another Claude Code Instance

Launch another Claude Code instance with a separate MCP config:

1. Write your agent's prompt to .claude/your-agent-prompt.md
2. Create a .claude/.mcp.your-agent.json file containing the MCP configuration for this agent.
3. Create a command in .claude/commands/your-agent.md:

````
---
allowed-tools: Bash(claude:*)
---

Execute command:

claude \
  --dangerously-skip-permissions \
  --mcp-config .claude/.mcp.your-agent.json \
  --strict-mcp-config \
  -p "SYSTEM_INSTRUCTION: @.claude/your-agent-prompt.md \nUSER_INPUT: $ARGUMENTS"

````

1. Try /your-agent What mcp tools do you have?

2. Use Open Code Instead

sst/opencode supports this feature as well as Claude OAuth login.

+1 This is absolutely needed for big projects that need a lot of context space

+1 Starting to really load up on MCPs and despite delegating work to subagents the outer Claude is filled up with a massive tool list that it should never use.

+1 I agree with @BenjaminBenetti

+1 need this working on a team that wants to manage combinations of mcp tools and agents independently

I would also really like to see this! I have MCP agents that the main process should never use taking up 25% of my context uselessly.

Since output-styles feature also deprecated, Anthropic is suggesting to use subagents instead. This is a must have feature. Main claude agent can be easily confused with all of the mcp servers that shouldnt have.

+1 this is a must-have to be able to use subagents properly.

I had basically stopped using MCPs because of this but had enough and decided to build something to fix it, so I'm sharing it here in case it helps anyone else. It's been working well for me with multiple custom agents and across various other tools (eg. Claude Desktop, etc).

What I Built

An Agent MCP Gateway that sits between your agents and downstream MCP servers and filters servers and individual tools based on an access policy per agent or subagent. Instead of loading all tool definitions upfront (that 10k-50k token overhead), it exposes just 3 gateway tools (~1k-2k tokens) no matter how many MCP servers you configure:

• list_servers - see which servers you (the agent/subagent) can access
• get_server_tools - load tools from a specific server when needed (but only the ones the agent has been given access to)
• execute_tool - runs the tool in the downstream server

Then you configure per-agent access rules. My main Claude Code agent sees only those 3 MCP tools but has no access to other servers and tools (just delegates). My research agent only sees search tools (eg. brave-search, context7, crawl4ai). Database agent sees database tools but can't drop tables. Frontend agent has only a small subset of playwright's 23 tools that I specify.

Agents discover tools and their definitions only when they need them instead of having everything loaded upfront. With just some basic hints and instructions in each agent's system prompt, this works perfectly and consumes a tiny amount of tokens in comparison.

I was listening to an Andrej Karpathy interview where he talked about focusing less on memory and more on LLM cognitive capacity. This made me wonder why are we loading everything into system prompts upfront every session?! Let agents discover what they need, when they need it.

The Tradeoffs

This is an opinionated implementation based on what I believe works best for my use-case, and there are also some limitations:

1. Agents self-identify: Claude Code doesn't pass agent/subagent identity to MCP servers. My solution is agents include agent_id in their tool calls. I add a brief instruction to each agent's system prompt (template in the README) and it's worked surprisingly well. Also works in Claude Desktop or any other MCP client with a default agent config via an env var.
2. Principle of least privilege: Zero implicit access. Agents must be explicitly granted access to see servers/tools.
3. On-demand only: Can't dynamically push tool updates because Claude Code doesn't listen to listChanged notifications via the MCP protocol. So the 3 gateway tools are loaded and they control what gets exposed depending on the agent calling it. TBH I prefer this anyway because it makes tools discoverable rather than forcing it in the context window every session.

Links

GitHub: https://github.com/roddutra/agent-mcp-gateway

Notes

I don't think it's perfect for everyone and it still needs some work, but it solved my problem so far. Happy to answer questions if anyone tries it.

I do hope that the per-agent MCP tool configs is added to Claude Code soon, but I also think that making tools discoverable on-demand and just adding brief instructions in the agent's system prompts (hints, not specs) is a much better approach than loading all tools' definitions into context upfront every time.

+1 this is a really critical feature that would provide significant flexibility

We would love this too!

+1 would be helpful!

+1

+1

This is a ctitical feature!

Funny that this still isn’t implemented. Anthropic is paying for unnecessary tokens. They published an article but didn’t provide real examples of bridging existing MCP tools. Code execution isn’t actually needed if you create an agent with a specific subset of MCP servers, and the main agent only has access to the agent’s description. Such a simple fix.

Funny that this still isn’t implemented. Anthropic is paying for unnecessary tokens.

you do realize you're paying for the tokens not anthropic right?

We really need this.

+1 🙏

My workaround is to use mcp-proxy and a skill that explains how to use curl to talk to the mcp-proxy directly, without actually having the MCP server configured in Claude Code. Only the subagent loads this skill, keeping the main context clean.

It is a workaround, but it works (around). More details here, focused on chrome-devtools-mcp but should be applicable to any stdio-based MCP.

There is Tool search tool now, can we please have it in Claude Code?

Hope the Tool Search Tool comes to Claude Code soon, since it’ll be a great way to have a bunch of useful MCPs available at all times.

At the same time, I think allowing subagents to have any MCPs, not just a subset, will still be a very useful capability to have.

I tested the Tool Search Tool in Claude Code using a local API proxy. It works so well that it could replace this feature. While this feature will still be very useful, the Tool Search Tool will ease many use cases people might have related to it.
https://github.com/unsafe9/claude-code-advanced-tool-use

Event ChatGPT supports this idea.

Huge +1. As a long time user of Claude Code, the most fundamental skill for working with it is context management. In the short term, this is the solution. Allowing sub agents only the access they need to a single mcp server at a time to prevent them either running into "the dumb zone" or worse, out of context entirely.

In the long term imo, we need something other than MCP to handle tool management. It just isn't effective when you have something like a Playwright or Github MCP server taking up a huge portion of the context window. I think I had 4 servers running at one point before I clocked that they were taking up a THIRD of my context window leaving maybe 10% of context before performance degrades. That's not a lot of tools in the grand scheme of things so it's obvious that this approach just won't scale in the future.

+1

+1

Without this, I feel like sub agents are simply useless. Being able to move the tools and functionalities out of the context of the main agent is the whole purpose of sub-agents. We need this asap.

+1 here. I couldn't believe that I couldn't give tool access to sub agents!

+1

+1000

For me this ia a bigger important feature. We nees this implementation.

I'm going to be annoying and add another comment. +1

@bcherny what do you think about this? Should we look forward to it?

+100

+100

+1, this would solve a major pain point with current MCP servers

+1

Previously, this feature was essential for enabling various MCP servers, but now we can defer-load tools by setting ENABLE_TOOL_SEARCH=true, so it's no longer necessary to manage the context window. That said, it's still useful for restricting permissions and preloading MCP tools for more flexibility.

Previously, this feature was essential for enabling various MCP servers, but now we can defer-load tools by setting ENABLE_TOOL_SEARCH=true, so it's no longer necessary to manage the context window. That said, it's still useful for restricting permissions and preloading MCP tools for more flexibility.

Thx so much:) Link to related issue: https://github.com/anthropics/claude-code/issues/12836

+101

+102

This is a really basic requirement. With opencode we use dedicated subagents to use MCPs with a large list of tools to avoid polluting the context of the main thread.

This would be super useful as a way to force delegation to a subagent that may have special instructions or context. In my use case, I have a lot of institutional knowledge embedded into the context of an Atlassian subagent, but the main agent sometimes decides to use the tool itself, so it completely misses any of this information, which is often critical.

Claude Code 2.1 added Skill agent + context: fork - Skills can run exclusively in a specific agent:
---
name: skill-bound
agent: agent-executor
context: fork
---

It feels like this could easily be extended to tools.

I bypassed this issue by switching to CLI-based browser tools (like Vercel's agent-browser or my own webctl).
It effectively hides the complexity behind the terminal. The agent does not see Playwright tool definitions in its context, just the CLI output. It's not a native fix for MCP scoping, but it solves the context pollution problem for me right now.

+1

+1

+1

++1 :)

+1

+1

+1

This is very useful if a lot of servers and tools are set up.

+1

+1

+1

+1

+1

+1

Right now this is my absolute most wanted feature. Playwright, as an example, is really useful but a bit too hungry to have enabled by default in the main context window.

Agreed that tool segregation between main agent and subagents would help a lot. One additional angle: even when the right tools are scoped to the right agent, each tool call still returns output that goes into context. Verbose CLI output (builds, test runs, git logs) can easily be thousands of tokens per call.

Pare addresses this side of the problem — MCP servers that return structured JSON instead of raw terminal text, typically 40–95% smaller. So combining tool scoping (this issue) with compact structured output would reduce context pressure from both directions.

+1

This is supported via the mcpServers frontmatter field in agent definitions. You can define an MCP server inline in your subagent config, and it will only be connected when that agent runs (and cleaned up when the agent finishes).

Example — give a browser-tester subagent access to Playwright, without exposing it to the main conversation:

~~~yaml
---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:

• playwright:

type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
---

You are a browser testing agent. Use the Playwright tools to...
~~~

The mcpServers field accepts a list where each entry is either:

• An inline definition ({ serverName: config } like above) — creates a fresh connection scoped to this agent only. Use this when you want the server to be subagent-only.
• A string reference to an existing server name (e.g., - github) — reuses a server already configured in .mcp.json.

To keep an MCP server out of the main conversation entirely, define it inline in the agent rather than in .mcp.json. The subagent gets the tools; the parent conversation does not.

---

Separately, for the context-window concern (verbose MCP tool schemas eating tokens): Claude Code now lazy-loads MCP tool definitions by default when they'd consume a significant portion of the context window. They're loaded on demand via tool search instead of upfront, so leaving servers configured globally no longer carries the same context cost it used to.

Docs incoming.

This is supported via the mcpServers frontmatter field in agent definitions. You can define an MCP server inline in your subagent config, and it will only be connected when that agent runs (and cleaned up when the agent finishes). Example — give a browser-tester subagent access to Playwright, without exposing it to the main conversation: --- name: browser-tester description: Tests features in a real browser using Playwright mcpServers: - playwright: type: stdio command: npx args: ["-y", "@playwright/mcp@latest"] --- You are a browser testing agent. Use the Playwright tools to... The mcpServers field accepts a list where each entry is either: An inline definition ({ serverName: config } like above) — creates a fresh connection scoped to this agent only. Use this when you want the server to be _subagent-only_. A string reference to an existing server name (e.g., - github) — reuses a server already configured in .mcp.json. To keep an MCP server out of the main conversation entirely, define it inline in the agent rather than in .mcp.json. The subagent gets the tools; the parent conversation does not. Separately, for the context-window concern (verbose MCP tool schemas eating tokens): Claude Code now lazy-loads MCP tool definitions by default when they'd consume a significant portion of the context window. They're loaded on demand via tool search instead of upfront, so leaving servers configured globally no longer carries the same context cost it used to. Docs incoming.

Thank you boris!

This is exactly the problem sub-mcp solves.

It generates .claude/agents/*.md files from a profiles config, each with mcpServers in the frontmatter. The main agent runs clean with zero MCP overhead. When it delegates a task, the subagent gets the MCPs it needs, uses them, and the connection dies when the subagent finishes.

Also includes a CLI wrapper for claude -p calls in scripts/CI, and a .claude/rules/ file that gives the main agent a lightweight menu of what profiles are available (~80 tokens).

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.