Based on Anthropic’s official docs, checked November 11, 2026

MCP token usage: output limits and context cost

MCP servers add tool descriptions to the conversation and can return large results, both of which consume context. Claude Code documents specific MCP output limits to keep those results from overwhelming a session. This guide follows the MCP output limits and warnings section of Anthropic’s Claude Code MCP docs, checked November 11, 2026. It does not invent a token cost per server or a cross-agent formula; other clients have their own limits. If the server never connects, start with the MCP server not connecting guide, or the spawn npx ENOENT guide when that is the error.

1. 1. See what is already in context

   Before raising any limit, look at what the session already loaded. In Claude Code, /context shows what each loaded item, including MCP tools, adds to the context window, and /mcp lists configured servers and their status. Disable or remove servers you are not using so their tool descriptions do not sit in context. This is an inspection step, not a claim that every unused server has a published token cost.

   /mcp
   /context

2. 2. Know the default output warning and cap

   Anthropic documents a warning when any MCP tool output exceeds 10,000 tokens. The warning threshold is fixed. By default, Claude Code limits MCP tool output to 25,000 tokens. When a successful result with no image content exceeds that token limit, Claude Code saves it to a file and replaces it in the conversation with a message that names the file path, so Claude can read the file when it needs the content. The file goes in the session’s tool-results directory under ~/.claude/projects/. Raising the cap is optional; first check whether a smaller or paginated result would do.

3. 3. Change the token cap only when you need the result inline

   To change the token limit, set MAX_MCP_OUTPUT_TOKENS in your shell before starting Claude Code. Anthropic’s example is export MAX_MCP_OUTPUT_TOKENS=50000 followed by claude. The variable applies to tools that do not declare their own limit. Tools that return image data remain subject to MAX_MCP_OUTPUT_TOKENS even if they declare a character annotation. A higher cap uses more context when the result stays in the conversation, so change it for a measured need rather than as a default for every project.

   export MAX_MCP_OUTPUT_TOKENS=50000
   claude

4. 4. Do not expect the env var to change the 50,000-character rule

   For a tool that does not declare anthropic/maxResultSizeChars, Claude Code also saves a successful result with no image content to a file once it is longer than 50,000 characters, whatever its token count. Setting MAX_MCP_OUTPUT_TOKENS does not change that character threshold. If you maintain the server and a tool must return inherently large text, such as a database schema or a file tree, the docs allow that tool’s tools/list entry to set _meta["anthropic/maxResultSizeChars"]. Claude Code then raises that tool’s character threshold to the annotated value, up to a hard ceiling of 500,000 characters. Users do not need to raise the environment variable for tools that declare the annotation. Do not copy a higher annotation onto a tool you do not maintain just to hide a size problem.

   {
     "name": "get_schema",
     "description": "Returns the full database schema",
     "_meta": {
       "anthropic/maxResultSizeChars": 200000
     }
   }

Transport size limits are separate from token caps

Claude Code also documents hard transport limits that are not controlled by MAX_MCP_OUTPUT_TOKENS. When a response from an HTTP or SSE server passes 16 MiB after decompression, Claude Code stops reading it and the request fails; the limit applies to one JSON response body or one event of an event stream. When a WebSocket server sends one message over 16 MiB, Claude Code closes the connection and in-progress calls on that server fail. If you maintain the server, return less data per response or message, for example by paginating results.

Error results are handled differently from successful ones. When a tool returns a result marked isError: true, Claude receives the text as the tool’s error message. Error text longer than about 11,000 characters keeps only its first 5,000 and last 5,000 characters, with a marker between them that says how many characters were removed.

Images and what this guide does not claim

When an MCP tool returns a PNG, JPEG, GIF or WebP image, Claude sees an inline copy that may be scaled or compressed to fit the model’s image size limits. Claude Code also saves the original bytes to the session’s tool-results directory (Claude Code v2.1.283 or later) and gives Claude the path, unless session persistence is disabled with --no-session-persistence or CLAUDE_CODE_SKIP_PROMPT_HISTORY.

This page does not estimate how many tokens a given MCP server will use in Cursor, Codex, Copilot or Antigravity, and it does not turn a 25,000-token cap into a billing forecast. For connection failures, use the MCP server not connecting guide. To generate a starting config, use the MCP config generator and then check it against the client docs.

Tips

• Run /context before raising MAX_MCP_OUTPUT_TOKENS; unused servers still occupy context with tool descriptions.
• Treat a 10,000-token warning as a signal to ask for a smaller or paginated result, not only to raise the cap.
• Remember that the 50,000-character save-to-file rule is independent of the environment variable.
• If you maintain the server, paginate large results and declare anthropic/maxResultSizeChars only for tools that truly need it.
• A 16 MiB HTTP or WebSocket payload fails at the transport layer; raising the token cap will not fix that.

Next steps

Sources

• https://code.claude.com/docs/en/mcp · checked 2026-11-11