MCP Pagination Empty `nextCursor`: Don't Stop After Page One
MCP pagination empty nextCursor handling looks like a tiny null check, but the wrong predicate can hide most of a server's catalog. In the final 2026-07-28 specification, cursors are opaque strings. An empty string is valid; only a missing nextCursor ends traversal. In a nullable C# response model, that absence is represented by null . I built a small .NET 10 verifier because this failure is…
MCP pagination breaks silently when the server omits the nextCursor field in the response. According to the 2026-07-28 specification, a non-null nextCursor indicates continuation of page traversal. An empty string is still considered a valid nextCursor token. In a nullable C# response model, an empty string is represented as null, while a missing nextCursor signifies the end of traversal.
This bug is particularly insidious because the request succeeds, the first page looks normal, and no error is displayed indicating that subsequent pages are missing. MCP uses cursor pagination for several endpoints, including tools/list, prompts/list, resources/list, and resources/templates/list. The server determines the page size, so a client cannot infer completion from the number of returned items.
The official pagination specification dictates that the client should continue requesting pages as long as a non-null nextCursor is provided. The client must forward this token without modifying or parsing it. An empty string is a valid token, but if it is missing, the client should request another page. A common C# loop inadvertently assumes that an empty cursor means no further pages exist, treating the response as the final page.
This loop can be fixed by explicitly checking for a null cursor, which would terminate the loop when the server omits the nextCursor field. The corrected loop iterates through pages, adds the returned tools to the collection, and updates the cursor only if a non-null value is received. If the cursor is null, the loop exits, ensuring that the client only receives complete pages.
This fix allows the client to handle both empty strings and opaque cursor tokens correctly, without altering their values. The fix also includes a page cap and cancellation handling to prevent indefinite looping in case of a faulty server. While the specification does not explicitly cover all aspects of cursor handling, this fix ensures that the client adheres to the correct protocol and avoids silently stopping after the first page.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
