Paginating tools/list: nextCursor, and the 1,000 tools that were 3,676
In early October, one of the reports on MCP Checkup said a server had 1,000 tools. Its tools/list response held 1,000 tools and a nextCursor, and our probe read only that first response. When we finally read the whole list, it had 3,676. Another server listed 50 tools and a cursor; it really had 62.
When we found it on 9 October, we first changed the report pages to say "at least 1,000 tools" and stopped presenting the first page as the whole list. On 22 October the probe started following nextCursor. The first server's report now lists 3,824 tools.
Any client can make the same mistake. Here is how tools/list pagination works, how to check that your server does it right, and what we do now.
How pagination works
The specification covers it in Server → Utilities → Pagination. The rules below hold in both revision 2025-11-25 and revision 2026-07-28. They apply to tools/list, prompts/list, resources/list and resources/templates/list.
- A response carries one page of results. If more exist, it also carries
nextCursor, an opaque string. - To get the next page, the client sends the same method again with
params.cursorset to that string. - The server picks the page size, and clients must not assume a fixed one.
- When
nextCursoris missing, the list has ended.
A first page that has more after it:
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"search","inputSchema":{"type":"object"}}],"nextCursor":"eyJvZmZzZXQiOjUwfQ"}}
The request for the next page:
{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{"cursor":"eyJvZmZzZXQiOjUwfQ"}}
Servers should give stable cursors and handle invalid ones gracefully. An invalid cursor should get a JSON-RPC error with code -32602 (Invalid params). Clients must treat cursors as opaque: no parsing and no editing.
Revision 2026-07-28 adds one sentence that matters. A client may decide only whether a non-null cursor was given, and an empty string is a valid cursor, so it must not be read as the end of the list. Revision 2025-11-25 did not say what "" meant. It also told clients not to keep cursors from one session to the next. 2026-07-28 has no sessions, so that line is gone.
Count your own pages
This script opens a 2025-11-25 session. It then reads tools/list page by page until nextCursor is missing or null. An empty-string cursor is sent back like any other. It needs bash, curl and jq, and it stops after 20 pages, so a server that keeps sending cursors can't keep it looping.
URL=https://your-server.example/mcp
V=2025-11-25
SID=$(curl -sS -D - -o /dev/null "$URL" \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H "mcp-protocol-version: $V" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"pagination-test","version":"1"}}}' \
| awk 'tolower($1)=="mcp-session-id:"{print $2}' | tr -d '\r')
H=(-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -H "mcp-protocol-version: $V")
[ -n "$SID" ] && H+=(-H "mcp-session-id: $SID")
curl -sS -o /dev/null "$URL" "${H[@]}" -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
NEXT=; PAGE=1; TOTAL=0
while :; do
if [ -z "$NEXT" ]; then PARAMS='{}'; else PARAMS=$(jq -nc --argjson c "$NEXT" '{cursor: $c}'); fi
BODY=$(jq -nc --argjson id "$((PAGE + 1))" --argjson p "$PARAMS" '{jsonrpc: "2.0", id: $id, method: "tools/list", params: $p}')
RESP=$(curl -sS "$URL" "${H[@]}" -d "$BODY" | sed -n '/^{/p; s/^data: //p')
N=$(printf '%s' "$RESP" | jq '.result.tools | length')
TOTAL=$((TOTAL + N))
NEXT=$(printf '%s' "$RESP" | jq -c '.result.nextCursor')
if [ "$NEXT" = null ]; then echo "page $PAGE: $N tools"; break; fi
echo "page $PAGE: $N tools, nextCursor present"
PAGE=$((PAGE + 1))
[ "$PAGE" -gt 20 ] && { echo "stopped after 20 pages"; break; }
done
echo "total: $TOTAL tools on $PAGE page(s)"
We ran it on 25 October against the server with 62 tools:
page 1: 50 tools, nextCursor present
page 2: 12 tools
total: 62 tools on 2 page(s)
jq -c prints the cursor as JSON, quotes included, so the script can tell an empty string from a missing cursor. The sed line accepts either a plain JSON body or a Server-Sent Events reply. A server that sets no session simply gets no mcp-session-id header.
On the server side
- Leave
nextCursorout of the last page. Under 2026-07-28,""is a cursor, and a conforming client will ask for one more page. Don't send it to mean "the end". - Make cursors survive a while. A client may read page 1, do something else, and come back. A cursor that holds an offset into a list that has changed since can skip or repeat tools. If your tool list changes often, base the cursor on something stable, such as the last tool name returned.
- Reject a bad cursor with -32602. Don't silently start again from page 1. A client that loops on that answer would never stop.
- Pick a page size, and don't promise it. Clients must not assume one. If many of your clients only ever read the first response, a larger page means fewer of them see a partial list.
On the client side
- Follow
nextCursoruntil it is missing or null. Send an empty-string cursor back like any other. Also set a limit on pages or tools, so a broken server can't keep you looping. - Don't parse or edit cursors. Start from the first page again in each new session.
- If you stop early, say so. A list you didn't read to the end is partial, and so is everything computed from it: counts, fingerprints, and "this tool isn't offered". Showing a first page as the whole list was exactly our mistake.
How many servers this affects
Most servers are small. These numbers cover 3,778 servers with a stored tool list, using the latest list for each, read on 25 October 2026 at 19:44 UTC:
| Tools per server | Value |
|---|---|
| Median | 7 |
| 90th percentile | 28 |
| 99th percentile | 118 |
| Largest | 3,824 |
Of these, 49 list more than 100 tools, 18 more than 200 and 2 more than 500. Our runs don't record how many pages each server used, so we can't say how many of them paginate. When we checked on 9 October, 2 of the 2,980 servers we tracked then sent a nextCursor. Large lists are where an unfollowed cursor goes unnoticed, because a first page of hundreds of tools looks complete.
What our probe does now
Each run follows nextCursor for up to 10 pages or 5,000 tools, whichever comes first. A null cursor ends the list; any string, "" included, means another page. Every page goes through the same address checks as the first request, and no request carries credentials.
If a list is still not finished at that limit:
tools_listis still VERIFIED, because the calls themselves were well-formed.- The toolset and schema fingerprints are UNVERIFIED with the reason
tools_list_incomplete, and so are the two checks against an approved baseline. We don't sign a fingerprint of part of a list.
On 25 October that applied to one server.
Check your own server
Look your server up at mcpcheckup.com/servers, or ask an agent connected to MCP Checkup to run get_mcp_report on it. The report shows how many tools we read, and says so when the list wasn't read to the end. For how a server should answer a call to a tool that isn't on its list, see MCP error codes explained.