Skip to content

All posts

AI

How to limit MCP tool output size in Claude Code

Ritesh Patel

AI: 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

  1. Pick a value. The docs give no minimum and no recommended number. The example below uses 10,000, which matches the transcript warning threshold.
  2. 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.
  3. Start Claude Code from that shell.
  4. Run an MCP tool that returns a large result. Open the transcript viewer with Ctrl+O and 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.

  1. MCP_TIMEOUT sets 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.
  2. MCP_TOOL_TIMEOUT sets the time allowed for one tool execution. The default is 100000000 milliseconds, about 28 hours.
  3. A timeout field in a server’s .mcp.json entry, in milliseconds, overrides MCP_TOOL_TIMEOUT for 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.

  1. Raising MAX_MCP_OUTPUT_TOKENS to 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.
  2. The 10,000-token warning only displays. It does not stop the output.
  3. 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.
  4. Image output stays under MAX_MCP_OUTPUT_TOKENS even when a tool declares its own limit. The annotation covers text only.
  5. 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.

Ritesh Patel, Founder & VP Product, Nirmata

Ritesh Patel is a founder of Nirmata and leads its products. He writes about governing AI coding agents, MCP security and Kubernetes policy as code.

LinkedIn

Govern AI agents with AIControlsControl what AI agents do, and prove it.
Share

Stay up-to-date with the latest in AI, governance, and infrastructure

Subscribe to our free monthly newsletter to get industry news, DevOps tips, and articles right to your inbox on Kyverno, containerization, Kubernetes deployment & management and more.