How to limit MCP tool output size in Claude Code

Set MAX_MCP_OUTPUT_TOKENS in your shell before you start Claude Code to change how large an MCP tool result can be before Claude Code saves it to a file. The documented default is 25,000 tokens. A separate 50,000-character limit on text results does not change when you raise or lower the token value.
Why oversized tool output matters
A tool result goes into the conversation that Claude reads. A server that returns a large payload fills that context with content that a reviewer may never open. The Claude Code MCP docs warn that servers which fetch external content can expose you to prompt injection risk, and a large result gives that content more room. Before you approve a server, run a test call and check how much text it returns.
Cost follows the same path. Claude Code sends your full conversation with every request, and each time Claude uses a tool it sends another request that carries the batch of tool results. The costs page says a session that stays open all day keeps drawing usage for its history, even when the next question is one line long. A tool that returns 25,000 tokens on every call adds that weight to every later turn until the session compacts or clears those results.
The limits and their defaults
Four numbers decide what happens to a large result. They act at different points, so changing one does not move the others.
| Limit | What it applies to | Documented default | How it is set | Over the limit |
|---|---|---|---|---|
MAX_MCP_OUTPUT_TOKENS |
Tokens in one MCP tool result, for tools that do not declare their own limit | 25,000 tokens | Shell environment variable, set before Claude Code starts | A successful result is saved to a file, and the conversation gets the path |
| Text threshold | Characters in one successful text result, for tools without the anthropic/maxResultSizeChars annotation |
50,000 characters | Not set by MAX_MCP_OUTPUT_TOKENS. A server can raise it per tool |
Saved to a file, whatever its token count |
| Transcript warning | Tokens in one MCP tool output | 10,000 tokens, fixed | Not configurable in the docs | A warning in the transcript viewer. The output is not blocked |
| Error text | Text of a result marked isError: true |
About 11,000 characters | Fixed in the docs | Keeps the first 5,000 and last 5,000 characters, with a marker between them |
The first row is the one most people mean by “limit output size.” The text threshold sits underneath it, so a value that looks generous can still send a large text result to a file.
Set the token limit
- Pick a value. The docs give no minimum and no recommended number. The example below uses 10,000, which matches the transcript warning threshold.
- Export the variable in the shell where you start Claude Code. The docs say to set it before you start, so a value changed inside a running session is not covered.
- Start Claude Code from that shell.
- Run an MCP tool that returns a large result. Open the transcript viewer with
Ctrl+Oand look for the warning, then check that the conversation shows a file path instead of the full output.
export MAX_MCP_OUTPUT_TOKENS=10000
claude
The docs do not name a Claude Code version for these output settings. Confirm the behaviour in the version you run, with claude --version.
What happens to an oversized result
When a successful result with no image content goes over the token limit, Claude Code saves it to a file. The file sits in the session’s tool-results directory under ~/.claude/projects/. The conversation keeps only a message that names the file path, so Claude reads the file when it needs the content.
For a security review, this means the full output is on disk, and the transcript holds a pointer to it. A reviewer who wants to see what a server returned has to open that file. Treat that directory as part of the review scope, because it holds the output you are trying to limit.
Timeouts are a separate setting
Timeouts do not use the output limit. Two environment variables cover the server and the tool, and a per-server field overrides the tool one.
MCP_TIMEOUTsets how long a server may take to start, in milliseconds. The default is 30000. The docs’ example,MCP_TIMEOUT=10000 claude, sets a 10-second startup timeout.MCP_TOOL_TIMEOUTsets the time allowed for one tool execution. The default is 100000000 milliseconds, about 28 hours.- A
timeoutfield in a server’s.mcp.jsonentry, in milliseconds, overridesMCP_TOOL_TIMEOUTfor that server. Values below 1000 are ignored.
{
"mcpServers": {
"airtable": {
"command": "npx",
"args": ["-y", "airtable-mcp-server"],
"timeout": 600000
}
}
}
A tool call that sends no response and no progress notification also aborts when its idle window ends. The idle window defaults to 5 minutes for HTTP, SSE, WebSocket and claude.ai connector servers, and 30 minutes for stdio servers. The docs say CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT needs Claude Code v2.1.187 or later.
Gotchas in the fine print
These points come straight from the docs, and each one can catch a reviewer who assumes the setting does more.
- Raising
MAX_MCP_OUTPUT_TOKENSto 50000 does not keep a text result of more than 50,000 characters inline. The docs say the character threshold stays the same whatever the token setting. - The 10,000-token warning only displays. It does not stop the output.
- A lower limit saves output to a file. It does not drop the output, so the content can still reach Claude through a later read.
- Image output stays under
MAX_MCP_OUTPUT_TOKENSeven when a tool declares its own limit. The annotation covers text only. - Error text over about 11,000 characters keeps only its first and last 5,000 characters. The middle is gone from what Claude receives as the error.
If you maintain the MCP server
A server can raise the threshold for one tool. Add the anthropic/maxResultSizeChars key under _meta in that tool’s entry in the tools/list response. Claude Code raises the threshold to that value, up to a hard ceiling of 500,000 characters. The annotation applies to text content only.
{
"name": "get_schema",
"description": "Returns the full database schema",
"_meta": {
"anthropic/maxResultSizeChars": 200000
}
}
Use it for tools whose output is large by design, such as a schema or a full file tree. A tool that returns more text than the caller needs is better fixed in the server, because the limit only changes where the output goes.
What this setting does not control
The token limit does not decide which servers you trust, and it does not filter what a server returns. The MCP docs tell you to confirm that you trust each server before you connect it. Prompt injection risk is a separate control, and the docs point to the security page for it.
The limit also does not cap the bytes a server sends. HTTP and SSE responses over 16 MiB fail, and a WebSocket message over 16 MiB closes the connection. Those limits sit in the transport, not in MAX_MCP_OUTPUT_TOKENS.
For the wider picture, start with the MCP security pillar. The audit of MCP tool calls and classifying MCP tools by risk cover the review steps that come before you set a limit.
Frequently asked questions
What is the default MCP tool output limit in Claude Code?
The documented default for MAX_MCP_OUTPUT_TOKENS is 25,000 tokens. Claude Code shows a warning in the transcript viewer when one MCP tool output exceeds 10,000 tokens, and that warning threshold is fixed. A successful text result longer than 50,000 characters is saved to a file whatever its token count. Setting MAX_MCP_OUTPUT_TOKENS does not change that character threshold.
Does a lower MAX_MCP_OUTPUT_TOKENS stop the tool output from reaching Claude?
Not according to the docs. An over-limit result is saved to a file in the session's tool-results directory, and the conversation gets a message that names the path. Claude reads that file when it needs the content. A lower limit moves output out of the conversation. It does not stop Claude from reading that output later.
What is the difference between MCP_TIMEOUT and MCP_TOOL_TIMEOUT?
MCP_TIMEOUT sets how long an MCP server may take to start, in milliseconds. Its default is 30000. MCP_TOOL_TIMEOUT sets the time allowed for one tool execution, with a default of 100000000, about 28 hours. A timeout field in a server's .mcp.json entry overrides MCP_TOOL_TIMEOUT for that server only. Changing MCP_TIMEOUT does not shorten a tool call.
Does MAX_MCP_OUTPUT_TOKENS apply to images returned by an MCP tool?
Yes. The docs say tools that return image data are still subject to MAX_MCP_OUTPUT_TOKENS, even when a tool declares its own text limit. The 50,000-character threshold is for results with no image content. Claude Code also saves the original image bytes to a file, and Claude sees an inline copy that may be scaled down or compressed.