›_ Claude Code Issues
Claude Code Issues / #13605

[BUG] Custom plugin subagents cannot access MCP tools (built-in agents can)

Status Fixed / completed
Maintainer reply None cached
Workaround ✓ Mentioned in thread ↓
Activity 15 comments · opened Dec 10, 2025 · closed Mar 25, 2026

Preflight Checklist

  • [x] I have searched existing issues and this hasn't been reported yet
  • [x] This is a single bug report (please file separate reports for different bugs)
  • [x] I am using the latest version of Claude Code

What's Wrong?

Custom subagents defined in Claude Code plugins cannot access MCP tools, regardless of how the tools field is configured in the agent definition. Built-in agents like general-purpose DO receive MCP tools, but custom plugin-defined agents do not.

What Should Happen?

When a custom plugin agent specifies MCP tools in its tools field (or omits the field to inherit), those tools should be available to the spawned agent, just as they are for built-in agents.

Error Messages/Logs

Steps to Reproduce

  1. Create a plugin with a custom subagent that needs MCP tools:
~/.claude/plugins/my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── my-agent.md
└── skills/
    └── my-skill/
        └── SKILL.md
  1. Define the agent with MCP tools in agents/my-agent.md:
---
name: my-agent
description: Agent that uses Playwright MCP for UI testing
tools: mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, Read, Grep, Glob
---

# Agent instructions here...
  1. Spawn the agent via Task tool:
Task(
  subagent_type="my-plugin:my-agent",
  prompt="Navigate to http://localhost:5173 and take a snapshot"
)

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.64

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other

Additional Information

What I've Tried

| Configuration | Result |
|---------------|--------|
| tools: mcp__playwright, Read, Grep, Glob | MCP tools not available |
| tools: mcp__playwright__browser_navigate, ... (explicit full names) | MCP tools not available |
| Omitting tools field entirely (should inherit all) | MCP tools not available |

In all cases, the subagent reports that Playwright MCP tools are not in its available function list.

Evidence

The primary agent CAN use MCP tools directly:

mcp__playwright__browser_navigate("http://localhost:5173")  // Works
mcp__playwright__browser_snapshot()  // Works

But when the same tools are requested for a subagent, they're not provided.

Documentation Reference

From https://code.claude.com/docs/en/sub-agents:

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 does not appear to work for custom plugin-defined subagents.

Related Issues

  • #2169 - MCP resources not available for subagents (different but related)
  • #6915 - Allow MCP tools to be available only to subagent (feature request for inverse problem)
  • #13254 - Background subagents cannot access MCP tools (confirmed: run_in_background: false is required)

Impact

This prevents creating specialized subagents for tasks like:

  • UI testing with Playwright (isolating browser context from main conversation)
  • Database operations via MCP
  • Any MCP-based tooling in a dedicated context

Workaround

Use the built-in general-purpose agent type instead of custom plugin agents:

<invoke name="Task">
  <parameter name="subagent_type">general-purpose</parameter>  <!-- Works! -->
  <parameter name="run_in_background">false</parameter>
  <parameter name="prompt">Use mcp__playwright tools to test...</parameter>
</invoke>

This works because built-in agents receive MCP tools, but custom plugin agents do not.

View original on GitHub ↗

15 Comments

rsalus · 7 months ago

Confirm I've also encountered this issue.

levikszabo · 7 months ago

Is this gonna get respolved?

harryjubb-xyme · 7 months ago

Also encountering this issue. It makes it very difficult to take advantage of using subagents for different tasks in plugins, particularly for context-heavy tasks such as using browser tools.

diranged · 7 months ago

It would be great to have some response from the dev team on this...

gilisho · 7 months ago

I could confirm this is the case in version 2.1.20

teppana88 · 7 months ago

I have the same issue. Managed to get working (with v2.1.22) by removing tools: from agent file. Not the real solution but at least agents can use now MCP tools as they inherit configuration from CLAUDE.

johnzfitch · 7 months ago

Additional Context from Related Investigation

While investigating LSP eager loading (#22335), I discovered this issue is part of a broader pattern of subagent/plugin context management problems.

Related Issues Filed

  1. #22335 - LSP plugins spawn eagerly regardless of file types

Workaround Confirmation

Can confirm the workaround mentioned in the original issue works:

Task(
  subagent_type="general-purpose",
  prompt="Use mcp__playwright tools to..."
)

Built-in agents receive MCP tools, custom plugin agents do not. This suggests the tool filtering logic handles built-in agents differently than plugin-defined agents.

Possible Root Cause

The tool injection for subagents appears to have two code paths:

  1. Built-in agents: Receive full tool list including MCP tools
  2. Plugin agents: Receive filtered tool list that excludes MCP

The tools field in plugin agent frontmatter may not be processed the same way as built-in agent tool lists.

johnzfitch · 7 months ago

Update: Related issues now filed with full cross-links:

  • #22335 - LSP plugins spawn eagerly regardless of file types
  • #22344 - Subagents should receive distilled system prompts tailored to their role
  • #22345 - Plugin skills don't support disable-model-invocation like user skills do

All four issues point to systemic problems with subagent/plugin context management.

johnzfitch · 7 months ago

📊 Cumulative Impact Analysis

This issue is part of a broader investigation into subagent/plugin context management. Here's the full picture:

The Four Issues

┌────────────────────────────────────────────────────────────┐
│                 SUBAGENT/PLUGIN OVERHEAD                   │
├──────────────┬─────────────────────────────────────────────┤
│   #22335     │ LSP Eager Loading                           │
│   (Resource) │ ~480MB RAM, 6 idle processes                │
├──────────────┼─────────────────────────────────────────────┤
│   #22344     │ Subagent Prompt Bloat                       │
│   (Tokens)   │ ~12K extra per spawn → ~66K/session         │
├──────────────┼─────────────────────────────────────────────┤
│   #22345     │ Plugin Skill Overhead                       │
│   (Tokens)   │ ~4.4K per request → ~220K/session           │
├──────────────┼─────────────────────────────────────────────┤
│   #13605     │ Plugin MCP Tools (this issue)               │
│   (Function) │ Blocks plugin subagent workflows            │
└──────────────┴─────────────────────────────────────────────┘

Why This Issue Matters Most

The other issues are optimization - this one is functionality:

| Without this fix | Impact |
|-----------------|--------|
| Can't isolate MCP context | Browser state bleeds into main conversation |
| Can't create specialized agents | No DB agent, no UI testing agent |
| Workaround required | Must use general-purpose for everything |

Combined Session Cost

| Source | Tokens | Fixable? |
|--------|--------|----------|
| Subagent bloat (#22344) | ~66K | ✓ Optimization |
| Plugin overhead (#22345) | ~220K | ✓ Optimization |
| MCP workaround (this) | +~30K* | ✓ This fix |
| Total | ~316K | |

*Estimated extra tokens from using general-purpose instead of focused plugin agents

---

Related issues: #22335, #22344, #22345

awsamuel · 6 months ago

Adding a data point: I'm seeing this same MCP tool loss with a simple skill that does NOT use context: fork or subagents.

My setup:

  • Skill defined in ~/.claude/skills/MyCustomSkill/skill.md
  • Frontmatter is just name and description - no context: fork, no agent configuration
  • Coda MCP configured in claude_desktop_config.json and works in Chat mode

What works vs doesn't when skill is invoked:

| Tool Type | Available? |
|-----------|-----------|
| Built-in (Bash, Read, Write, Glob, Grep) | ✅ Yes |
| mcp__Claude_in_Chrome__* | ✅ Yes |
| mcp__mcp-registry__* | ✅ Yes |
| mcp__coda__* | ❌ No |

The pattern:

  • Claude Desktop Chat mode: Coda MCP ✅
  • Claude Desktop Cowork mode: Coda MCP ❌
  • Claude Code (no skill): Coda MCP ✅
  • Claude Code (with /viv skill): Coda MCP ❌

This suggests the bug may be broader than subagents - simple skill injection also loses us

[memo written by MyCustomSkill]

dergachoff · 6 months ago

Has anyone tested if this fix in 2.1.30 resolved this issue?
_Fixed subagents not being able to access SDK-provided MCP tools because they were not synced to the shared application state_

juliettefournier-econ · 6 months ago

I'm also encountering this bug.

johnzfitch · 6 months ago

Maybe claude code could use a bit of a refactor. Plugins seem like the best place to start over from.

verveguy · 6 months ago

Confirmed fixed in @anthropic-ai/claude-agent-sdk@0.2.63 (Claude Code 2.1.30+).

We tested this with a standalone program that:

  1. Configured an Atlassian MCP server (type: "http", url: https://mcp.atlassian.com/v1/mcp)
  2. Created a custom subagent with tools including mcp__atlassian__*
  3. Asked both the main agent and the custom subagent to list Confluence spaces

Result: Both returned identical, real Confluence data. The custom subagent successfully called MCP tools — no hallucination.

The key requirements:

  • SDK version >=0.2.63
  • Custom agent must declare MCP tools in its tools configuration (e.g., mcp__atlassian__*)
  • MCP server must be configured at the top-level client

This answers @rlichtenwalter's question — yes, the fix in 2.1.30 does resolve this issue.

github-actions[bot] · 4 months ago

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.

Related Claude Code issues

Matched on shared title terms, labels, topic and reported release — ranked so issues with real discussion come first.

Browse by topic

This issue appears in the ranked issue list on this topic page, alongside a backlog trend for the whole topic.

MCP server connection issues →

Browse all Claude Code issue topics →