MCP 工具结果分页怎么设计：游标失效、重复项与增量验收

接入 MCP 工具后，最容易被低估的不是“能不能返回下一页”，而是 Agent 在重试、插入新数据、切换会话之后，是否还能拿到一份不漏项、不重复的结果。一个看似正常的 next_cursor，如果没有稳定排序和失效策略，最终会让模型把同一条工单读两遍，或者把刚创建的记录误判为不存在。

先看一个会“少读一条”的 MCP 场景

假设工具 search_tickets 按 updated_at DESC 返回工单，每页 20 条。Agent 读完第一页后保存了游标；这时一条新工单插入到列表顶部，第二次请求仍然按“当前列表的第 21 条”取数据。结果是原来排在第 20 位的工单被挤过边界，可能永远不会出现在后续页里。

另一类问题出在重试环节：服务端已经生成并返回第二页内容，但客户端连接在拿到响应前意外断开。Agent 再次携带同一游标发起请求，如果服务端把游标当成一次性消费令牌，可能直接返回空页；如果服务端忽略游标版本校验，又可能从错误的位置重新开始读取。

先保护三类结果资产，再谈字段设计

查询条件是资产边界

游标不能脱离原查询逻辑复用。至少要绑定工具名、过滤条件的规范化摘要、排序字段和页大小。否则同一个游标被拿去查询其他数据集时，即便服务端能正常解码内容，也完全没法保证返回结果的语义正确。

稳定排序是防漏读的第一道控制

updated_at 不是唯一键，同一毫秒内的两条记录可能顺序不稳定。实际返回可以使用 (updated_at, ticket_id) 这样的复合排序，并把最后一条记录的两个值都放入游标。下一页使用严格的“小于”条件，而不是依赖数据库的偏移量。

游标需要签名和生命周期

建议把游标编码成带版本的结构，再进行签名。载荷可以包含 query_hash、sort_key、last_id、snapshot_id、issued_at 与 expires_at。签名解决篡改问题，过期时间解决长期复用旧边界的问题；两者不要混为一谈。

返回协议怎么让 Agent 能恢复

工具结果不宜只返回数据数组。一个便于上层编排的最小响应结构可以是：

{
  "items": [{"id": "T-1042", "updated_at": "2026-08-25T04:00:12Z"}],
  "page": {
    "next_cursor": "v1.signed.payload",
    "has_more": true,
    "cursor_expires_at": "2026-08-25T04:10:00Z",
    "snapshot_id": "snap-7f2c"
  },
  "consistency": "snapshot"
}

consistency 要明确告诉调用方：这是固定快照，还是随时变化的数据集。快照模式适合导出和审计，增量模式适合持续同步。若请求使用了过期或查询不匹配的游标，建议返回结构化错误，例如 CURSOR_EXPIRED、CURSOR_QUERY_MISMATCH 或 CURSOR_VERSION_UNSUPPORTED，不要用空列表掩盖异常。

把重复项和漏项变成可验收的证据

测试分页逻辑不能只断言“每页都能返回数据”。先准备一组带唯一 ID 的固定测试数据，记录所有页返回的 ID 集合和完整顺序，再分别在翻页的间隙插入、更新、删除部分记录。最终至少核对四件事：

• 同一快照范围内，所有返回 ID 的并集是否和预期集合完全一致。
• 相邻页面之间是否存在重复 ID，尤其是排序键取值相同的记录。
• 重试完全相同的请求，是否能得到一致的页指纹。
• 游标过期之后，触发的恢复动作是否会重新发起查询，而不是静默从第一页开始读取。

页指纹可以由 snapshot_id、首尾 ID、条目数量和内容摘要组成。它不是安全凭证，却能帮助调用方判断“这是同一页的重放”还是“数据边界已经变化”。

重试策略要和游标语义配套

网络错误发生在响应提交之前时，可以使用同一个请求幂等键重试，不要无条件生成全新游标。服务端如果暂存了短期的请求结果副本，就能返回同一页内容，客户端也能依据页指纹确认没有重复消费数据。

如果服务端明确返回 CURSOR_EXPIRED，恢复动作应由调用方选择：审计型任务重新建立快照并从头读取，实时型任务改用“最后确认的更新时间加唯一 ID”作为增量边界。两种路径都要在结果中记录恢复原因，方便后续排查 Agent 为什么重新读取。

常见问题

游标里只放最后一条记录 ID 可以吗？

只有在排序字段本身唯一且取值不会回退的场景下才勉强成立。常用的时间戳字段通常满足不了这个条件，建议把排序键和唯一 ID 一起存入游标。

页大小改变后，旧游标还能继续用吗？

可以禁止跨查询复用游标，也可以做兼容逻辑，但必须有明确的版本规则。针对审计和批量处理这类场景，直接返回查询不匹配的提示通常更安全，避免同一任务里混入不同分页语义的结果。

游标过期要不要自动从第一页重试？

不要在底层静默重试。应该把游标失效的具体原因返回给编排层，由编排层决定要不要重新建立查询快照还是切换到增量读取模式，否则后续返回的结果里很难追溯重复数据的来源。

把分页协议纳入工具上线清单

MCP 工具的分页接口，真正的验收标准不是“第二次请求能正常返回数据”，而是面对排序并列、数据变动、网络重试和过期游标这些场景时，依然能给出可追踪可解释的结果。把查询指纹、稳定复合排序、快照语义、结构化错误提示和页指纹一起纳入协议设计，Agent 才有机会在调用失败后自主恢复流程，而不是靠猜测继续发起无效调用。