Allow MCP tools to be available only to subagent

I have MCP tools that I use with frequency that I do want generally polluting the context of every chat. Playwright is a great example where the main chat should be able to give instructions to a subagent to use the tools without polluting the context of the main chat with all of the playwright MCP tool calls.
The issue is that when I do this the playwright tools are still available to the main agent, but the main agent should never use these tools directly and they take up precious space in the context window.

This is a feature request to allow for configuring whether tools or entire MCP servers are available to the main agent while allowing them to be enabled for subagents.

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.

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

+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:

---
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.

Navigation Menu

Repository navigation

Allow MCP tools to be available only to subagent #6915

64 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Allow MCP tools to be available only to subagent #6915

Description

Activity

coygeek commented on Aug 31, 2025

leourbina commented on Sep 1, 2025

zen0wu commented on Sep 4, 2025

Layvier commented on Sep 5, 2025

attilaveres commented on Sep 10, 2025

msokolnickiitt commented on Sep 11, 2025

andrewleech commented on Sep 15, 2025

mikewrather commented on Sep 16, 2025

kingsonlo commented on Sep 19, 2025

christophercolumbusdog commented on Sep 25, 2025

cosinusalpha commented on Oct 9, 2025

PaulRBerg commented on Oct 10, 2025

64 remaining items

emil45 commented on Feb 7, 2026

okohub commented on Feb 8, 2026

janukobytsch commented on Feb 22, 2026

sylv-io commented on Feb 22, 2026

swally3216 commented on Feb 25, 2026

abl030 commented on Feb 26, 2026

danielholbling commented on Mar 5, 2026

Dave-London commented on Mar 7, 2026

willyw0nk4 commented on Mar 10, 2026

bcherny commented on Mar 11, 2026

2jfs904judsw20600jikn613d0dookl23jsig commented on Mar 11, 2026

dev-boz commented on Mar 16, 2026

github-actions commented on Mar 23, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions