Blog / Tool results and errors
MCP output limits by agent: Claude Code's 25k-token refusal, OpenCode's 51,200 bytes, Codex truncation
Your tool can return 46,000 tokens without an error. The agent app decides what the model actually gets: all of it, a file path, the first part, or the start and end with the middle gone. Each app does it differently, and none of them tells your server. Here's the table, with what we saw happen in live runs.
MCP output limits by agent app
| App (version) | Limit | Over the limit | Seen in our runs |
|---|---|---|---|
| Claude Code 2.1.301 | 25,000 tokens (warning at 10,000); 50,000 characters for text | Saves to a file, gives the model the path | 76 refusals in 80 runs |
| Codex 0.161.0 | About 10,000 tokens per printed output in code mode | Keeps start and end, drops the middle | 3 of 3 follow-up runs cut |
| OpenCode 1.18.34 / 2.0.31 | 2,000 lines or 51,200 bytes | Keeps the start, saves the rest to a file | 29 of 33 list results cut (OpenCode 1) |
| Grok Build 1.0.60 | 20,000 bytes (from source) | Keeps the start, saves the rest | Not hit |
Versions as tested on 16 Oct 2026. Limits change between releases, so check the version your users run.
Claude Code: refuse and save to a file
Per Claude Code's MCP docs, results over 25,000 tokens are not passed to the model. Claude Code saves them to a file and replaces the result with a message naming the path. You can raise the limit with MAX_MCP_OUTPUT_TOKENS. Separately, text over 50,000 characters is saved to a file unless the tool sets _meta["anthropic/maxResultSizeChars"] (up to 500,000). The docs also say error text over about 11,000 characters keeps only its first and last 5,000.
What we saw: on a 99-tool production server, the default call of the main list tool returned 46,253 tokens. Claude Code refused 40 results in 23 of 40 runs (42–71%), and 36 in 22 of 40 in a second round: 76 across 80 runs. The model got a message like “result (218,237 characters) exceeds maximum allowed tokens” and read the file in pieces, with 138 extra local reads and searches in round one. Most answers were still right; the cost was turns and tokens.
Codex: keep the start and end
Codex in its default code mode calls tools from JavaScript and prints what it needs. Printed output is capped at about 10,000 tokens by default (the source sets DEFAULT_MAX_OUTPUT_TOKENS = 10_000; the model can ask for more per call). Over the cap, Codex keeps the start and the end and replaces the middle with a marker, “…N tokens truncated…”. A public Codex issue asks for spill-to-file instead.
What we saw: in 3 of 3 live follow-up runs, every whole list page the model printed was cut, for example 133,088 and 129,770 tokens down to about 10,000. A broad tool-catalog dump of 56,619 tokens was cut to 11,244. Each time the model recovered by filtering in code, and all 3 answers were correct. But in 2 of 3 runs that meant calling the server again for the same data.
Find out which of your results hit these limits.
We run your users' jobs through Claude Code, Codex, OpenCode and the other apps they use, measure every result, and show which ones get refused, cut or re-called.
OpenCode: keep the first 51,200 bytes
OpenCode 1.18.34 and 2.0.31 cap a tool result at 2,000 lines or 51,200 bytes (we read these from the shipped binary; we found no public doc). Over the cap, the model sees the start with a note like “showing lines 1-866 of 2589; full output saved to …”, and can read the file.
What we saw: OpenCode 1 cut 29 of its 33 results from the main list tool, and made 123 extra reads to recover. OpenCode 2 hit the cap twice in one job, keeping 14,098 and 16,343 tokens, then searched the saved file in 4 steps. The answer was correct.
Grok Build: 20,000 bytes
Grok Build 1.0.60's source truncates MCP output at 20,000 bytes and saves the full result. In our captured task no result reached that size, so we have no measured behaviour. It is the smallest cap of the four, about 5,000 tokens.
Go deeper: How to reduce MCP tool response size, structuredContent or text, Why agents call the same tool twice.
What to do on your server
- Measure the default call, with no arguments, in tokens. That's the one agents make first.
- Stay under the smallest cap. About 5,000 tokens covers all four apps.
- Put the summary first: counts, what's next, and a cursor. Both Codex and OpenCode keep the start.
- Don't send the data twice. Text plus structured doubles the size; see which half the model sees.
- Keep errors short. Claude Code trims long error text to its start and end.
How we cut a list from 11,776 to 546 tokens: how to reduce MCP tool response size. All the rules: tool results and errors for AI agents.
How we measured
- Live: a 99-tool production MCP server, read-only through a proxy that blocks writes, 16 Oct 2026. Claude Code 2.1.301 (2 rounds × 40 runs), Codex CLI 0.161.0, OpenCode 1.18.34 (40 runs); 8 jobs × 5 runs per round.
- Follow-up: 3 Codex runs and 2 OpenCode 2.0.31 runs with model traffic recorded, 16 Oct 2026.
- Limits: from each app's docs, source or shipped binary on that date. Token counts are o200k_base unless they are the app's own figures (Codex's truncation numbers are its own estimate).
- Limits of this test: one server, one model per app. Grok Build's cap is from source only.
FAQ
What happens when an MCP tool result is too large?
It depends on the agent app. Claude Code saves results over 25,000 tokens to a file and gives the model the path. Codex cuts printed output to about 10,000 tokens, keeping the start and end. OpenCode keeps the first 2,000 lines or 51,200 bytes and saves the rest. Your server gets no signal either way.
What is Claude Code's MCP output limit?
25,000 tokens by default, with a warning above 10,000, per Claude Code's docs. You can raise it with MAX_MCP_OUTPUT_TOKENS. Text results over 50,000 characters are also saved to a file unless the tool sets anthropic/maxResultSizeChars, up to 500,000.
Why does Claude Code say a result exceeds maximum allowed tokens?
The result was over its limit, so it was saved to a file instead. In our live runs, the default call of one list tool returned 46,253 tokens and was refused this way 40 times in 23 of 40 runs.
Does Codex truncate MCP tool output?
Yes. In code mode, what the model's code prints is cut to about 10,000 tokens by default, keeping the start and end with the middle removed. In 3 of 3 live follow-up runs, whole list pages of about 130,000 tokens were cut to about 10,000.
How big should an MCP tool result be?
Small enough to pass every app your users run. The smallest cap we found is Grok Build's 20,000 bytes, about 5,000 tokens, so aim for default results under that and offer more by cursor or filter.
Find out which of your results hit these limits.
We run your users' jobs through Claude Code, Codex, OpenCode and the other apps they use, measure every result, and show which ones get refused, cut or re-called.