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.

• Der Cursor ist ein undurchsichtiges String‑Token und repräsentiert eine Position in der Ergebnismenge
• Die Seitengröße wird vom Server bestimmt und MUSS NICHT fix sein

Response Format

Pagination starts when the server sends a response that includes:

• Die aktuelle Ergebnisseite
• Ein optionales Feld nextCursor, falls weitere Ergebnisse vorhanden sind

{
  "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. Server SOLLEN:

   • Stabile Cursor bereitstellen
   • Ungültige Cursor robust behandeln

2. Clients SOLLEN:

   • Fehlenden nextCursor als Ende der Ergebnisse interpretieren
   • Sowohl paginierte als auch nicht paginierte Abläufe unterstützen

3. Clients MÜSSEN Cursor als undurchsichtige Token behandeln:

   • Keine Annahmen über das Cursorformat treffen
   • Cursor nicht parsen oder verändern
   • Cursor nicht über Sitzungen hinweg persistieren

Error Handling

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