Pagination

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 MAY NOT be fixed

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",
  "method": "resources/list",
  "params": {
    "cursor": "eyJwYWdlIjogMn0="
  }
}

Pagination Flow

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: List Request (no cursor)
    loop Pagination Loop
      Server-->>Client: Page of results + nextCursor
      Client->>Server: List Request (with cursor)
    end

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).