分页机制

• 1. 分页模型
• 2. 响应格式
• 3. 请求格式
• 4. 分页流程
• 5. 支持分页的操作
• 6. 实现指南
• 7. 错误处理

协议版本: 2025-06-18

模型上下文协议（Model Context Protocol，MCP）支持对可能返回大型结果集的列表操作进行分页处理。分页允许服务器以较小的数据块形式返回结果，而不是一次性返回所有结果。

当通过互联网连接到外部服务时，分页尤其重要，但对于本地集成来说也很有用，可以避免大型数据集带来的性能问题。

1. 分页模型

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

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

2. 响应格式

分页开始时，服务器发送的响应包括：

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

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "resources": [...],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}

3. 请求格式

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

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

4. 分页流程

5. 支持分页的操作

以下 MCP 操作支持分页：

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

6. 实现指南

1. 服务器应该：

   • 提供稳定的游标
   • 优雅地处理无效游标

2. 客户端应该：

   • 将缺失的 nextCursor 视为结果的结束
   • 支持分页和非分页流程

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

   • 不要对游标格式做出假设
   • 不要尝试解析或修改游标
   • 不要在会话之间持久化游标

7. 错误处理

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