MCP fetch token budget: client limits and tool size caps

Every fetch call spends context. The page arrives as a tool result, stays in the conversation and is sent to the model again with every later turn until the context is compacted. Two limits decide how much one call can spend: the size cap of the fetch tool and the output limit of your MCP client. This guide is about how those two fit together, and a default that works for most reading tasks.

The numbers below use a rough rule of thumb: English prose is about four characters per token. Code, tables, URLs and other languages cost more per character. Treat the figures as estimates and measure your own pages when it matters.

Where the tokens go

The tool result is the big cost, and it repeats: a 20,000-token result read on turn three is still paid for on turn ten. Tool definitions also cost context on every request, but for a fetch server with one or two tools that cost is small; the rest of this guide is about the result.

Your client's output limit

Clients put their own ceiling on MCP tool results. Claude Code shows a warning when an MCP tool result exceeds 10,000 tokens and limits output to 25,000 tokens by default. A successful text result over that limit is not dropped: Claude Code saves it to a file in the session's tool-results directory and puts the file path in the conversation instead, so the model reads the page only when it opens that file. You can raise the limit for a session:

MAX_MCP_OUTPUT_TOKENS=50000 claude

To make it permanent, export the variable in your shell profile or set it in the env block of Claude Code's settings.json. It applies to every MCP server in the session, whatever scope you added the server in.

One threshold does not move with this variable. Unless the server raises a tool's own limit with anthropic/maxResultSizeChars, Claude Code saves any successful text result longer than 50,000 characters to a file, whatever MAX_MCP_OUTPUT_TOKENS says (checked 2026-10-28). A fetch cap above 50,000 characters therefore sends long pages to a file rather than into the conversation.

Raising the client limit is the wrong first move for a fetch tool. It lets one page take more of your context; it does not make the page more useful. Set the tool's cap first, and keep the client limit as a safety net.

The tool's own size cap

The best cap is the one the server applies, because it stops the content before it reaches the client. Fetch tools name this option differently:

The transport guide shows how to run the reference server locally if you want to try max_length and start_index yourself.

Note how the two limits line up: 100,000 characters, the top of Live Web Data API's range, is roughly 25,000 tokens, which is Claude Code's default limit. A result at the top of the range can still trip the limit on dense pages, so stay well below it.

Two options shrink a result without a smaller cap. Live Web Data API's verbosity: "compact" (the default) returns the main content and drops navigation, footers and cookie banners; "full" returns the whole page body. And the output format matters a little: HTML is the largest, so ask for it only when structure is the data.

Reading long pages in parts

Some pages are long and you need all of them, such as a full changelog or a long API reference. Options, from best to worst:

1. Fetch a narrower URL. Most docs sites have one page per section and changelogs often have one page per release. A specific URL is cheaper than any amount of paging.
2. Page through it. With the reference server, call again with start_index set to where the last result stopped. The model reads the page in steps and can stop early.
3. Raise the cap once. With a tool that has no paging, like Live Web Data API's, ask for a larger max_characters for that one call, then go back to the default.
4. Summarize and drop. Ask the agent to note what it needs from a long result and continue in a fresh context.

A default budget to start from

• Request 8,000 characters (about 2,000 tokens) of Markdown in compact mode for a first read.
• Use 2,000 characters for checks: a version number, a price, a status line.
• Go to 20,000 characters only when the first result clearly cuts off what you need.
• Leave Claude Code's output limit at its default until a real task needs more.

Tell the agent the budget in your project instructions, for example: "When fetching, request 8,000 characters first; raise it only if the answer is cut off." Models follow a stated rule more reliably than a vague "be efficient".

Try the defaults

Live Web Data API's fetch tool defaults to 8,000 characters of compact Markdown, and each result header shows the credits used and the credits left. Failed fetches cost no credits. Configs are in the MCP docs. If a fetch fails instead of returning too much, see the errors guide.