Custom subagents cannot access MCP tools despite docs saying they should

Status Fixed / completed

Maintainer reply None cached

Activity 4 comments · opened Mar 22, 2026 · closed Mar 22, 2026

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

Configure an MCP server in .mcp.json (stdio transport, Node.js server)
Confirm MCP tools work in the main session and in general-purpose agents
Create a custom subagent in .claude/agents/test.md
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

View original on GitHub ↗

4 Comments

yurukusa · 6 months ago

Thorough reproduction. Until this is fixed, a workaround:
Use general-purpose agents instead of custom agents for MCP tasks:
Since general-purpose agents can access MCP tools, you can achieve similar scoping by dispatching from the main session:

Use the Agent tool with subagent_type="general-purpose" and prompt:
"You have access to MCP tool mcp__servername__toolname. Use it to [task]."

The general-purpose agent inherits MCP tools correctly. The downside is you lose the custom agent's frontmatter constraints (model, tools whitelist, etc.).
Alternative: Wrap MCP calls in a bash script
If your MCP server exposes an HTTP/stdio interface, you can call it directly from the custom agent via Bash:

echo '{"method":"tools/call","params":{"name":"your_tool","arguments":{}}}' | node your-mcp-server.js

This bypasses the MCP tool discovery entirely. Not clean, but it works for simple tool calls.
The root issue seems to be that custom agent tool resolution doesn't query MCP servers — only the built-in tool registry. Worth flagging as a regression if this worked in earlier versions.

github-actions[bot] · 6 months ago

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

mmdevelops · 6 months ago

Closing as duplicate of #25200 which describes the same issue (custom agents in .claude/agents/ cannot access MCP tools). We tested six different configurations — all failed identically. Upvoting #25200.