分页

Model Context Protocol (MCP) 支持对可能返回大量结果集的列表操作进行分页。分页允许服务端以较小的分块逐步返回结果，而不是一次性返回全部内容。

在通过互联网连接外部服务时，分页尤为重要，但对于本地集成而言，它同样有助于避免大数据集带来的性能问题。

NOTE

为简洁起见，本页的请求示例省略了 _meta 请求元数据（io.modelcontextprotocol/protocolVersion、io.modelcontextprotocol/clientInfo 和 io.modelcontextprotocol/clientCapabilities）。每个请求 MUST（必须）包含所需的 _meta 字段；参见 _meta。

分页模型

MCP 中的分页采用不透明的基于游标的方式，而非编号页面。

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

响应格式

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

当前页的结果
如果还有更多结果，则包含可选的 nextCursor 字段

json

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

请求格式

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

json

{
  "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 - 列出可用工具

实现指南

服务端 SHOULD（应该）：
- 提供稳定的游标
- 优雅地处理无效游标
客户端 SHOULD（应该）：
- 将缺失的 nextCursor 视为结果结束
- 同时支持分页和非分页流程
客户端 MUST（必须）将游标视为不透明的令牌：
- 不要对游标格式做任何假设
- 不要尝试解析或修改游标
- 除了判断是否提供了非空值之外，不要基于游标值做任何判断（例如，空字符串是有效的游标，因此 MUST NOT（不得）被视为结果结束）

错误处理

无效游标 SHOULD（应该）导致错误，错误码为 -32602（Invalid params）。

分页