Claude Code subagents (Explore, Plan, general-purpose) fail at spawn with `prompt is too long: 209117 tokens > 200000 maximum` when many MCP servers are configured

发生场景

Source(s): https://github.com/anthropics/claude-code/issues/37793 Status: reported working by source, not reproduced by us (workaround only; root fix not confirmed).

问题

Every Agent call ends at once. The TUI only shows something like Done (0 tool uses · 0 tokens · 44s) with no visible error; the error above is only in the subagent's JSONL transcript. The main session, on a 1M-context model, keeps working. The user prompt was about 156 tokens; the rest of the overflow was MCP tool definitions.

报错原文（已脱敏/规范化）

400 {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 209117 tokens > 200000 maximum"}}

prompt is too long: 213431 tokens > 200000 maximum

适用环境

Claude Code 2.1.81 to 2.1.121 (CLI and the macOS desktop app), Max subscription, main session on a 1M-context Opus model, subagents on 200k-context models; 10 to 34 user-level MCP servers (about 274 to 566 tools); reported March to May 2026. A commenter with 10 MCP servers (about 274 tools) got prompt is too long: 213431 tokens > 200000 maximum.

如何确认是这个问题

1. Run the same subagent with no MCP servers: claude --strict-mcp-config --mcp-config '{}' --agent Explore -p "OK" → expect: it succeeds (a commenter measured 2,015 tokens with this, 213,431 tokens without --strict-mcp-config).
2. Look in the failed subagent's JSONL transcript → expect: prompt is too long: <n> tokens > 200000 maximum.

不是这个问题时 / 边界

The check in confirm 1 still fails, so the size does not come from MCP tool definitions (our inference). On a current version, the collaborator named two cases that can still hit the limit: tool search is off for the session (ENABLE_TOOL_SEARCH disabled, or a provider without tool search), or a custom agent's tools list names MCP tools without ToolSearch.

根因

Subagents received every MCP tool schema from the parent session at spawn. The collaborator said the Explore subagent ran on a smaller model that didn't use tool search, so it put every MCP tool schema into its own context window. A commenter noted that the parent session listed the same tools as deferred (names only), so deferral worked there but not at subagent spawn. Another commenter said skills and plugins add to the spawn prompt too.

占位变量

<prompt>: your task text. <n>: the token count in the error.

修复步骤

1. Update Claude Code to 2.1.198 or later and check with claude --version → expect: per the collaborator, from 2.1.198 Explore runs on the main session's model and built-in subagents defer MCP schemas through tool search like the main session (no user confirmed this in the thread before it was closed on 2026-10-18).
2. If you cannot update, or it still fails: start Claude Code with the environment variable CLAUDE_CODE_SUBAGENT_MODEL set to a model that has room, e.g. CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-4-6 → expect: a commenter confirmed the Sonnet subagent then ran (28k tokens, 1 tool use) where the Haiku subagent failed. The original poster and another commenter instead pass model: "opus" on Agent calls.
3. For headless runs: claude -p --disable-slash-commands --strict-mcp-config "<prompt>" → expect: a commenter said a prompt that failed 13 times in the default config succeeded on the first dispatch.
4. Per project: list the MCP servers that project does not need under that project's disabledMcpServers in ~/.claude.json, then start a new session → expect: a commenter said this works, but it must be set before the session starts (edits mid-session are ignored) and kept up to date per project.

如何验证

Ask for an Explore subagent with a short task → expect: more than 0 tool uses and no prompt is too long in its JSONL transcript.

试过没用的办法

ENABLE_TOOL_SEARCH=true had no effect on subagent spawn (still 213,431 tokens). A user-scope ~/.claude/agents/Explore.md with a narrow tools: list did not replace the built-in Explore for one commenter (213,465 tokens); another commenter said a custom agent named Explore with tools: Read, Grep, Glob, Bash "seems to be working", so reports conflict.

风险提示

Running subagents on Opus uses more quota (original poster). With --strict-mcp-config and no --mcp-config, that run has no MCP tools at all (our inference). Commenters linked third-party proxies and context tools; we have not reviewed them, so don't put an unreviewed proxy between your agent and MCP servers that hold credentials (our inference).

验证范围

Claude Code 2.1.81 to 2.1.121 for the failure; fix named for 2.1.198 and later; October 2026.

何时失效

All built-in and custom subagents defer MCP schemas on every provider. Open question: whether 2.1.198+ fixes it for the people who reported it; nobody confirmed in the thread.