VOOZH about

URL: https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination

⇱ Pagination - Model Context Protocol

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Skip to main content
The Model Context Protocol (MCP) supports paginating list operations that may return large result sets. Pagination allows servers to yield results in smaller chunks rather than all at once. 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.

Pagination Model

Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages.
  • The cursor is an opaque string token, representing a position in the result set
  • Page size is determined by the server, and clients MUST NOT assume a fixed page size

Response Format

Pagination starts when the server sends a response that includes:
  • The current page of results
  • An optional nextCursor field if more results exist
{
 "jsonrpc": "2.0",
 "id": "123",
 "result": {
 "resources": [...],
 "nextCursor": "eyJwYWdlIjogM30="
 }
}

Request Format

After receiving a cursor, the client can continue paginating by issuing a request including that cursor: 
{
 "jsonrpc": "2.0",
 "id": "124",
 "method": "resources/list",
 "params": {
 "cursor": "eyJwYWdlIjogMn0="
 }
}

Pagination Flow

Operations Supporting Pagination

The following MCP operations support pagination:
  • resources/list - List available resources
  • resources/templates/list - List resource templates
  • prompts/list - List available prompts
  • tools/list - List available tools

Implementation Guidelines

  1. Servers SHOULD:
    • Provide stable cursors
    • Handle invalid cursors gracefully
  2. Clients SHOULD:
    • Treat a missing nextCursor as the end of results
    • Support both paginated and non-paginated flows
  3. Clients MUST treat cursors as opaque tokens:
    • Don’t make assumptions about cursor format
    • Don’t attempt to parse or modify cursors
    • Don’t persist cursors across sessions

Error Handling

Invalid cursors SHOULD result in an error with code -32602 (Invalid params).

Was this page helpful?

LoggingSchema Reference
⌘I
Assistant
Responses are generated using AI and may contain mistakes.