In Claude Code, an MCP tool returns a 60,000-token database dump: what do the output warning and limit do, and how do MAX_MCP_OUTPUT_TOKENS and maxResultSizeChars change them?
answer
- a warning, then a cap
- ten thousand, twenty-five thousand
- over the cap: a file, not truncation
- an environment variable for every tool
- a per-tool annotation, images excepted
basics
~20 sClaude Code warns when MCP output passes 10,000 tokens and caps it at 25,000 by default, saving an oversized text result to a file and passing its path. MAX_MCP_OUTPUT_TOKENS raises the cap; a tool's anthropic/maxResultSizeChars overrides it for text.
solid answer
~40 sClaude Code shows a warning when an MCP tool's output exceeds **10,000 tokens**, a fixed threshold, and limits output to **25,000 tokens** by default. A result with no image content that goes over the limit isn't dropped: Claude Code saves it to a file in the session's `tool-results` directory under `~/.claude/projects/` and replaces it with a message naming the path, so Claude reads the file when it needs the content. `MAX_MCP_OUTPUT_TOKENS` raises the limit for every tool that doesn't declare its own. A server author can instead set `_meta["anthropic/maxResultSizeChars"]` on one tool, up to 500,000 characters, which governs that tool's text whatever the variable says; image content from such a tool still counts against `MAX_MCP_OUTPUT_TOKENS`.
go deeper
Recall the two numbers, a warning past 10,000 tokens and a 25,000-token default limit, and the environment variable that raises the limit.
Explain what happens over the limit: the result is saved to a file and Claude gets the path, so nothing is silently truncated.
Choose the right lever for a heavy tool, a per-tool annotation for your own server, the variable for someone else's, and know images escape the annotation.
Weigh larger inline results against context cost across a team's sessions, and push server authors toward pagination rather than raising limits by default.
## Why Claude Code limits MCP output An MCP tool result goes straight into the conversation, and everything in the conversation counts against the context window on every later request. One tool that returns a whole schema, log or table can crowd out your code and push the session toward compaction. Claude Code therefore watches the size of each MCP result. ## The default behaviour | Mechanism | Value | Adjustable? | | :- | :- | :- | | Warning threshold | 10,000 tokens | no, fixed | | Output limit | 25,000 tokens | yes, `MAX_MCP_OUTPUT_TOKENS` | | Per-tool text limit | the tool's `anthropic/maxResultSizeChars` | by the server author, up to 500,000 characters | - **Warning.** Any MCP tool output over 10,000 tokens produces a warning in the session. It tells you a tool is heavy; it changes nothing by itself. - **Limit.** The default maximum is 25,000 tokens. - **Over the limit.** When a result with no image content exceeds the limit, Claude Code **saves it to a file** in the session's `tool-results` directory under `~/.claude/projects/` and replaces it in the conversation with a message that names the file path. Claude can then read the file, or the parts of it it needs, with its normal file tools. So the 60,000-token dump in the question produces the warning, and the conversation receives a pointer to a saved file rather than the dump itself. ## Raising the limit for every tool Set the environment variable before starting Claude Code, or in the `env` block of `settings.json`: ```bash export MAX_MCP_OUTPUT_TOKENS=50000 claude ``` This applies to every tool that doesn't declare its own limit. It is the lever you have for servers you don't control. Raising it means large results land inline again, so you trade context space for avoiding the file round trip. ## Raising it for one tool, from the server side A server author can mark individual tools whose large outputs are the point, such as a full database schema or a file tree: 1. Add `_meta` with `"anthropic/maxResultSizeChars"` to that tool's entry in the server's tool list. 2. Claude Code raises that tool's threshold to the value, up to a hard ceiling of **500,000 characters**. 3. For **text content**, that value applies regardless of `MAX_MCP_OUTPUT_TOKENS`, so users don't have to raise the variable. The annotation has **no effect on image content**: images from that tool are still subject to `MAX_MCP_OUTPUT_TOKENS`, and raising the variable is the only option for image-heavy tools. ## Images are handled separately When a tool returns a PNG, JPEG, GIF or WebP image, Claude sees it inline, possibly scaled down to fit the model's image limits. From v2.1.283 Claude Code also saves the original bytes to the same `tool-results` directory and gives Claude the path, unless session persistence is disabled. ## Choosing between the levers - **The tool is yours:** add `anthropic/maxResultSizeChars` to the one tool that needs it, or paginate its results so each page stays small. - **The tool is someone else's:** raise `MAX_MCP_OUTPUT_TOKENS` for sessions that need it, or ask the author to add the annotation or pagination. - **The output is rarely needed in full:** keep the default; the saved file gives Claude access without paying for the whole result in context. ## Two units, and what lands on disk The two levers count differently: `MAX_MCP_OUTPUT_TOKENS` is measured in **tokens**, while `anthropic/maxResultSizeChars` is measured in **characters**. A 200,000-character annotation and a 50,000-token variable are not the same budget, so compare them deliberately when a tool's results hover near either. A spilled result is a **plaintext file** under `~/.claude/projects/<project>/<session>/tool-results/`. Claude Code deletes it with the session's other files once it is older than `cleanupPeriodDays` (30 days by default). If a tool returns customer records or secrets, that file holds them for the retention period, which is worth knowing before you point a database server at production data. A slow call is a different problem from a big one: an MCP call in the main conversation still running after two minutes moves to a background task, and its limits are timeouts rather than token counts.
- Is the 10,000-token warning adjustable?No. The warning threshold is fixed; only the limit moves. `MAX_MCP_OUTPUT_TOKENS` raises the 25,000-token limit for tools without their own setting, and a server's `anthropic/maxResultSizeChars` raises one tool's text threshold, but outputs above 10,000 tokens still trigger the warning.
- An MCP tool call is not big but slow, still running after three minutes. What does Claude Code do?From v2.1.212, a main-conversation MCP call still running after two minutes moves to a background task: Claude gets a task ID and keeps working, the result arrives as a notification, and you can stop it from `/tasks`. `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` changes the threshold. Subagent calls are never backgrounded, and a call waiting on an open elicitation dialog moves only after the dialog closes.
- Claude Code truncates oversized MCP output and drops the rest
- Raising MAX_MCP_OUTPUT_TOKENS also moves the 10,000-token warning
- maxResultSizeChars lifts the limit for a tool's images too
- An oversized MCP result fails the tool call
- Output limits apply to tool definitions as well as results