Custom subagents cannot access MCP tools despite docs saying they should

Description

Custom subagents defined in .claude/agents/ cannot access MCP tools under any configuration. The docs at sub-agents#scope-mcp-servers-to-a-subagent state:

By default, subagents inherit all tools from the main conversation, including MCP tools.

In practice, custom subagents always get "No such tool available" for any MCP tool, while general-purpose agents in the same session can access MCP tools without issue.

Reproduction

1. Configure an MCP server in .mcp.json (stdio transport, Node.js server)
2. Confirm MCP tools work in the main session and in general-purpose agents
3. Create a custom subagent in .claude/agents/test.md
4. Spawn it and attempt to call any MCP tool → "No such tool available"

Configurations tested (all failed)

| Attempt | Frontmatter | Result |
|---------|------------|--------|
| 1 | tools: Read, Write, mcp__servername__* | No such tool |
| 2 | mcpServers: [servername] (string reference) | No such tool |
| 3 | Added ToolSearch to tools: | No such tool |
| 4 | Both mcpServers + mcp__* together | No such tool |
| 5 | No tools: field, only disallowedTools: (should inherit all) | No such tool |
| 6 | Inline MCP definition: mcpServers: [{servername: {type: stdio, command: node, args: [...]}}] | No such tool |

Expected behavior

Custom subagents should be able to access MCP tools, either by inheritance (no tools: field) or via mcpServers configuration as documented.

Workaround

Launch as a general-purpose agent (no subagent_type) with the custom agent's instructions in the prompt. General-purpose agents inherit MCP tools correctly.

Environment

• Claude Code (CLI)
• Windows 11
• MCP server: stdio transport, Node.js
• Claude model: Opus 4.6