Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Sub-agent docs omit `mcpServers` support for main-thread `--agent` sessions [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#51770•Fetched 2026-04-22 07:53:18
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×4
RAW_BUFFERClick to expand / collapse

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

Supported frontmatter fields, Scope MCP servers to a subagent, and Run the whole session as a subagent

Current Documentation

The docs currently say:

| mcpServers | No | MCP servers available to this subagent. Each entry is either a server name referencing an already-configured server (e.g., "slack") or an inline definition with the server name as key and a full MCP server config as value |

Use the mcpServers field to give a subagent access to MCP servers that aren't available in the main conversation.

Run the whole session as a subagent. Pass --agent <name> to start a session where the main thread itself takes on that subagent's system prompt, tool restrictions, and model:

Related pages repeat the same narrower description:

agent | Run the main thread as a named subagent. Applies that subagent's system prompt, tool restrictions, and model.

Setting agent activates one of the plugin's custom agents as the main thread, applying its system prompt, tool restrictions, and model.

What's Wrong or Missing?

Changelog v2.1.117 says agent frontmatter mcpServers are now loaded for main-thread agent sessions started via --agent, but the docs still describe mcpServers as subagent-only behavior and describe main-thread agent activation as applying only the system prompt, tool restrictions, and model.

That leaves readers with the wrong mental model for agent frontmatter:

A. mcpServers looks unavailable in main-thread agent sessions

The sub-agents page currently scopes mcpServers to delegated subagents and says it gives a subagent access to MCP servers that are not available in the main conversation.

B. Main-thread --agent docs omit the new behavior

The --agent / agent setting documentation says the main thread uses an agent's system prompt, tool restrictions, and model, but it does not mention that mcpServers from agent frontmatter are now loaded too.

Suggested Improvement

Update the sub-agents page to distinguish which frontmatter fields apply when an agent runs as a delegated subagent versus when it runs as the main thread via --agent or the agent setting.

Specifically:

  1. Update the mcpServers field description to note that agent frontmatter mcpServers also load for main-thread agent sessions.
  2. Add a short example showing an agent file with mcpServers plus claude --agent <name>.
  3. Update settings and plugins wording so they do not imply that only system prompt, tool restrictions, and model are applied when the main thread runs as an agent.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageContext
https://code.claude.com/docs/en/sub-agentsFrontmatter field reference and --agent main-thread behavior
https://code.claude.com/docs/en/settingsagent setting description for main-thread sessions
https://code.claude.com/docs/en/pluginsPlugin settings.json agent description for main-thread sessions

Total scope: 3 pages affected

Source: Changelog v2.1.117

Entry text: Agent frontmatter mcpServers are now loaded for main-thread agent sessions via --agent

extent analysis

TL;DR

Update the documentation for sub-agents, settings, and plugins pages to reflect that agent frontmatter mcpServers are loaded for both delegated subagents and main-thread agent sessions started via --agent.

Guidance

  • Review the current documentation for mcpServers and --agent to identify areas where the text implies mcpServers is only for subagents.
  • Update the mcpServers field description to note its applicability to main-thread agent sessions.
  • Add examples to illustrate the usage of mcpServers with --agent, such as an agent file with mcpServers and the command claude --agent <name>.
  • Ensure the documentation for settings and plugins accurately describes the behavior when the main thread runs as an agent, including the loading of mcpServers from agent frontmatter.

Example

An updated description for the mcpServers field could be:

| mcpServers | No | MCP servers available to this agent. Each entry is either a server name referencing an already-configured server (e.g., "slack") or an inline definition with the server name as key and a full MCP server config as value. This field applies to both delegated subagents and main-thread agent sessions started via --agent.

Notes

The updates should be made to the sub-agents, settings, and plugins pages as listed in the affected pages section of the issue.

Recommendation

Apply workaround by updating the documentation as suggested to reflect the correct behavior of mcpServers in main-thread agent sessions. This will improve the understanding and usability of the feature.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING