菜单

tools/list 分页:nextCursor,以及被当成 1,000 个的 3,676 个工具

2026-11-06MCP Checkup

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 错误码详解。