An empty-string nextCursor in an MCP list result is not the end: keep paging until nextCursor is missing, and never parse the cursor

Error strings

• none listed

Situation

You write an MCP client or an agent loop that calls tools/list, resources/list, resources/templates/list or prompts/list on a server you do not control.

Symptom

Some tools, resources or prompts never show up, or paging stops early, because the loop read only the first page, stopped on a falsy cursor or assumed a fixed page size.

Cause

MCP list operations use an opaque cursor instead of numbered pages, and the server decides the page size. When more results exist, the result can include nextCursor. The specification says clients SHOULD treat a missing nextCursor as the end, and an empty string is a valid cursor that MUST NOT be treated as the end. A check like if (!nextCursor) in JavaScript or if not next_cursor in Python treats the empty string as the end and drops the remaining pages. Decoding or editing a cursor, even one that looks like base64, relies on a format the server does not promise.

Fix

1) After each list call, continue while nextCursor is present and not null: nextCursor != null in JavaScript (this covers both null and undefined), next_cursor is not None in Python. Do not use a falsy check. 2) Send the cursor back exactly as received, in params.cursor. Do not decode, edit or build cursors yourself. 3) Do not assume a page size. A short or empty page is not the end while nextCursor is still present. 4) The specification says an invalid cursor SHOULD give error -32602 (Invalid params), a code that is also used for other bad parameters. If a cursor request fails that way, you can start once more from the first page without a cursor, after clearing the items collected so far. 5) Put a page limit in the loop and stop when the server sends the same cursor twice in a row. When either happens, report the list as incomplete instead of using it as the full list.

Snippet

# illustrative: session.request stands for your MCP client call
cursor, tools, complete = None, [], False
for _ in range(100):  # page limit
    params = {} if cursor is None else {"cursor": cursor}
    result = session.request("tools/list", params)
    tools += result["tools"]
    nxt = result.get("nextCursor")
    if nxt is None:  # "" is a valid cursor, not the end
        complete = True
        break
    if nxt == cursor:  # same cursor again: stop
        break
    cursor = nxt
if not complete:
    raise RuntimeError("tools/list incomplete")

Verify

Against a test server that returns at least two pages, check that the number of collected items equals the number the server holds. Then let one page return nextCursor as an empty string, and another page return no items but a nextCursor, and check that the loop requests the next page in both cases instead of stopping.

Source

https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/pagination

Use this via MCP

Streamable HTTP, no authentication: https://agent-economy-data.onrender.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.