分页

模型上下文协议（MCP）支持对可能返回大型结果集的列表操作进行分页。分页允许服务器分批返回较小的结果， 而不是一次性返回全部结果。

通过互联网连接外部服务时，分页尤其重要；对于本地集成，分页也有助于避免大型数据集引发性能问题。

分页模型

MCP 中的分页使用基于不透明游标的方式，而不是页码。

• 游标是不透明的字符串令牌，表示结果集中的一个位置
• 分页大小由服务器决定，客户端 MUST NOT 假定固定的分页大小

响应格式

当服务器发送包含以下内容的响应时，分页开始：

• 当前页的结果
• 如果存在更多结果，则包含可选的 nextCursor 字段

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "resultType": "complete",
    "resources": [...],
    "nextCursor": "eyJwYWdlIjogM30=",
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

请求格式

收到游标后，客户端可以发出包含该游标的请求来_继续_分页：

{
  "jsonrpc": "2.0",
  "id": "124",
  "method": "resources/list",
  "params": {
    "cursor": "eyJwYWdlIjogMn0="
  }
}

分页流程

  sequenceDiagram
    participant Client
    participant Server

    Client->>Server: List Request (no cursor)
    loop Pagination Loop
      Server-->>Client: Page of results + nextCursor
      Client->>Server: List Request (with cursor)
    end

支持分页的操作

以下 MCP 操作支持分页：

• resources/list - 列出可用资源
• resources/templates/list - 列出资源模板
• prompts/list - 列出可用提示词
• tools/list - 列出可用工具

实现指南

1. 服务器 SHOULD：

   • 提供稳定的游标
   • 妥善处理无效游标

2. 客户端 SHOULD：

   • 将缺少 nextCursor 视为结果结束
   • 同时支持分页和非分页流程

3. 客户端 MUST 将游标视为不透明令牌：

   • 不要假定游标格式
   • 不要尝试解析或修改游标
   • 除了判断是否提供了非空值以外，不要根据游标值作出任何判断（例如，空字符串是有效游标， 因此 MUST NOT 将其视为结果结束）

错误处理

无效游标 SHOULD 导致错误码为 -32602（参数无效）的错误。