MCP tool exceeds maximum allowed tokens: the fix

The error means an MCP tool returned more than Claude Code's output limit, which is 25,000 tokens by default. You can raise it with the MAX_MCP_OUTPUT_TOKENS environment variable, but the lasting fix is a smaller result: a narrower or paginated call, or a server that returns file URLs instead of inline image data. Current Claude Code docs say a text-only result over the limit is saved to a file instead, while results with image data stay subject to it.

The limits come from the Claude Code MCP docs, read on 2026-09-28. The server-side example is Sume's hosted MCP server, from MCP tools and gates and current code.

What is Claude Code's MCP output limit?

Current Claude Code docs set these values. A text-only result over the limit is saved to a file, and the conversation gets a message naming the path so Claude can read it when needed. Image data gets no such escape.

How do I raise the limit?

Set the variable before you start Claude Code. The docs use 50,000 as the example:

• A bigger limit lets more of the result into the conversation, so it uses more of your context window.
• For a server you don't control, the docs also suggest asking its author to add the anthropic/maxResultSizeChars annotation or to paginate responses.

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Why do image and video tools hit it?

Because an image can travel inside the result. MCP tools can return image content, and Claude Code counts image data against MAX_MCP_OUTPUT_TOKENS even when the tool declares its own size limit. A media server that returns a link instead keeps each result small, whatever the file size.

Sume's server works that way: in current code a successful result is one JSON text block, and completed jobs can include public artifacts under https://media.sume.com that the docs tell agents to report instead of signed URLs. MCP tool call result structure shows what comes back.

How do I make the call smaller?

Ask for fewer rows or fewer ids per call, and page through the rest. On Sume's server, in current code:

• jobs_list and assets_list take limit, from 1 to 100 with a default of 20; assets_list also takes a cursor for the next page.
• jobs_result accepts job_ids, with a ceiling of 20 per call; read a large batch in smaller groups.
• Results larger than 256 KB come back as an mcp_output_too_large error instead of the data. Its message asks for a narrower or paginated read and says this is an output limit, not a job failure: never resubmit a paid create because of it.