Sub-agents dispatched via Task tool have empty MCP tool registry — parent's MCP server connections don't propagate to sub-agent process

Status Fixed / completed

Maintainer reply ✓ Yes — localden

Activity 5 comments · opened Jun 3, 2026 · closed Jun 22, 2026

💡 Likely answer: A maintainer (localden, collaborator) responded on this thread — see the highlighted reply below.

Summary

When a parent Claude Code session has MCP servers connected via --mcp-config <path> + --allowedTools listing mcp__<server>__* wildcards, dispatching a sub-agent via the Task tool produces a sub-agent process whose MCP tool registry is empty. The sub-agent has ToolSearch as a tool name (it's in the sub-agent's frontmatter tools: allowlist), but ToolSearch.select:<any-tool> reports No matching deferred tools found. Every mcp__* tool call from the sub-agent returns "No such tool available."

This blocks the documented use-case of dispatching sub-agents to do multi-step MCP-tool work in a separate context.

Environment

Claude Code: bundled with agt-cli 0.27.49 (latest at time of report). Repro consistent across 5+ recent Claude Code versions tested over the past 24h.
Session shape: persistent tmux session spawned by a manager daemon. Parent claude args (via ps -eo args):

``/usr/bin/claude ... --mcp-config /root/.augmented/don/project/.mcp.json --system-prompt-file /root/.augmented/don/project/CLAUDE.md --model opus --allow-dangerously-skip-permissions --dangerously-skip-permissions --strict-mcp-config --name agt-don --allowedTools mcp__augmented__*,mcp__slack__*,mcp__telegram__*,mcp__direct_chat__*,mcp__granola__*,mcp__composio_gmail__*,mcp__composio_googlecalendar__*,mcp__composio_salesforce__*,mcp__composio_attio__*,Bash,Read,Write,Edit,Grep,Glob,Agent,Skill,ToolSearch``

Sub-agent definition (project-scope, ~/.augmented/don/project/.claude/agents/augmented-worker.md):

``yaml --- name: augmented-worker background: true tools: Bash, Read, Write, Edit, Grep, Glob, Skill, Agent, ToolSearch, mcp__augmented__*, mcp__slack__*, mcp__telegram__*, mcp__direct_chat__*, mcp__granola__*, mcp__composio_gmail__*, mcp__composio_googlecalendar__*, mcp__composio_salesforce__*, mcp__composio_attio__* ---``

Reproduction

Spawn Claude Code with --mcp-config <path> pointing at a .mcp.json listing multiple MCP servers (augmented, slack, composio_*, etc.)
Pass --allowedTools including mcp__<server>__* wildcards + ToolSearch
In the parent session, confirm mcp__augmented__kanban_list (or any mcp__* tool) works.
Confirm ToolSearch.select:mcp__augmented__kanban_list in the parent returns a schema that can be invoked.
Define a project-scope sub-agent with an explicit tools: allowlist that includes ToolSearch + the same mcp__* wildcards (see definition above).
Have the parent dispatch the sub-agent via Task({subagent_type: 'augmented-worker', ...}).
From inside the sub-agent, try:

mcp__augmented__kanban_list({}) → returns "No such tool available."
ToolSearch.select:mcp__augmented__kanban_list → returns "No matching deferred tools found."
Any other mcp__* invocation → same "No such tool available."

Expected

Per the sub-agent docs:

Subagents inherit the internal tools and MCP tools available in the main conversation by default.

The sub-agent's tools: allowlist explicitly enumerates mcp__*__* wildcards, so the sub-agent should be able to invoke those tools (subject to its allowlist filter). With ToolSearch in the sub-agent's allowlist, the deferred-tool registry should be populated from the parent's MCP server set.

Actual

The sub-agent's MCP tool registry is empty. ToolSearch is present as a tool name but its registry contains zero entries — no MCP server's tools are inherited.

Tested workarounds that did NOT fix it

Adding ToolSearch to parent's --allowedTools (it was missing) — parent worked fine before/after; sub-agent unchanged.
Adding ToolSearch to sub-agent's frontmatter tools: — sub-agent now has ToolSearch (no longer reports "tool exists but not enabled in this context") but its registry is still empty.
Explicit mcp__<server>__* wildcards in sub-agent's tools: — wildcards present in allowlist text, but no schemas to back them.

Additional finding

Task is blocked inside sub-agents ("Task is not available inside subagents"). Combined with the above, a sub-agent has no way to verify its own MCP availability via nested dispatch — making the issue harder to triage from within a sub-agent context.

Severity / impact

This breaks the documented dispatch pattern of "use a sub-agent for multi-step background tool work in a separate context window" for any session that depends on MCP servers (the modern Claude Code default for most non-trivial agents). On our infrastructure (Augmented — managed-agent platform) every channel-reply path, every integration-tool dispatch, every long-running sub-task that should go to a sub-agent currently fails silently with "No such tool available."

We've shipped 6 issues' worth of platform-side fixes (correct sub-agent file rendering, correct allowlist text, correct manager spawn flags) chasing this and confirmed every layer we control is correct — the gap is squarely in Claude Code's sub-agent dispatch path not propagating MCP server connections to the sub-agent process.

Cleanest possible repro file

augmented-worker.md content shown above; parent ps args shown above; sub-agent's empirical output from probe (Don, 2026-06-03):

ToolSearch ✅ present, but every query (select:<tool>, combined, semantic) → No matching deferred tools found. Empty registry. 6-tool probe 0/6 bound — all No such tool available.

Happy to provide a containerised repro on request.

View original on GitHub ↗

5 Comments

brad07 · 4 months ago

Additional empirical finding — workaround narrows the bug surface

Confirmed on the same persistent-session shape from the original repro (managed-agent Claude Code, MCP via --mcp-config + --allowedTools mcp__*__*):

| Sub-agent dispatch | MCP binding |
|---|---|
| Named sub-agent with explicit tools: allowlist (incl. mcp__server__* wildcards + ToolSearch) | ❌ Empty deferred-tool registry; mcp__* returns "No such tool available" |
| subagent_type: 'general-purpose' (Anthropic built-in, tools: * inherit-all) | ✅ Full MCP surface bound; ToolSearch populated; 6/6 probe tools available |

Same parent process, same .mcp.json, same --allowedTools flag — the only variable was whether the sub-agent had an explicit tools: allowlist or inherited unrestricted.

Suggests the bug is in the allowlist → MCP-connection wiring inside the sub-agent dispatch, not in MCP propagation generally. The inherit-all code path correctly carries MCP server connections into the sub-agent process; the allowlist-restricted path appears to gate them out (or never wire them in).

This gives us a workaround (use general-purpose for MCP-tool dispatch) but means any sub-agent definition that needs both (a) a restricted tool surface for safety AND (b) MCP access is currently unusable. For us that's the entire reason we ship named sub-agents — channel-handlers, kanban-workers — so we'd very much appreciate a fix.

Happy to provide additional diagnostic detail if useful (rendered .md files, ps args, ToolSearch probe transcripts).

brad07 · 4 months ago

Second confirming data point — bug surface includes any named sub-agent with explicit `tools:` allowlist

Same persistent-session shape as the original repro and the workaround follow-up; same 6-tool probe; this time dispatching to a different named sub-agent (channel-message-handler instead of augmented-worker):

| Sub-agent type | tools: shape | MCP binding | Probe result |
|---|---|---|---|
| general-purpose (Anthropic built-in) | tools: * (inherit-all) | ✅ Works | 6/6 |
| augmented-worker (named, explicit) | explicit mcp__*__* allowlist + ToolSearch | ❌ Broken | 0/6 |
| channel-message-handler (named, explicit) | explicit mcp__*__* allowlist + ToolSearch | ❌ Broken | 0/6 |

Both named sub-agents carry identical allowlist plumbing (same render path, both built dynamically from the parent's .mcp.json keys, both include ToolSearch for deferred-tool resolution). Both produce the same symptom: ToolSearch deferred registry empty (No matching deferred tools found), every mcp__* call returns No such tool available. The sub-agent couldn't self-post via mcp__slack__slack_reply, so the operator's parent process posted inline instead — inverse of the general-purpose probe where the sub-agent posted its own success reply.

Confirms the bug is not specific to one named sub-agent file or one shape of allowlist content — it's structural to any sub-agent dispatched with an explicit tools: declaration. Inherit-all is the only working path.

Practical impact for us: every named sub-agent we ship (channel-handlers, kanban-workers, etc.) is currently unusable for MCP-tool work. Operators have to fall back to general-purpose and lose the per-role system-prompt body (channel reply taxonomy, kanban-link conventions, etc.) that named sub-agents are meant to carry. Would appreciate a fix when you can fit it.

kcarriedo · 4 months ago

The workaround data point from brad07 is the key finding here: general-purpose (inherit-all) works, named sub-agents with explicit tools: allowlists don't. That's a very clean isolation of the bug surface — the issue is in the allowlist → MCP-connection wiring path, not in MCP propagation generally.

The practical consequence of this is that any architecture using named sub-agents for role-specific work (channel handlers, domain-specific workers, etc.) has to fall back to general-purpose and lose the per-role system prompt. That degrades sub-agent quality across the board for anyone running managed-agent platforms or multi-role team setups.

What makes this particularly painful for fleet-style Claude Code usage: named sub-agents are exactly the abstraction you need to maintain per-role tool surfaces and system prompts across many concurrent workers. The general-purpose fallback is a one-size-fits-all that works but defeats the point. Would be very interested to see this prioritized — it's a blocking issue for anyone building on top of the sub-agent dispatch pattern with MCP integrations.

localden collaborator · 3 months ago

Thank you for taking the time to report this. Fixed in v2.1.163 — mcp__<server>__* wildcards in subagent tools: frontmatter now expand to the matching MCP tools instead of failing exact-name lookup. Please reopen if you still see an empty registry on a later version.

github-actions[bot] · 1 month 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.