How do I cap or truncate MCP tool output so it doesn't flood the context window?

What should I check, step by step?

1. Find the tools that can return unbounded data: search, list, query, log, file-read and fetch tools are the usual ones.

2. Give each one a limit (or page_size) argument with a small default and a hard maximum the server enforces, so a model that asks for 'everything' still gets one page.
3. Return a cursor or offset for the next page and say in the result how many items remain. MCP's own cursor pagination applies to list operations, so for tools/call you add these as ordinary tool arguments.
4. Add filters and range selection (date range, fields, line range) so the agent can ask for exactly what it needs instead of fetching everything and reading it.
5. Offer a response_format argument (for example concise or detailed) and default to concise: names and IDs the next call needs, not every field.
6. If you truncate, mark it in the result itself, for example '[truncated: showing 50 of 4,812 rows; call again with cursor=... or add a filter]'. A silent cut looks like a complete answer.
7. For large files, return a resource_link (URI, name, mimeType) and let the client fetch it only if needed, rather than embedding the whole file in the result.
8. Keep error results short and actionable: Claude Code trims error text longer than about 11,000 characters to its first and last 5,000.
9. In Claude Code, set MAX_MCP_OUTPUT_TOKENS if 25,000 tokens is too much or too little for your work; only raise a single tool's text ceiling with _meta["anthropic/maxResultSizeChars"] when its large output is genuinely needed.
10. Remember that big tool output is also untrusted input: the more third-party text a tool pours into the context, the more room there is for injected instructions.

What Claude Code does with large MCP results

Claude Code's MCP docs list the current limits: a warning above 10,000 tokens of tool output, a default maximum of 25,000 tokens that MAX_MCP_OUTPUT_TOKENS changes (the warning threshold is fixed), and, for a successful result without images that goes over the limit, saving it to a file in the session's tool-results directory and putting the file path in the conversation so Claude can read it when needed.

• Separately, a successful text result longer than 50,000 characters is saved to a file whatever its token count, unless the tool declares _meta["anthropic/maxResultSizeChars"] in its tools/list entry; that per-tool value can go up to a hard ceiling of 500,000 characters. Tools that return images stay under the token limit.
• Responses from HTTP and SSE servers over 16 MiB are not read at all and the request fails, and a WebSocket message over 16 MiB closes the connection, so very large payloads have to be paginated on the server either way.

What the MCP specification says

A tool result carries a content array (text, image, audio, resource links and embedded resources) and optionally structuredContent; a tool that returns structuredContent SHOULD also return the serialized JSON in a text block, which doubles the size of a large structured result.

• A tool MAY return resource links: a URI the client can fetch or subscribe to, instead of the data itself.
• The specification's pagination is opaque cursor-based and covers list operations; the server picks the page size and clients MUST NOT assume a fixed one. It does not define a size cap for tool results, so limits come from the server's design and the client's settings.

Why truncation alone isn't enough

Anthropic's engineering post on writing tools for agents recommends some combination of pagination, range selection, filtering and truncation with sensible default parameter values for any response that could use a lot of context, and, if you truncate, steering the agent with helpful instructions, for example to make many small targeted searches instead of one broad one.

• A client-side cap protects the context window but throws the information decision to the client. A server that returns the right page, with the right fields and a note on how to get more, gives the agent a complete answer to a smaller question.