MCP Specification · 2026-07-28 · zh-TW

分頁

Pagination

以 opaque cursor 分批取得大型 list result；page size 由 server 決定，client 不得推測 cursor 格式。

MCP 對可能產生大型結果集的 list operations 支援 pagination，讓 server 分批回傳資料，而不是一次傳完。這對 remote services 特別重要，本機 integration 也可避免大量資料造成效能問題。

請求中繼資料（Request metadata）

本頁範例省略 _meta；實際每個 request 仍 MUST（必須）包含 io.modelcontextprotocol/protocolVersion 與 io.modelcontextprotocol/clientCapabilities。io.modelcontextprotocol/clientInfo 為選用欄位，但 client SHOULD（應該）在未特別停用時提供。

分頁模型（Pagination Model）

MCP 使用 opaque cursor，而不是 numbered pages：

cursor 是代表結果位置的不透明字串。
Page size 由 server 決定，client MUST NOT（不得）假設固定大小。

回應格式（Response Format）

Server 的 list response 回目前 page，若還有結果則提供選用的 nextCursor：

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

請求格式（Request Format）

收到 cursor 後，client 可在下一次 list request 帶回該 cursor 以繼續分頁：

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

支援分頁的操作（Operations Supporting Pagination）

resources/list
resources/templates/list
prompts/list
tools/list

實作指引（Implementation Guidelines）

Server SHOULD（應該）提供 stable cursors，並妥善處理 invalid cursor。Client SHOULD（應該）支援 paginated 與 non-paginated flow，且把缺少 nextCursor 視為結果結束。

Client MUST（必須）把 cursor 當 opaque token：

不得假設 cursor format。
不得 parse 或修改 cursor。
除了是否提供 non-null value 外，不得依 cursor value 做其他判斷。
空字串是有效 cursor，client MUST NOT（不得）把空字串視為「沒有下一頁」。

錯誤處理（Error Handling）

Invalid cursor SHOULD（應該）回 -32602 Invalid params。