Every result costs context

Build

The MCP spec sets no size limit; the host does. Every token a tool returns is a token of Claude's context, so a tool that returns 50k rows is broken even if it works.

Claude Code's limits for one tool result

10k: warning

25k: cut off (default)

get_issue400
search, 20 results4,000
list all issues18,000
dump 50k rowstoo big

Change the cap with MAX_MCP_OUTPUT_TOKENS. Over it, Claude gets an error saying the response exceeded the maximum allowed tokens, with a hint to paginate or filter.

Paginate

Return a page and a cursor. Let Claude ask for more.

Filter

Take query, fields or date params so results start small.

Summarize first

Counts and top hits first, details on request.

Link, don’t paste

Return IDs, URLs or resource links instead of blobs.