Pagination and Streaming in MCP List Endpoints

Opaque cursors and the empty-string trap are tripping up real integrations.

Cover illustration for “Pagination and Streaming in MCP List Endpoints”

Pagination and streaming in MCP list endpoints solve different problems. Opaque cursors govern how clients traverse a catalog, while streaming governs how a response reaches them. Reliable integrations keep that distinction clear, stop only when nextCursor is absent, and apply the caching and notification rules introduced by the 2026-07-28 revision.

Why MCP list endpoints cannot return everything at once

MCP discovery can produce far more data than an agent can use comfortably in one response. The methods tools/list, prompts/list, resources/list, and resources/templates/list expose what a server offers, and tool definitions are particularly substantial. Each includes a name, a description, and a full JSON Schema for its parameters. An unbounded discovery response can crowd out the information the agent needs for its actual task.

The MCP pagination specification identifies this problem for remote servers reached over the internet and for local integrations with large catalogs. The protocol therefore defines pagination for the discovery layer, where the number of available entries can grow without a useful bound. This is a deliberate contract for list operations rather than a general solution for every large MCP response, and clients must follow its constraints to discover the complete catalog.

How the opaque cursor model works and what clients must not assume

The MCP pagination specification defines an opaque cursor as a position token whose internal format is hidden from the client. Traversal begins with a list request that has no cursor. The server returns a page and, when more results exist, a nextCursor field. The client then calls the same list method with that value in params.cursor. Only the absence of nextCursor ends the loop.

For tools/list, the request-and-response relationship is therefore between the response’s nextCursor and the next request’s params.cursor. The client passes the received value back unchanged. It does not calculate a page number or derive the next position from the number of tools returned. The server controls page size and may return one item or a hundred on any given page. A short page is not proof of completion.

Opacity also places limits on what clients may do with the token. Clients must not assume a cursor format, parse or modify cursors, or persist them across sessions. The last restriction limits cursor reuse. Servers should provide stable cursors and handle invalid ones gracefully, with invalid cursors producing error code -32602 for Invalid params as a specification recommendation.

A compliant client should also support non-paginated results. A server may return its entire catalog in the first response and omit nextCursor. That response uses the same completion rule as the last page of a longer traversal. There is no need to infer which kind of server is responding before discovery begins.

The empty-string cursor trap that silently truncates a server's catalog

The first request returns HTTP 200 and a valid result, but the client never asks for the remaining pages. No protocol error announces the omission. The agent simply operates on a partial catalog, with no indication that other tools or resources exist.

The failure can start with a common C# predicate, string.IsNullOrEmpty(cursor). Used as a loop terminator, it treats an empty string as equivalent to a missing continuation token. The MCP pagination specification explicitly makes an empty string a valid cursor and prohibits treating it as end-of-results. A server that returns that value after page one has requested another page.

This bug is difficult to recognize from the result alone because the client has no independent page-size signal. A small first page could be complete, or it could be followed by many more pages. Both are valid server choices. Counting returned items therefore cannot repair the incorrect predicate, and successful HTTP delivery says nothing about whether the client finished traversal.

In brief pseudocode, the rule is while nextCursor is present, request the next page with that exact value. Here, a value is present if it is neither null nor undefined, so an empty string still passes the test. The loop ends when the response omits nextCursor.

How the 2026-07-28 spec revision changed the ground under list endpoints

The 2026-07-28 MCP changelog removes protocol-level sessions and makes the protocol fully stateless. In Streamable HTTP, that removes the Mcp-Session-Id header and the initialize / notifications/initialized handshake. Every request now includes its protocol version and client capabilities in _meta fields. All results must also include resultType, with a value of "complete" or "input_required".

The earlier transport was informally deprecated in 2025-03-26, when Streamable HTTP replaced it, and formally deprecated under the lifecycle policy in 2026-07-28. That history is relevant to migration, but the current discovery semantics follow from statelessness. The transport change is not merely a different way to keep the same session-based behavior.

In particular, tools/list, resources/list, and prompts/list no longer vary per connection. The tool set belongs to the server and the authenticated principal. Servers that previously changed their tool set according to session state have no mechanism for that behavior in the current protocol. For cross-call state, SEP-2567 instead uses explicit, server-minted handles passed as ordinary tool arguments.

This separation also simplifies deployment behind gateways. Stateless requests can reach server instances through a plain round-robin load balancer with no need for protocol-level session state. Discovery still depends on the authenticated principal, however. Removing connection-specific catalogs does not turn every server response into data that can be shared across users.

Why ttlMs and cacheScope are now required, not optional hints

The 2026-07-28 MCP changelog makes ttlMs and cacheScope required under SEP-2549. They belong on results from tools/list, prompts/list, resources/list, resources/read, and resources/templates/list. These fields make freshness and sharing scope explicit in the stateless model. Their inclusion is no longer an optional optimization. Server authors targeting this revision must emit them, and client authors must honor their meaning.

The two fields answer different caching questions. ttlMs expresses freshness in milliseconds, telling the client how long the response is valid, and is modeled on HTTP Cache-Control max-age. cacheScope allows or prohibits caching by shared intermediaries. A value of "public" allows shared caching, while "private" prohibits sharing across users. A response can be fresh without being safe to share.

Omitting the fields is also a live compatibility failure. Claude Code has rejected tool lists with a validation error when they were missing. A filed bug report challenges that strict rejection because the reference SDK may allow the fields to be left out. That disagreement reveals a mismatch between validation expectations and SDK behavior, rather than removing the requirement described by the revision. For implementers targeting it, relying on omission leaves a concrete failure path.

Incorrect scope creates a more serious problem than rejection. If a generic cache or CDN stores a "private" result and serves it to another user, the result is a cross-user data leak. The field sets a security boundary as well as rules for how to use the cache. Clients and intermediaries must preserve that boundary even when a response remains within its stated freshness period.

How streaming fits into the list endpoint picture — and where it does not

Streamable HTTP controls delivery of a single response, while pagination controls traversal across responses. Streaming is not a substitute for pagination. A large catalog may need several list requests whether each response arrives as JSON or through SSE. The continuation decision still comes from nextCursor.

The transport uses a single endpoint, and the server determines the response type. Clients must advertise both application/json and text/event-stream in the Accept header so that either format is acceptable. The server can then return a single JSON object or an SSE response for that request. Both forms can carry a paginated result with nextCursor. Once that result is available, the client follows the same cursor loop.

Continuous, push-based delivery offers limited client flow control and makes recovery harder when a broken stream requires restarting the entire stream. Pagination is client-pulled, groups data into logical units, and allows resumption from a cursor. Those are differences between delivery strategies, not a reason to bypass MCP’s list contract when SSE is selected.

How change notifications work after the session model was removed

The 2026-07-28 MCP changelog replaces the HTTP GET endpoint and resources/subscribe / resources/unsubscribe with subscriptions/listen. The replacement is a single long-lived POST-response stream that clients explicitly open for change notifications.

Clients opt in to specific notification types, including toolsListChanged, promptsListChanged, resourcesListChanged, and resourceSubscriptions. The server acknowledges the subscription and tags each notification with io.modelcontextprotocol/subscriptionId. Request-scoped notifications take a separate path. For example, notifications/progress remains on the response stream of the request it concerns.

Reconnects also have an explicit consequence for clients. Servers keep no subscription state across them, so clients must re-subscribe after any reconnect. This requirement follows the same stateless model that removed connection-dependent list results, while still allowing a long-lived stream for opted-in notifications.

A list_changed notification signals that the client should fetch the list again. It is not a diff and gives no details about which entries changed. For tools, the client must call tools/list, potentially traverse every page again, and compare the results.

A client gets change notifications only while it has an open subscriptions/listen stream. Its cached catalog can go stale silently. The practical choice is to subscribe and restore the subscription after reconnects, or to re-poll tools/list on a schedule.

The open question: pagination for tool responses, not just tool lists

Tool invocations that return large datasets have no equivalent pagination mechanism in the current specification. Server authors must still control how large those responses can be.

Cursor pagination also has limits within discovery itself. Federated backends, eventual consistency, and live datasets that reorder between requests can make cursor semantics unreliable. In those cases, an agent cannot rely on page order to give it a stable control boundary. Correctly returning a token unchanged avoids client-side corruption, but it does not establish that the underlying dataset remains ordered throughout traversal.

People in the community also ask whether one pagination strategy works for every query. An opaque cursor can suit an unbounded resource such as a news feed. A bounded question such as “what’s new today?” may benefit from total item counts or page counts, which the current model omits.

For current implementations, the division of responsibility is clear. List endpoints need the cursor loop, required ttlMs and cacheScope fields, and either subscriptions or polling for changes. Tool responses that could grow too large need server-side chunking, reference-based results, or explicit tool-level pagination. Those remain bespoke patterns rather than extensions clients can assume from MCP’s list pagination contract.

Sources

  1. Pagination - Model Context Protocol

    Provided the authoritative specification for opaque cursors, traversal rules, and the empty-string cursor requirement that the article explains in detail.

  2. Key Changes - Model Context Protocol

    Provided the details of the 2026-07-28 revision, including removal of sessions, addition of resultType, ttlMs/cacheScope requirements, and the subscriptions/listen replacement.

  3. Pagination - Model Context Protocol

    Provided the earlier pagination specification context relevant to the transport deprecation history discussed in the article.

  4. Streamable HTTP - Model Context Protocol

    Provided the Streamable HTTP transport details including the single endpoint, Accept header requirements, and SSE/JSON response formats described in the article.

  5. Client.list_tools silently truncates listings with an empty next_cursor · Issue #5025 · PrefectHQ/fastmcp · GitHub

    Provided a real-world example of the empty-string cursor bug silently truncating tool listings.

  6. fix: send an empty-string pagination cursor verbatim on every list adapter by cliffhall · Pull Request #2277 · modelcontextprotocol/inspector · GitHub

    Provided a concrete example of the empty-string cursor fix in the MCP inspector, illustrating the bug described in the article.

  7. The 2026-07-28 Specification

    Provided the official announcement of the 2026-07-28 specification changes including statelessness and the new caching and subscription model.

  8. Caching hints - MCP Python SDK

    Provided details on the ttlMs and cacheScope caching hint fields and their semantics referenced in the article.

The Context Window Editors