[DOCS] Sub-agent docs omit `mcpServers` support for main-thread `--agent` sessions

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:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/sub-agents | Frontmatter field reference and --agent main-thread behavior |
| https://code.claude.com/docs/en/settings | agent setting description for main-thread sessions |
| https://code.claude.com/docs/en/plugins | Plugin 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