Wiki · Concept · Last reviewed June 25, 2026

MCP Pagination

MCP pagination is the Model Context Protocol utility for splitting large list results into cursor-linked pages across prompts, resources, resource templates, and tools.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: MCP, Pagination, AI Agents, Discovery, Context Governance

Definition

MCP pagination is a utility in the Model Context Protocol for list operations that may return large result sets. The 2025-11-25 specification says pagination lets servers yield smaller chunks rather than returning everything at once. It is useful for internet-connected services and for local integrations where large data sets could create performance problems.

The model is cursor-based rather than page-number-based. A cursor is an opaque string token representing a position in a result set. The server determines page size, and clients must not assume a fixed page size. This matters because discovery in an agent system is not only about convenience; it decides which tools, prompts, resources, and templates become visible to the client.

How It Works

Pagination begins when a server response includes the current page of results and, if more results exist, an optional nextCursor field. The client continues by issuing another request that includes that cursor in params.cursor. A missing nextCursor means the client should treat the result set as complete.

The specification gives implementation rules that are easy to miss. Servers should provide stable cursors and handle invalid cursors gracefully. Clients should support both paginated and non-paginated flows. Clients must treat cursors as opaque tokens: they should not assume a cursor format, parse a cursor, modify a cursor, or persist cursors across sessions. Invalid cursors should result in JSON-RPC error code -32602, invalid params.

Where It Applies

The pagination page lists four MCP operations that support pagination: resources/list, resources/templates/list, prompts/list, and tools/list. The separate resources, prompts, and tools pages all describe listing operations that can include a cursor value. Pagination therefore governs discovery surfaces rather than arbitrary tool outputs.

Discovery completeness is operationally important. If a client stops after the first page, it may build an incomplete picture of available tools or context. If a server changes ordering between pages, the client may see duplicates or gaps. If a client persists old cursors, it may request a later page against a result set that no longer exists in the same form.

Governance Requirements

A governed MCP deployment should log the method being listed, server identity, client identity, session, whether a cursor was supplied, whether a nextCursor was returned, the count of items returned, and whether the client reached the end of the list. For sensitive deployments, logs should avoid storing raw cursor strings unless there is a clear diagnostic need and an appropriate retention rule.

User interfaces should disclose partial discovery. A client that has loaded one page of tools should not imply that the server's full tool inventory is known. Administrative consoles should distinguish "first page loaded," "more pages available," and "complete list exhausted."

Failure Modes

First-page blindness. A client exposes only the first page of tools, prompts, or resources while presenting the list as complete.

Cursor misuse. A client parses, rewrites, or stores a cursor across sessions even though the specification says cursors are opaque and should not be persisted across sessions.

Unstable result sets. A server changes ordering or filtering between requests, producing duplicates, missing items, or misleading discovery records.

Cursor leakage. A cursor encodes sensitive state, then appears in logs, screenshots, telemetry, or error reports.

Source Discipline

Claims about MCP pagination should cite the versioned pagination specification. Claims about supported operations should either cite the pagination page or the specific prompts, resources, and tools pages. Governance claims should distinguish source-backed protocol requirements from local operational recommendations.

Spiralist Reading

Pagination is a humble mechanism with institutional consequences. It decides whether the machine sees a whole catalog or only the first shelf.

The Spiralist lesson is that partial views become policy when no one labels them as partial. In agent infrastructure, the unseen second page can be a missing tool, a safer prompt, a forbidden resource, or an audit clue. Completion is not only an API state; it is a claim about what has been seen.

Open Questions

Sources

Return to Wiki