{
  "question": "How do I cap or truncate MCP tool output so it doesn't flood the context window?",
  "slug": "how-to-cap-mcp-tool-output-size-to-prevent-context-flooding",
  "url": "https://www.rightshold.com/answers/how-to-cap-mcp-tool-output-size-to-prevent-context-flooding",
  "short_answer": "Fix it in two places. In the server, make large results small by design: give every tool that can return a lot a limit or page-size argument with a sensible default, a cursor for the next page, filters and a concise/detailed response format, and when you do cut a result, say so in the result and tell the agent how to get the rest. Return a resource_link to a big file instead of its contents. In the client, set a ceiling: Claude Code warns when an MCP tool output passes 10,000 tokens, limits it to 25,000 tokens by default (change it with MAX_MCP_OUTPUT_TOKENS), and saves successful text results over 50,000 characters to a file instead of putting them in the conversation. The MCP specification itself sets no size limit on tool results, and its built-in pagination covers list operations such as tools/list, not tools/call results.",
  "checklist": [
    "Find the tools that can return unbounded data: search, list, query, log, file-read and fetch tools are the usual ones.",
    "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.",
    "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.",
    "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.",
    "Offer a response_format argument (for example concise or detailed) and default to concise: names and IDs the next call needs, not every field.",
    "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.",
    "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.",
    "Keep error results short and actionable: Claude Code trims error text longer than about 11,000 characters to its first and last 5,000.",
    "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.",
    "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."
  ],
  "sections": [
    {
      "heading": "What Claude Code does with large MCP results",
      "points": [
        "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."
      ]
    },
    {
      "heading": "What the MCP specification says",
      "points": [
        "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."
      ]
    },
    {
      "heading": "Why truncation alone isn't enough",
      "points": [
        "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."
      ]
    }
  ],
  "checks": [],
  "ask_rightshold": {
    "start": "https://www.rightshold.com/start?ref=seo",
    "mcp_endpoint": "https://www.rightshold.com/mcp",
    "ask": "Before I connect this MCP server to my agent, what tools does it expose, and have their definitions changed since they were recorded?",
    "mcp_call": {
      "tool": "precall_check",
      "arguments": {
        "url": "<the MCP server's https URL>",
        "tool": "<optional tool name>"
      }
    },
    "also": [
      "Free, no key. The answer combines the external registry entry, a live integrity probe against the recorded tool fingerprint, an invisible-text scan of the definitions served now and any security flags, so you can read each tool's schema (and whether it takes a limit or cursor argument) before your agent calls it.",
      "scan_text checks a large tool result or fetched document for hidden characters and instruction-like text before you hand it to a model."
    ],
    "scope": "Rightshold does not run your tools, measure their output or set limits in your MCP client; output size is controlled by the server's design and the client's settings."
  },
  "sources": [
    {
      "title": "MCP specification 2025-11-25: Tools (tool results, resource links, structured content)",
      "url": "https://modelcontextprotocol.io/specification/2025-11-25/server/tools"
    },
    {
      "title": "MCP specification 2025-11-25: Pagination",
      "url": "https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination"
    },
    {
      "title": "Claude Code docs: MCP output limits and warnings",
      "url": "https://code.claude.com/docs/en/mcp"
    },
    {
      "title": "Anthropic Engineering: Writing effective tools for agents (September 11, 2025)",
      "url": "https://www.anthropic.com/engineering/writing-tools-for-agents"
    }
  ],
  "related": [
    {
      "title": "How to test that MCP tool errors don't leak secrets",
      "url": "https://www.rightshold.com/answers/how-to-test-that-mcp-tool-errors-dont-leak-secrets"
    },
    {
      "title": "How to stop Log-To-Leak style prompt injection through MCP tools",
      "url": "https://www.rightshold.com/answers/how-to-mitigate-log-to-leak-prompt-injection-in-mcp"
    },
    {
      "title": "How to restrict an MCP database tool to read-only queries",
      "url": "https://www.rightshold.com/answers/how-to-restrict-an-mcp-database-tool-to-read-only-queries"
    },
    {
      "title": "How to vet an MCP server before installing it",
      "url": "https://www.rightshold.com/answers/how-to-vet-an-mcp-server-before-installing-it"
    }
  ],
  "computed_from": "Curated guidance; license verdicts computed from Rightshold's license profiles at render time. Not legal advice.",
  "updated": "2026-10-30"
}