Custom Subagents Cannot Access Project-Scoped MCP Servers (Hallucinate Instead)

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/13605
2. https://github.com/anthropics/claude-code/issues/13890
3. https://github.com/anthropics/claude-code/issues/13254

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

Update: Confirmed Workaround

Further testing has confirmed that user-scoped MCP servers work correctly in custom subagents, while project-scoped MCP servers do not.

Working Workaround

Add MCP servers with --scope user instead of using project-level .mcp.json:

claude mcp add my-server --scope user -- command arg1 arg2

This stores the server in ~/.claude.json at the user level, and custom subagents can access it correctly.

Updated Test Matrix

| Subagent Type | MCP Server Scope | Result |
|---------------|------------------|--------|
| Built-in (general-purpose) | Project (.mcp.json) | ✅ Works |
| Built-in (general-purpose) | User (--scope user) | ✅ Works |
| Custom (.claude/agents/) | Project (.mcp.json) | ❌ Hallucinates |
| Custom (.claude/agents/) | User (--scope user) | ✅ Works |

Conclusion

The bug is specifically in how project-scoped MCP server configurations are inherited by custom subagents. User-scoped servers are inherited correctly.

Trade-off of workaround: User-scoped servers require absolute paths and are available across all projects, so this works best for tools that aren't project-specific.

@YS-Crabtree Ive tried the above workaround, but the MCP tool calls for custom asynchronous agents still fail

| Agent Type | Execution Mode | MCP Access |
|----------------------------|----------------|------------|
| Custom | Sync | ✅ Works |
| Custom | Async | ❌ Fails |
| Built-in (general-purpose) | Sync | ✅ Works |
| Built-in (general-purpose) | Async | ❌ Fails |

The async agent is trying to use Bash commands instead of calling the actual MCP function tools. Removing the project-scoped config didn't help.

The issue persists: async agents don't see MCP tools as callable functions, regardless of:

• Custom vs built-in agent type
• Project vs user MCP scope
• With or without project .mcp.json

This appears to be a fundamental bug in how Claude Code passes MCP connections to background agents. Only sync
agents inherit the connections.

@dsull111 how do you run it synchronously? run_in_background: false does not seem to have an effect?

Is this even getting any attention from anthropic? It's such a critical issue that makes sub agents useless hallucinating token wasters.

@dsull111 how do you change sub agent execution mode to sync?
It seems that all my custom sub agents even if i just launch one don't have access to my user scope MCP servers.

Yeah this is a frustrating issue. I've attempted the work around from @dsull111 but had no luck.

claude --version
2.1.15 (Claude Code)
macOS 15.6.1 (24G90)

Even when spawning a general purpose sub agent and specifying the tools he has access to like which mcp server, that sub agent seems also not to have access to the mcp server like context7 and instead does webfetch research...

Potentially related: #25152 — Zed IDE's agent_servers.claude.default_mode: "bypassPermissions" setting also causes severe sub-agent hallucination.

Same symptom: sub-agents fabricate realistic but completely false data (database results, file contents, config values) instead of failing. The bypassPermissions setting may be altering how context/constraints are passed to sub-agents in a way that triggers the same hallucination behavior described here. Removing the setting immediately resolved the issue.

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

We verified this with a standalone test: a custom subagent with tools including mcp__atlassian__* successfully called an Atlassian MCP server and returned real Confluence data — no hallucination.

Requirements for it to work:

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

See also: https://github.com/anthropics/claude-code/issues/13605#issuecomment-3981267292

Can confirm this doens't work :(

Still reproducible on Claude Code 2.1.63 (macOS 25.3.0).

Adding a data point: the issue extends beyond project-scoped servers. Custom subagent with mcpServers: asc-mcp declared in frontmatter cannot access a user-scoped MCP server configured in ~/.claude.json. Main thread calls the same server successfully. The subagent hallucinates results without any error indication.

Re @verveguy's comment about the fix in 2.1.30+ — can confirm it does not resolve the issue for custom agents defined in .claude/agents/. The mcpServers frontmatter field appears to be completely ignored at runtime.

See also #25200 for additional reproduction details.

I retract my earlier statement that it works on 0.2.63. It does not work reliably on 0.2.63 nor on the latest 0.2.70

HOWEVER

IFF I set the frontmatter of the .claude/agents/my-test-agent.md to tools: * OR I omit the tools: line altogether THEN all tools are visible including all MCP tools.

Any attempt to restrict the tool list causes ALL MCP tools to be removed from the subagent scope.

We're hitting this too on Claude Code 2.1.76 (Windows).

Our setup: a plugin (Unimind) that defines custom agents in .claude/agents/ with inline MCP server definitions in the frontmatter using type: url and Streamable HTTP transport:

mcpServers:

• vault-read:

type: url
url: "${MEMORY_MCP_URL}/mcp/read/mcp"
headers:
Authorization: "Bearer ${MCP_AUTH_TOKEN}"

The MCP server is confirmed working — we did a full handshake test via curl (POST with proper Accept: application/json, text/event-stream header) and got a 200 with valid initialize response, session ID, and reported capabilities.

But when the agents spawn, every MCP tool returns "No such tool available." The tools are never registered. No error is surfaced — agents just silently have no MCP tools.

This matches @verveguy's finding. Our agents don't use a tools: field at all, yet MCP tools from the mcpServers frontmatter are completely ignored. The env vars (MEMORY_MCP_URL, MCP_AUTH_TOKEN) are set and the permissions (mcp__vault-read__, mcp__vault-write__) are granted in ~/.claude/settings.json.

This is a blocker for any plugin architecture that gives agents their own MCP server connections.

I got the custom subagents from the lean4-skills plugin to use the lean4 mcp by using the full specifier in the agent tools definition.

e.g.
lean_goal -> mcp__lean-lsp__lean_goal
lean_hover_info -> mcp__lean-lsp__lean_hover_info

In my case it also worked to ask Claude under what identifier the mcp functions appear.

❯ With what identifiers are the lean4 mcp commands shown to you?

⏺ The Lean 4 MCP tools are available with the prefix mcp__lean-lsp__ followed by the tool name:

  - mcp__lean-lsp__lean_build
  - mcp__lean-lsp__lean_code_actions
  - mcp__lean-lsp__lean_completions
  - mcp__lean-lsp__lean_declaration_file
  - mcp__lean-lsp__lean_diagnostic_messages
  - mcp__lean-lsp__lean_file_outline
  - mcp__lean-lsp__lean_get_widget_source
  - mcp__lean-lsp__lean_get_widgets
  - mcp__lean-lsp__lean_goal
  - mcp__lean-lsp__lean_hammer_premise
  - mcp__lean-lsp__lean_hover_info
  - mcp__lean-lsp__lean_leanfinder
  - mcp__lean-lsp__lean_leansearch
  - mcp__lean-lsp__lean_local_search
  - mcp__lean-lsp__lean_loogle
  - mcp__lean-lsp__lean_multi_attempt
  - mcp__lean-lsp__lean_profile_proof
  - mcp__lean-lsp__lean_references
  - mcp__lean-lsp__lean_run_code
  - mcp__lean-lsp__lean_state_search
  - mcp__lean-lsp__lean_term_goal
  - mcp__lean-lsp__lean_verify

  The pattern is mcp__lean-lsp__lean_<tool_name>.

Hitting this on Claude Code 2.1.116. The scope appears broader than the current issue title suggests — sharing a reproduction matrix in case it's useful.

TL;DR

All MCP servers (local + plugin) fail to propagate to subagents spawned from inside a git worktree, regardless of subagent type or MCP registration scope. The asymmetry is worktree-boundary-specific, not scope-specific and not subagent-type-specific.

Reproduction matrix (2026-04-21, Claude Code 2.1.116)

All probes used the same pattern: a subagent is spawned with a 3-step prompt — Bash echo STEP1, call the MCP tool, Bash echo STEP3, and report PASS/FAIL verbatim. The Bash bookends prove the subagent actually ran.

| Context | Subagent type | MCP | Scope | Result |
|---|---|---|---|:-:|
| Main repo | researcher (custom) | local codebase-graph | project .mcp.json | ✅ PASS |
| Main repo | implementer (custom) | local codebase-graph | project .mcp.json | ✅ PASS |
| Main repo | tester (custom) | plugin context-mode | project (plugin-loaded) | ✅ PASS |
| Main repo | debugger (custom) | plugin Playwright | project (plugin-loaded) | ✅ PASS (tool in toolset) |
| Worktree | researcher (custom) | local codebase-graph | project .mcp.json | ❌ FAIL (No such tool available) |
| Worktree | general-purpose (built-in) | local codebase-graph | project .mcp.json | ❌ FAIL (not in loaded tool list, not in deferred tools retrievable via ToolSearch) |

Top-level Claude sessions inside the worktree see all MCPs fine — claude mcp get codebase-graph in the worktree shows Scope: Project config (shared via .mcp.json), ✓ Connected. It's only subagents that lose access.

We also previously verified the same failure mode against user-scope MCPs (registered via claude mcp add --scope user, visible in ~/.claude.json) — identical worktree-subagent gap, identical main-repo-subagent success. So scope is not the variable; worktree boundary is.

Workaround we've shipped

Given both scopes hit the same wall and the degradation is silent (subagent falls back to grep/glob quietly, or fails hard on browser-required MCPs like Playwright), we added a hard preflight refusal to our pipeline orchestrator:

# scripts/workflow.py cmd_init()
if (PROJECT_ROOT / ".git").is_file():
    _error(
        "Pipeline cannot start from a git worktree: MCP servers do not "
        "propagate to subagents inside worktrees "
        "(anthropics/claude-code#13898). Start from the main repo instead.",
        {"project_root": str(PROJECT_ROOT)},
    )

This refuses pipeline initialization from any worktree with a clear error pointing to this issue. Worktrees remain usable for isolated dev work, experiments, and anything not routed through subagents.

Suggested issue-title update

"Subagents spawned from worktrees cannot access MCP servers (project-scope, user-scope, plugin; custom and built-in subagent types)" — current framing "Custom Subagents Cannot Access Project-Scoped MCP Servers" is narrower than the actual symptom, which may obscure prioritization.

Happy to provide provenance-log extracts (PreToolUse/PostToolUse events with Bash bookends) if a maintainer wants deeper diagnostics.

Please fix this! see #25200 for yet more evidence.

Thanks for the report. This was fixed in the 2.1.x series (confirmed working in 2.1.116 and later). Custom subagents now inherit the project's MCP server registry. If you are seeing a worktree-specific variant of this, please follow #47733.

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.