tools/list 分页:nextCursor,以及被当成 1,000 个的 3,676 个工具
10 月初,MCP Checkup 上有一份报告说某个 server 有 1,000 个工具。它的 tools/list 响应里有 1,000 个工具,外加一个 nextCursor,而我们的探测器只读了这第一个响应。后来把整份列表读完,一共 3,676 个。另一个 server 列出 50 个工具和一个 cursor,实际有 62 个。
10 月 9 日发现这个问题后,我们先改了报告页:写成「至少 1,000 个工具」,不再把第一页当成整份列表。10 月 22 日,探测器开始跟着 nextCursor 翻页。第一个 server 的报告现在列出 3,824 个工具。
任何客户端都可能犯同样的错。下面说说 tools/list 的分页规则、怎么检查自己的 server 做得对不对,以及我们现在怎么做。
分页的规则
规范在 Server → Utilities → Pagination 一节讲分页。下面这些规则在 2025-11-25 和 2026-07-28 两个版本里都一样,适用于 tools/list、prompts/list、resources/list 和 resources/templates/list。
- 一个响应装一页结果。后面还有的话,响应里再带一个
nextCursor,它是一个不透明的字符串。 - 要下一页,客户端再发一次同样的方法,把
params.cursor设成这个字符串。 - 每页多大由 server 决定,客户端不能假设固定的页大小。
- 没有
nextCursor,就是列表结束了。
后面还有内容的第一页:
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"search","inputSchema":{"type":"object"}}],"nextCursor":"eyJvZmZzZXQiOjUwfQ"}}
请求下一页:
{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{"cursor":"eyJvZmZzZXQiOjUwfQ"}}
server 应当提供稳定的 cursor,并妥善处理无效的 cursor。无效 cursor 应当回 code 为 -32602(Invalid params)的 JSON-RPC 错误。客户端必须把 cursor 当成不透明的:不解析,不修改。
2026-07-28 版多了一句要紧的话:客户端只能判断是否给了一个非 null 的 cursor,空字符串也是合法的 cursor,不能当成列表结束。2025-11-25 版没说 "" 算什么;它还要求客户端不要跨会话保存 cursor。2026-07-28 没有会话了,这一句也就去掉了。
数一数你的页
下面的脚本先建一个 2025-11-25 的会话,然后一页一页地读 tools/list,直到 nextCursor 没有了或者是 null。空字符串的 cursor 照样原样发回去。脚本需要 bash、curl 和 jq;最多读 20 页就停,免得一个一直发 cursor 的 server 把它困在循环里。
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)"
10 月 25 日我们对那个有 62 个工具的 server 跑了一遍:
page 1: 50 tools, nextCursor present
page 2: 12 tools
total: 62 tools on 2 page(s)
jq -c 按 JSON 输出 cursor,引号也带上,所以脚本分得清空字符串和没有 cursor。sed 那一行既能读普通的 JSON 响应体,也能读 Server-Sent Events 的回复。server 不建会话的话,就不会带 mcp-session-id 头。
server 这一侧
- 最后一页不要带
nextCursor。 按 2026-07-28,""也是 cursor,合规的客户端会再要一页。不要用它表示「结束了」。 - cursor 要能管一阵子。 客户端可能读完第 1 页,去做别的事,过一会儿再回来。cursor 里存的如果是偏移量,而列表在这期间变了,就可能跳过或重复工具。工具列表经常变的话,用稳定的东西做 cursor,比如上一页最后一个工具的名字。
- 坏 cursor 回 -32602。 不要悄悄从第 1 页重新开始;客户端如果照着这个回答一直循环,就停不下来了。
- 定一个页大小,但别承诺它。 客户端不能假设页大小。如果你的客户端很多只读第一个响应,页大一些,看到不完整列表的就少一些。
客户端这一侧
- 跟着
nextCursor一直读,直到它没有了或者是 null。空字符串的 cursor 照样发回去。另外给页数或工具数设个上限,免得坏掉的 server 让你一直循环。 - 不解析、不修改 cursor。每个新会话都从第一页重新读。
- 提前停下就要说出来。没读完的列表是不完整的,从它算出来的东西也都不完整:数量、指纹、「没有提供这个工具」的判断。把第一页当成整份列表,正是我们犯的错。
影响有多大
大多数 server 都很小。下面统计的是 3,778 个存有工具列表的 server,每个取最新的那份,读取时间 2026 年 10 月 25 日 19:44 UTC:
| 每个 server 的工具数 | 值 |
|---|---|
| 中位数 | 7 |
| 第 90 百分位 | 28 |
| 第 99 百分位 | 118 |
| 最多 | 3,824 |
其中 49 个列出超过 100 个工具,18 个超过 200 个,2 个超过 500 个。我们的检测记录里没存每个 server 用了几页,所以说不出有多少在分页。10 月 9 日查的时候,当时追踪的 2,980 个 server 里有 2 个发了 nextCursor。没跟着翻页的问题,最容易藏在大列表里:第一页就有几百个工具,看起来像是全部了。
我们的探测器现在怎么做
每轮检测跟着 nextCursor 最多读 10 页或 5,000 个工具,先到哪个算哪个。null 表示列表结束;任何字符串,包括 "",都表示还有下一页。每一页都和第一个请求一样经过地址检查,没有任何请求带凭据。
读到上限时列表还没完的话:
tools_list仍然记 VERIFIED,因为调用本身是合规的;- 工具集指纹和 schema 指纹记 UNVERIFIED,原因是
tools_list_incomplete,和已批准基线对比的两项检查也一样。我们不给半份列表的指纹签名。
10 月 25 日,有一个 server 属于这种情况。
看看你自己的 server
在 mcpcheckup.com/servers 搜你的 server,或者让接入了 MCP Checkup 的 agent 对它调用 get_mcp_report。报告会显示我们读到了多少个工具;列表没读完,也会写明。server 收到对一个不在列表里的工具的调用时该怎么回答,见 MCP 错误码详解。