[BUG] Background subagents lose ListMcpResourcesTool/ReadMcpResourceTool - MCP resources unreachable from subagents by default

Status Open

Reported on v2.1.226

Maintainer reply None cached

Activity 3 comments · opened Aug 9, 2026

Environment

Claude Code version: 2.1.226
Platform: Linux

Summary

Since subagents run in the background by default (v2.1.198), the background-subagent tool filter keeps every MCP tool but only a fixed allowlist of built-in tools. ListMcpResourcesTool, ReadMcpResourceTool, and ReadMcpResourceDirTool are not on that allowlist, so a background subagent cannot list or read MCP resources at all. An entire MCP feature becomes unreachable from subagents by default, while every tool of the same server -- including ones that execute code -- remains available.

The subagents docs ("Available tools") describe the allowlist, and listing a stripped tool in an agent's tools: frontmatter is documented as silently overridden, so no configuration restores resource access to a background subagent. The only workarounds are running the subagent in the foreground (run_in_background: false), a fork, or resolving resources in the parent and pasting the content into the prompt.

Observed

Main session: the three resource tools are present in the deferred tool list.
Background subagent (subagent_type: general-purpose, tools: *): its deferred_tools_delta attachment contains all 66 mcp__<server>__* tool names and zero occurrences of the three resource tools.
Concrete case: we ship agent-facing documentation as MCP resources (kit:// URIs on a fork of mozilla/firefox-devtools-mcp). A subagent worked for an hour against that server, used its tools throughout, and could never discover or read the resource-served docs. Its own debrief: "I never found a kit:// resource listing -- I have no resource-listing tool exposed."

Expected

A background subagent that keeps a server's MCP tools should also be able to read that server's MCP resources. The resource tools are read-only and no more powerful than WebFetch or Read, both of which are on the background allowlist.

Proposed fix

Add the three MCP resource tools to the background-subagent built-in allowlist. Failing that: document the limitation on the MCP and subagents pages (today the consequence is spelled out only for context: fork skills), and warn when a requested tool is silently stripped (same ask as #80733).

#80733 -- same mechanism, LSP tool
#84093 -- same mechanism, ReportFindings (breaks /code-review's own instructions to its background agent)
#84125 -- its Exhibit A incidentally shows the three resource tools present in the parent session's tool list and absent in the subagent's
#2169 -- older report of the same symptom (closed as stale; predates background-by-default and had a different mechanism)

View original on GitHub ↗

3 Comments

marcorusc · 1 month ago

Stumbled on the very same problem. For now, my workaround is to create and mcp tool that exposes all resources to the sub-agent or expose the resources to the main agent that passes them down to the sub-agents. Hope this gets fixed soon because it prevents precise workflow execution. Another workaround may be exposing resources as complementary skills.

lean0x2f-xbow · 1 month ago

This is real and extremely annoying. There is no workaround harness-side. I had to do the same workaround as Marco and expose a generic resource_read() tool to agents.

webby-box · 1 month ago

Background children without MCP resources will invent workarounds — and inventing burns. Either inject the resource tools or forbid background for MCP-dependent tasks.