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

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.