GitHub's MCP server paginated from day one and still overflowed the context window

GitHub's official MCP server paginated from the start — perPage up to 100, after cursors on the newer tools — and its issue tracker still filled with single calls that broke the context window: 30 commits at more than 64k tokens, 30 pull requests at 508KB, 50 project items at about 100K tokens. Pagination bounds how many records come back. The context window is a budget of tokens, and a record can weigh anything. Count your pages in tokens, cut fields before you page, and assume the host your users run will handle the overflow differently from the one you tested.

At a glance

The overflow reports on github/github-mcp-server, as of October 2026. Sizes are what each reporter measured, except PR #2563's, which the maintainers measured.

Filed	Tool	Reported size	Response
2025-04-06 (#142)	`list_commits`	30 commits, >64k tokens; ~5–6KB per commit	Reporter asked for field filtering
2025-05-22 (#425)	`get_pull_request_comments`	26,688 tokens against Claude Code's 25,000 cap	Requests for pagination followed (#567, #625)
2025-06-29 (#608)	`get_job_logs`	Full logs "can easily exceed LLM context limits"	`tail_lines` parameter
2026-02-02 (#1934)	`list_pull_requests`	30 PRs, 508KB; ~17KB per PR, 36KB in another query	Still open; PR #2675 makes `search_pull_requests` minimal by default
2026-03-02 (#2122)	`pull_request_read`	Payloads above ~50–100KB pin Cursor and VS Code at 100% CPU	PR #2489 exposed the missing `after` cursor
2026-04-24 (#2383)	projects	50 items, ~400KB, ~100K tokens	PR #2563 minimal types: −93% per item
2026-09-07 (#3236)	`pull_request_read` `get_files`	Always returns full patches	Open; #3286 asks for field filtering

The same page of 50 records, before and after projection. The page size did not change; what each record carries did.

A paper trail from one server

Most MCP servers that overflow a context window leave no record. GitHub's left eighteen months of one, because its users file issues and its maintainers answer them in public. Read in order, the issues tell the same story every time.

The first, #142 in April 2025, was a list_commits call on zalando/skipper. Thirty commits produced more than 64k tokens on the next model call, about 5–6KB per commit. The reporter was a tier-1 OpenAI user and got a 429: the request needed 68,490 tokens against a limit of 30,000 tokens per minute. That is the one hard cost number in this story. The call was well within its page size and still could not be sent.

The pattern held. In May 2025 get_pull_request_comments returned 26,688 tokens to a Claude Code user whose cap was 25,000 (#425). In June, a report that complete job logs "can easily exceed LLM context limits" led to a tail_lines parameter (#608). In February 2026, list_pull_requests returned 508KB for 30 PRs — about 17KB each, 36KB each on another query — and the reporter asked for the minimal_output option that search_repositories already had (#1934, still open). In April, 50 project items came to about 400KB, roughly 100K tokens, which the reporter called "roughly half of a typical LLM context window"; two pages of 50 fill one (#2383).

The cause was the record, not the count

GitHub's REST objects are built for programs that ignore what they don't need: user objects carry more than fifteen URL templates, plus reactions and metadata a model will never use. Passed through unchanged, five to seventeen kilobytes per record times a perPage limit of 100 is a page no model can hold. The server's page sizes were reasonable for an HTTP client and far too large for a context window.

The fix that worked, each time, was projection. PR #2563, merged on 28 May 2026, added minimal types for project items. The maintainers measured five live items at about 12,875 tokens before and 901 after — a 93.0% cut, from roughly 2,575 tokens per item to 180. Scaled to a page of 50, that is 128,750 tokens down to 9,010. The page size stayed the same, and every record got smaller. The same fix is now spreading endpoint by endpoint: a fields parameter on the issue and pull-request list and search tools, whose README notes that "omitting body drops the largest per-result data"; PR #2675 making search_pull_requests compact by default with minimal_output: false to get the raw objects back; and the minimal types collected in pkg/github/minimal_types.go. As of October 2026, pull_request_read is next in line, still returning full patches from get_files (#3236).

Pagination you cannot reach is not pagination

Issue #2122, from March 2026, shows the other way record pagination fails. pull_request_read's get_review_comments method advertised cursor pagination, but the after argument was missing from the tool's schema, and page and perPage were silently ignored by three methods. The model could not ask for a second page because nothing in the schema let it. The results, above about 50–100KB, pushed Cursor and VS Code to 100% CPU and needed a hard restart. PR #2489 exposed after and the issue closed in May. A cursor only works if the model can see it in the schema, and only helps if every page fits.

Why a record count cannot bound a window

A page size in records makes the page's token cost whatever the records happen to weigh. A budget fixes the cost and lets the record count vary.

Datadog reached the same conclusion from the opposite kind of data: "a Datadog log message might be only 100 characters or it might be 1 MB", and no record count bounds that. So they changed what a page means — "The server cuts off its response after a certain number of tokens and returns a cursor for more" — and the cursor carries the rest.

What a size-aware page looks like in code, with MotherDuck's and Grafana's servers as worked examples, is laid out in Step 4 of Large Results & Pagination in MCP. A server that pages by count alone leaves the rest to the host, and the protocol gives the host nothing to go on.

The protocol pages the catalog, not the call

MCP has pagination, but only for list methods such as tools/list. tools/call has no cursor, no size limit and no chunking, so every server that pages a tool result invents its own page, perPage, after or cursor argument, as GitHub did. Proposals to change that have been filed and closed, and the roadmap items that might help have no date; the spec's rules and that history are in Large Results & Pagination in MCP.

Two bloats, one of them addressed

The well-known context savings of the past year are mostly on the other side of this line. Tool search, code-mode catalogs and synced tool descriptions all shrink the tool definitions the model reads before it calls anything; none of them makes a single list_pull_requests response smaller. The protocol pages the catalog, and so does most of the industry's optimisation work. The numbers, and why they should not fund a result-side fix, are in When MCP Results Overload the Context.

So the host decides, and the hosts disagree

One server, one response, six different outcomes. Nothing in the result tells the host which one the server would want.

With nothing in the protocol, every host sets its own ceiling and its own behaviour past it, and the hosts do not even agree on the unit: some count tokens, others characters. A page a server author tuned to fit one host can be several times over the line on another. Each host's current limit, and the knobs an operator controls, are kept in one list in Step 2 of When MCP Results Overload the Context.

The file spill is not a page

Spilling to a file looks like the host solving the problem: the result is kept and the window is spared. Datadog's write-up notes that Cursor and Claude Code now do this, and that it "is not in the MCP spec yet". The file only helps if the model can read part of it and act on what it reads, and public reports against Notion's, Atlassian's and VS Code's integrations show each of those steps breaking; they are collected as host-side test cases in Step 3 of the operations guide. Each host fixes its own spill on its own schedule, so a server cannot rely on any of them.

What to do on the server side

The server is the one place that knows what a record contains and which fields matter. GitHub's eighteen months come down to four practices; the full contract, with arguments, envelope and sizing, is in Large Results & Pagination in MCP.

Count the page in tokens

Take a budget, not just a count: add records until the next would cross it, then return a cursor, and keep a record cap as a backstop. That is the change Datadog made and GitHub's record-counted pages never did.

Project before you page

Return the fields an agent will act on by default and make the full object something it asks for, keeping the identifiers later calls need. GitHub's −93% came entirely from this, with no change to page size.

Put the truncation flag and the remedy in the result

The model should never have to guess whether it got everything. Fetch one more than the limit to know, say so in a field, and add a sentence on what to do next; Anthropic's tool-writing guidance asks for truncation text that steers the agent toward "many small and targeted searches". A worked envelope, with the cursor in the arguments and the flag in the result, is in Step 4 of the deep dive.

Design for the smallest host

Size your default page for the strictest host your users run, not for the one on your desk, and treat any one host's per-tool override as an escape hatch rather than a fix. The two numbers that set that ceiling today are in Step 3 of the deep dive.

FAQ

Does MCP support pagination for tool results?

No. MCP pagination covers only list methods such as tools/list, so a server that pages tool results has to define its own cursor argument; the rules are in Large Results & Pagination in MCP.

Why did GitHub's MCP server overflow context windows if it paginated?

Its pages were counted in records, and its records were large — 5–6KB per commit and 17–36KB per pull request in the reported cases. Minimal response types, not smaller pages, fixed it: PR #2563 cut project items by 93%.

What happens when an MCP tool result is too large in Claude Code?

Claude Code warns, then saves an over-cap successful result to a file and gives the model the path, while oversized errors are cut to their first and last characters. The current thresholds are listed in When MCP Results Overload the Context.

How big should an MCP tool's page be?

Set it in tokens or characters, not records, size it for the strictest host your users run, and return a truncated flag and a cursor with it. The full contract is in Large Results & Pagination in MCP.

Is the MCP spec going to add tool-result pagination?

Not soon: the roadmap plans a redesign of the tools/call result shape with no date, and proposals for streaming partial results were closed. The details are tracked in Large Results & Pagination in MCP.