Controlling MCP Result Size And Context Pressure

TL;DR

Claude Code warns when MCP tool output exceeds 10,000 tokens. Control pressure with MAX_MCP_OUTPUT_TOKENS, server-side anthropic/maxResultSizeChars, tool search deferral, and careful alwaysLoad settings.

Prerequisites & Requirements

• {"task": "Large-output tools identified", "description": "Servers returning logs, queries, or file dumps are listed"}
• {"task": "Env access", "description": "You can export variables before launching Claude Code"}
• {"task": "Server ownership", "description": "Know whether you can patch MCP server pagination"}
• {"task": "Context budget", "description": "Team agrees on acceptable MCP share of the window"}

Core Concepts Explained

Default warning at 10k tokens

MCP documentation states Claude Code displays a warning when MCP tool output exceeds 10,000 tokens, signaling context pressure.

MAX_MCP_OUTPUT_TOKENS

Set the environment variable to raise or lower the cap—for example MAX_MCP_OUTPUT_TOKENS=50000. Applies to tools without their own declared limit.

maxResultSizeChars annotation

Tools that set anthropic/maxResultSizeChars use that value for text content independently of the env var. Prefer server-side annotations over globally raising limits.

Tool search deferral

Tool search loads MCP tool definitions on demand, keeping session-start context lower when many servers are configured. ENABLE_TOOL_SEARCH=auto uses a 10% context threshold mode.

alwaysLoad tradeoff

Setting alwaysLoad: true forces a server's tools into context every turn—only for small always-needed toolsets.

Step-by-Step Implementation Guide

1. Reproduce the warning. Note which MCP tool triggers the 10k token alert.

2. Try server pagination first. Ask the server author to page large responses.

3. Add maxResultSizeChars if you maintain the server.

4. Tune MAX_MCP_OUTPUT_TOKENS temporarily while paginating—document the value in team runbooks.

5. Review alwaysLoad flags. Disable on catalog servers with dozens of tools.

6. Confirm tool search is on. Default deferral helps multi-server setups.

7. Monitor /context. Verify MCP share drops after changes.

Configuration Examples

export MAX_MCP_OUTPUT_TOKENS=25000
claude

{
  "mcpServers": {
    "analytics": {
      "type": "stdio",
      "command": "analytics-mcp",
      "alwaysLoad": false
    }
  }
}

Troubleshooting

Warning persists after raising env var

Check whether the tool declares anthropic/maxResultSizeChars or returns images subject to token limits separately.

Claude cannot complete task with truncated output

Paginate server responses or split tools instead of only raising limits.

Context still tight with few tools

Inspect alwaysLoad servers and upfront built-in tools; use tool search auto mode.

Source Verification Notes

Verified against Claude Code MCP documentation on 2026-06-16: 10k token warning, MAX_MCP_OUTPUT_TOKENS, anthropic/maxResultSizeChars, tool search defaults, ENABLE_TOOL_SEARCH=auto, and alwaysLoad behavior.

Duplicate Check

Complements sparse-context-setup-for-large-codebases (general context strategy) and MCP threat-model guides. No guides entry documents MCP output token limits and tool search deferral together.

References

• Claude Code MCP - https://code.claude.com/docs/en/mcp