分页 - MCP 中文文档

Model Context Protocol (MCP) 支持对可能返回大型结果集的列表操作进行分页。分页允许服务器以小批量方式返回结果，而不是一次性返回所有结果。当通过互联网连接外部服务时，分页尤为重要，但对于本地集成也很有用，可以避免大型数据集带来的性能问题。

For brevity, the request examples on this page omit the _meta request metadata (io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo, and io.modelcontextprotocol/clientCapabilities). Every request MUST include the required _meta fields; see _meta.

分页模型

MCP 中的分页使用基于不透明游标的方法，而不是编号页。

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

响应格式

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

当前页的结果
如果存在更多结果，则包含可选的 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="
  }
}

分页流程

支持分页的操作

以下 MCP 操作支持分页：

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

实施指南

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

错误处理

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

基础协议

客户端功能

服务器功能

分页

分页模型

响应格式

请求格式

分页流程

支持分页的操作

实施指南

错误处理

​分页模型

​响应格式

​请求格式

​分页流程

​支持分页的操作

​实施指南

​错误处理

分页模型

响应格式

请求格式

分页流程

支持分页的操作

实施指南

错误处理