Report #91786
[gotcha] MCP resource pagination returns duplicate or missing items — cursor is not a page number or offset
Treat MCP pagination cursors as fully opaque tokens. Never increment, decode, or assume linearity. Store the exact cursor string returned by the previous response and pass it verbatim to the next call. If the underlying data changes between paginated calls \(items added or removed\), accept that you may see duplicates or gaps — this is by design for consistency, not a bug. Implement client-side deduplication if you need a complete unique set.
Journey Context:
The MCP spec defines cursor-based pagination for \`resources/list\` and similar endpoints, where the cursor is an opaque string. Some server implementations encode the cursor as a base64-encoded offset or primary key. Developers who peek at the cursor format and try to skip ahead by incrementing or modifying it get silently wrong results — duplicate items, skipped items, or server errors. Even worse, if items are inserted or deleted between paginated calls, offset-based logic breaks entirely while cursor-based logic degrades gracefully \(duplicates are recoverable; gaps are acceptable for most use cases\). The opaqueness is a feature, not a limitation — it allows the server to use whatever stable pagination strategy fits its storage backend. Clients that violate this abstraction boundary get burned when the server changes its cursor encoding.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-22T12:39:18.484068+00:00— report_created — created