nextCursor
nextCursor is an opaque pagination token an MCP server may include in a tools/list response. Its presence means more tools exist and the client must call again with that cursor to get them. A client that ignores it sees a truncated list and receives no error explaining why.
Updated
What is nextCursor?
nextCursor is how MCP pagination works. When a server has more tools than it wants to return at once, it sends the first page plus a cursor string, and the client passes that string back in the cursor parameter of the next tools/list call. The server decides the page size, and a client must not assume one.
The value is opaque. Clients must not parse it, infer ordering from it, or construct one.
When is the list finished?
When nextCursor is absent. That is the only end signal: the current spec revision (2026-07-28) tells clients to treat a missing nextCursor as the end of results.
An empty string is not the end. The spec says a client may only check whether a cursor was provided, not what it contains, so "nextCursor": "" is a valid cursor and MUST NOT be read as the last page. A loop that stops on a falsy value stops early on exactly this case.
The same mechanism covers all four list methods: tools/list, resources/list, resources/templates/list and prompts/list. A client that paginates tools but not prompts has the bug for prompts. A cursor the server no longer accepts should come back as error -32602 (invalid params); the spec has no rule for a cursor that repeats, so a client that caps the number of pages it will fetch cannot be looped forever by a broken server.
Why is it the easiest bug to ship?
Because the failure is silent and the common case hides it. A client that never implements cursor handling gets a valid response, no error, and a list that is simply shorter than reality.
Nothing signals the problem. The connection succeeded, the JSON parsed, and tools came back. The only symptom is a model that cannot find a function the server genuinely offers.
How often do servers actually paginate?
Almost never, which is the trap. Zero of the 14 servers we connected to on 5 August 2026 returned a non-empty nextCursor, including the one that returned 213 tools in a single response.
So a client with no pagination support passes every test against real servers today and breaks the first time it meets one that paginates. Rarity is why the bug survives review, not a reason to skip the handling.
Example
A paginating server answers the first tools/list with 50 tools and a cursor. The correct second call repeats the method with that value:
{"jsonrpc": "2.0", "id": 3, "method": "tools/list", "params": {"cursor": "eyJvZmZzZXQiOjUwfQ"}}
A client that stops after the first response reports 50 tools for a server that has 120, and every downstream count built on that number inherits the error.