Pagination in MCP

Status in the 2026-07-28 spec: core (server utility)

Pagination in MCP is how a server splits a long list, such as hundreds of tools or thousands of resources, into smaller pages. The server returns one page plus a nextCursor token. The client sends that token back to get the next page, and stops when no cursor comes back.

MCP uses cursors, not page numbers. The pagination page of the 2026-07-28 spec calls it "an opaque cursor-based approach." This page explains how it works, which methods use it, and the small rules that trip clients up.

Why pagination exists

Some servers expose a lot. A document server might list thousands of files as resources. A large platform might offer hundreds of tools. Sending everything in one response is slow and memory-hungry, especially over the internet.

The spec says pagination "is especially important when connecting to external services over the internet, but also useful for local integrations to avoid performance issues with large data sets."

How it works

Which methods paginate

The 2026-07-28 spec lists four core operations:

Extensions reuse the same pattern. The Skills extension says skills/list "supports pagination," for example.

The flow

1. The client sends a list request with no cursor.
2. The server returns the first page. If more results exist, it adds nextCursor.
3. The client sends the same list request with "cursor" set to that value.
4. Repeat until a response has no nextCursor.

Here is a page of results, from the spec:

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "resultType": "complete",
    "resources": [],
    "nextCursor": "eyJwYWdlIjogM30=",
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

(We emptied the resources array for brevity. The spec shows it as [...].)

The client then asks for the next page:

{
  "jsonrpc": "2.0",
  "id": "124",
  "method": "resources/list",
  "params": { "cursor": "eyJwYWdlIjogMn0=" }
}

In real 2026-07-28 traffic, each request also carries required _meta fields such as the protocol version. The spec's examples omit them for brevity.

The rules for each side

The spec's implementation guidelines are short:

• Servers should provide stable cursors and handle invalid cursors gracefully.
• Clients should treat a missing nextCursor as the end and support both paginated and non-paginated servers.
• Clients must treat cursors as opaque: no assumptions about format, no parsing, no edits.

An invalid cursor should return JSON-RPC error -32602 (Invalid params).

What changed across spec versions

Pagination has been in MCP since the first spec, 2024-11-05. The model itself has stayed the same. Two things changed in 2026-07-28, compared with 2025-11-25:

The old line about sessions disappeared because sessions were removed. See why MCP became stateless.

The changelog also asks servers to return tools/list in a deterministic order. That helps client caching and model prompt caching, and it makes pages more predictable.

Common mistakes

• Treating an empty string as "done". The spec says an empty string "MUST NOT be treated as the end of results." Only a missing (or null) nextCursor ends the list.
• Decoding the cursor. The example cursor looks like base64 JSON. That is an implementation detail. Clients must not parse or build cursors.
• Assuming a page size. The server sets it, and it can change.
• Only reading the first page. A client that ignores nextCursor silently misses tools. Users then wonder why a server "has no tool for that."
• Unstable server cursors. If your cursor depends on an order that shifts between calls, clients may see duplicates or gaps.
• Ignoring caching hints. With ttlMs, clients can reuse a list instead of paging through it again on every request.

Who needs to care

If you are evaluating an MCP client for a large server, check that it pages through full lists. If you build servers, paginate long lists and keep the order stable. Both points belong in a technical review, alongside the items in how to choose MCP servers.

Next step

Pagination is one of several small utilities in the spec. Next, see how long operations report status in MCP progress notifications, or return to the MCP specification reference.

Frequently asked questions