Implement Agent-Scoped MCP Configuration with Strict Isolation

I'm just verifying that we're discussing the same issue. You want MCP Servers that are scoped for a single agent. such as shown below

claude mcp add --scope agent=my-superduper-agent ...mcp server details

Then only the my-superduper-agent has access to the tools of that mcp server?

I'm just verifying that we're discussing the same issue. You want MCP Servers that are scoped for a single agent. such as shown below `` claude mcp add --scope agent=my-superduper-agent ...mcp server details `` Then only the my-superduper-agent has access to the tools of that mcp server?

That's right. But pivotally the main thread / agent who not only can't use it but has no knowledge it exists.

Right now the main agent has to be exposed to every mcp added which I don't want.

This isn't permissions either , it should simply have no knowledge of the mcp.

I also have a similar need, I hope that a certain MCP tool will only expose subagents to avoid the main agents being misled by these MCP tools.

Currently, the alternative solution I can think of is to create a sub-agent that doesn't inherit specific MCP tools, and directly specify in the main agent to let this sub-agent work in place of the main agent. But it seems like subagents cannot create another subagents? (no Task tool)

This could also be accomplished by allowing users to set any agent as the primary agent when they start Claude. With that agent having its own tool scope in its config.

this should work without any changes to the primary agent. any sub-agent should have its own MCP config, so the context window of the main agent does get filled out with stuff the main agent never uses. if you then start claude with any specific agent, that´s up to you.

I agree that configuring MCP Servers agent level (with current support for tool limits) would be a great way to control context size issues.
The main CC system should not be aware of any agent scoped MCP servers due to how much context they use up even when they are NOT being used (just to setup config).

I agree that configuring MCP Servers agent level (with current support for tool limits) would be a great way to control context size issues. The main CC system should not be aware of any agent scoped MCP servers due to how much context they use up even when they are NOT being used (just to setup config).

yes exactly the whole purpose of subagents is to help with context control. MCP tool call descriptions take up a significant amount of context every single session when this simply should be optional / possible to offload to a specific subagent.

You can also make agents scoped to specific mcps and specific tools for those selected mcps. This way, for example, a typescript agent will only have access to context7 and playwrite, while a sql agent has access to only database read queries—whatever the user defines.

Similar to the allowed tools options.

I'm just verifying that we're discussing the same issue. You want MCP Servers that are scoped for a single agent. such as shown below `` claude mcp add --scope agent=my-superduper-agent ...mcp server details `` Then only the my-superduper-agent has access to the tools of that mcp server?

I would also like to suggest the ability to add an mcp with an empty agent scope so that it can be added, but no agent picks it up for use right away.

claude mcp add --scope agent   ...mcp server details

Then in the agent config menu (from /agents in CC), add a the ability to turn on/off each of the mcp servers that are either available to the main agent or in the pool of agent scoped mcp servers.

Also, I am a really big fan of the idea of being able to switch persona to that of any agent you have defined as others have mentioned...so many times I have wished I could interactively work with a configured agent.

As long as the main context thread has an idea of what each MCP should be used (some context), then they don't need to necessarily have the full context of every MCP and what the full details are, they would then be able to delegate to subagents who could have the full MCP context. This would allow us to have many MCPs that can be useful in niche cases, without fully polluting the scope. I downloaded a few useful common MCPs and ended up with 40k context used in MCPs! I removed the ones that are more niche use case, but I still would like to have access to them on occasion.

@christopher-buss

As long as the main context thread has an idea of what each MCP should be used

nope. that´s the whole point: the main thread does not need to know! 😏 that´s the whole idea behind this.
the main thread does not need know that the MCP exists at all.
the main thread only needs to know which agents exist and what they are good for.
the agent decides which MCP it uses for the task, not the main thread.

@christopher-buss > As long as the main context thread has an idea of what each MCP should be used nope. that´s the whole point: the main thread does not need to know! 😏 that´s the whole idea behind this. the main thread does not need know that the MCP exists at all. the main thread only needs to know which agents exist and what they are good for. the agent decides which MCP it uses for the task, not the main thread.

Agreed, If main thread known of some mcp tools, it may confused itself even with configuration of no permission on this mcp tools

@christopher-buss > As long as the main context thread has an idea of what each MCP should be used nope. that´s the whole point: the main thread does not need to know! 😏 that´s the whole idea behind this. the main thread does not need know that the MCP exists at all. the main thread only needs to know which agents exist and what they are good for. the agent decides which MCP it uses for the task, not the main thread.

Yes apologise, that would be the solution. The main agent can know about the subagents capabilities and then pass this on to them.

I'm very excited to see people chatting here, I really NEED this feature - with the amount of tools I use across my many agents, they take up 100k worth of context when all loaded in the main agent but I don't need more than 10k of tool descriptions per subagent (yes I have a lot of subagents).

I feel like the simplest way to go about this would be:

1. In settings.json, any tool listed in the deny array is automatically removed from the main agent's context. This would support both removing everything from an MCP and also just specific tools you don't want in context.
2. In any sub agent md file, when excluding the tool list you inherit tool configs from main agent. When you include the list of tools its a full override, and thus you can insert tools here which are ok for the subagent to use but are denied via the main agent settings.json array.

This approach allows the flexibility to still provide SOME tools to the main agent including the built-in ones. For example, I want my main agent to use my google-search tool because I don't need subagent for that task, but I don't want main agent to use my confluence MCP, I just want my product manager subagent to be able to use that and I can manage all the details about how I want it to use confluence in its subagent md and not pollute the main context with that tool config or procedural instructions about that tool.

Plus one on this. this is a needed feature

Yeah, I also think this feature would be great

Please implement this feature! Thank you 😍

I'm happy that so many people now understand the value of this feature, but please stop this useless "I want this too" postings where everybody gets a useless notification - please: just leave a 👍 - thanks 🙏

It feels to me like if this visibility was driven by permissions then you'd solve this issue as well as others.

Github has a very large MCP toolset, and has ways of cutting down the tools, but still you use 20-30k of tokens on a minimal toolset. It'd be nice to be able to add the Github MCP but through permissions be able to allow-list the tools that:

1. you want to be able to use
2. that will occupy context window

Then you don't need to have a seperate concept of MCPs configured for Subagents, you can just have:

.claude/agents/pr_creation_agent.md

tools: mcp_github_create_pull_request

and your main agent might have access to 2-3 other tools but NOT mcp_github_create_pull_request. That way the tools that occupy context are only visible to agents/subagents that explicitly call out that they want to use them. Sorry unsure if I misunderstood the other proposals here.

Plus one

Plus one!

Yes letting agents have there own MCP scope would be great. Why do I have to add a MCP server to my main project or global scope that neither will every use, now context is being taken away from my coding session for information that will never be called for in that session, you should also be able to enable/disable MCP tools from the server tool list in your config just like allow/deny tool list, there may only be one tool in a list of 100 that I want to use but in order to use that one tool I have to have all of them add to my session taking up tokens/context that will never be referenced.

I think everyone agrees we need a better way to utilize context tokens when having too many tools/commands/agents/etc. There are multiple open issues on that topic.

This one (private plugin resources) https://github.com/anthropics/claude-code/issues/10896 IMO looks like it could solve this issue for any kind of resource, not only MCP servers.

Or, the suggestion here https://github.com/anthropics/claude-code/issues/4476#issuecomment-3357294291 by @maschwenk, of using permissions to drive visibility, although that doesn't necessarely cover the componentization part.

Shameless plug as I believe this would solve the MCP token issue so we didn't have to hack around it https://github.com/Orange-County-AI/MCP-DSL

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.

I'm happy that so many people now understand the value of this feature, but please stop this useless "I want this too" postings where everybody gets a useless notification - please: just leave a 👍 - thanks 🙏

Actually, in this repo you NEED to comment to keep the stupid issue open. Normally I'd agree, but you're unfortauntely wrong in this case.

+1 (now watch the bot remove the autoclose label...)

See what I mean?

<img width="962" height="347" alt="Image" src="https://github.com/user-attachments/assets/5dfbd429-ccfd-49d7-9a28-b7b81e587070" />

This issue (#4476) started with the idea of scoping MCP configurations per agent. While I do like that idea, I personally prefer the concept of configuring my servers once, then scoping the permissions of those servers/tools to individual agents. I go into extreme detail on this here. The approach posited there is a sort of "best of both worlds" approach. It would allow you to configure once, then "assign" permissions as needed.

The key to BOTH of these ideas is not polluting any context (main or sub) with unused tools. In the server-scoping concept, agents would be able to include or exclude entire MCP servers from their context. In the permission-scoping concept, there would be more granular control down to the tool level. The reason I prefer the second solution is that it covers all of the same bases, but also solves for edge cases like "I only want a few tools from this bloated server" and "I want this agent to have access to everything except these dangerous tools <...>".

They are both attempts to provide a solution to the same issue: context overload via MCP. Here is a compilation of suggested solutions for this problem (it's not complete, by any means):

• Tool filtering via permissions
• #4380
• My suggested solution with ideas on DX and configuration
• Agent MCP Gateway: @roddutra's solution [source] which is spiritually similar to the Tool Search Tool for the Claude API
• Comments for similar solutions
• @marcdemory-8451's comment
• @maschwenk's comment
• #7289
• Agent-Scoped MCP Server
• [This issue] #4476
• #10896
• #6915

Somewhat Related Issue: #4906

This issue is pushing for the ability to exclude tools when defining MCP servers, which is a great security improvement. Personally I don't think that issue alone would be enough to address the concerns we've all mentioned here.

TLDR:

This is clearly a major issue plaguing Claude Code. There is hope with the Tool Search Tool, but it's not available for CC yet, nor is it a true solution to some of the issues (just hides the bloat behind a non-deterministic search solution).

I personally think we should scope permissions, since it solves all the edge cases and allows for a single configuration file. But honestly, I'd take literally any solution for the time being.

Plus +500.

We've been experiencing context bloat in our monorepo setup lately. Upon investigating it today, it looks like we are using up a whopping 50% of context tokens, ~100K, just on boot of the claude code agent. There are two significant sources of that, one is MCPs which really should be scoped to subagents and therefore not bloating the main thread, and two is that we work in workspaces, and claude seems to double load skills and slash commands from both the workspace and the parent repo.

It'd make a huge difference for us if we could load mcps at the subagent level rather than at the root of the claude code session.

+100 on this one

This would be so good to have mcp defined in a skill to not bloat the context of main agent if he's not using this mcp.

I desperately want to have subagents be specialized users of context heavy mcp tools like playwright or puppeteer or jira, but it's too painful to have so much of my main agents context window taken up by these mcp servers.

This feels like a no brainer and we need this fast, both cause we're wasting tokens, and because we're getting lower quality output due to context bloat

This issue has been open in some form or another since 2025, which is a long time in vibe land. Pretty please make this work?

Beyond the context bloat (which is clearly the biggest pain point — 100K tokens on boot is brutal), there's a security dimension to agent-scoped MCP that I think deserves more attention in the design.

Right now, if you configure a database MCP and a GitHub MCP globally, every subagent can call any tool from both. This means:

1. A code-review subagent can execute database mutations — there's no way to say "this agent only gets github_* tools"
2. Prompt injection through one MCP can escalate to another — if a malicious file in a repo tricks the code-review agent into calling database_execute, the blast radius is every configured MCP, not just the one relevant to the task
3. Credential isolation is impossible — you can't give the "database agent" read-only DB creds and the "deploy agent" write creds, because they're all in the same MCP scope

The allowedTools filter on subagents helps with (1) at the tool level, but it's opt-in and doesn't address (2) or (3). What's really needed is MCP-level scoping, not just tool-level filtering.

A minimal implementation could look like:

{
  "agents": {
    "db-analyst": {
      "mcpServers": ["postgres-readonly"],
      "allowedTools": ["query", "explain"]
    },
    "code-reviewer": {
      "mcpServers": ["github"],
      "allowedTools": ["search_code", "get_file", "create_review"]
    }
  }
}

This maps cleanly to the existing allowedTools pattern but scopes it at the MCP server level — the agent's session simply never connects to MCPs outside its scope. No tool descriptions from out-of-scope servers enter the context, solving both the token bloat and the security boundary in one mechanism.

I've been working on the credential isolation side of this problem in janee — specifically binding secrets to agent identity so that even when two agents share the same MCP server type, they get different credential scopes (e.g., read-only vs. read-write). Happy to share implementation details if useful for the design discussion here.

This is now supported via the mcpServers frontmatter field in agent definitions.

Define MCP servers inline in your subagent's frontmatter and they'll be:

• Connected only when that subagent starts
• Absent from /mcp in the main conversation (the main thread has no knowledge of them)
• Disconnected and cleaned up when the subagent finishes

Example — Playwright scoped to a browser-tester agent only:

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

• playwright:

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

Use the Playwright tools to navigate, screenshot, and interact with pages.
~~~

Inline definitions use the same schema as .mcp.json entries (stdio, http, sse, ws).

To achieve the strict isolation you describe:

• Do not put the server in .mcp.json — define it inline in the agent only
• The main conversation will not list or be able to call these tools

Docs: [sub-agents → Scope MCP servers to a subagent](<https://docs.anthropic.com/en/docs/claude-code/sub-agents#scope-mcp-servers-to-a-subagent>)

Closing as resolved — reopen if this doesn't cover your use case.

Thanks @bcherny! If folks are unsure if it's working, can just call /mcp and it'll show as a agent-scoped MCP. You won't see any mention of the mcp when you go to the /agents view.

<img width="188" height="73" alt="Image" src="https://github.com/user-attachments/assets/cf8a8d95-8a94-4cfe-bdb5-f40e535d6800" />

I've tried a few things but best I can tell interpolation doesn't work?

mcpServers:
  - depot:
      command: 'bun'
      args: ['packages/depot-mcp/src/index.ts']
      env:
        DEPOT_ORGANIZATION_TOKEN: "${DEPOT_ORGANIZATION_TOKEN}"

With claude --debug I can see the MCP server booting and registering tools but can't tell if the interpolation is working.

2026-03-12T02:27:00.290Z [DEBUG] [Agent: frontend] Connected to MCP server 'depot' with 1 tools

I'm gonna guess interpolation doesn't work? Not the biggest deal for a lot of our internal MCPs, but I think there's a few MCPs out there that do rely on secret passing through env vars. Maybe they should just stop doing that.

In terms of frontmatter config, we previously would bootstrap certain MCPs on our users behalf, and manage that in a centralized typescript script where it was nice to be able to define MCP configs once. Having to define potentially the same MCPs inline for each subagent feels a little bit duplicative and hard to manage, but I may be an outlier. Just feels like it'd be nice to conceptually separate the configuration of tools with the activation/visibility in context window.

@bcherny After testing it with Claude Code Plugins (Marketplace), I found three bugs:

---
Bug 1: MCP servers defined in agent files show as errors and never start

If you put MCP server config directly in an agent definition file:

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

Claude Code never actually starts the server. Instead, the agent view shows warning errors like:

⚠ Unrecognized: mcp__plugin_<plugin_name>_<mcp_server_name>__<tool_name>

And claude /mcp doesn't show the server at all. The MCP config in agent files appears to be silently ignored.

---
Bug 2: Forced workaround defeats the purpose of scoping

Because agent-level config doesn't work, the only option right now is to add the MCP server to marketplace.json at the plugin level. But that registers it globally visible and loaded for the root agent, not just the sub-agent. This directly contradicts the whole point of agent-scoped MCP and wastes tokens on tools the root agent will never use.

---
Bug 3: Sub-agents from plugins always fail on the first call

When a plugin provides a sub-agent, calling it by name fails the first time:

Agent type 'support-agent' not found.
Available agents: ..., support-agent:support-agent

Then Claude retries with the fully-qualified plugin-name:agent-name format and succeeds. This is a naming resolution bug. The agent runner should resolve plugin-scoped agents without needing a retry.

---
Thanks for shipping this! Agent-scoped MCP is a big deal for sub-agent use cases. Happy to provide more details or test fixes.

For anyone landing here looking for a solution — I built sub-mcp which does agent-scoped MCP isolation today.

You define MCP profiles in a YAML config, and sub-mcp install generates .claude/agents/*.md files with mcpServers in the frontmatter. Each profile gets its own agent file. The main session never loads the MCP schemas — only the subagent that needs them does, and only for the duration of that task.

Supports isolateMcp: true to prevent inheriting parent MCPs, per-profile model selection, and env var substitution resolved at runtime.

I have this working, but I'm noticing when I have the sub-agent run, it says "N tools used" but the name of the tools called doesn't appear to show? I see the docs say that the primary agent wouldn't see them, but I'd expect that inspecting the verbose transcript of the sub-agent would show what tools it called?

Yes that is what my testing showed. a limitation of the tools being inside the subagent. ctrl+o to expand should show the tool use but it depends on the tool and how it displays. which mcp are you using?

EDIT I've added showing MCP tools used via a custom stop hook!

@bcherny works well. the only issue I see though is that when starting the subagent via claude --agent 'agent name' . the mcp isn't instantiated .

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.