Skip to content

Pagination

The Model Context Protocol (MCP) は、大きな結果集合を返し得る list operation に対して pagination をサポートします。Pagination により、server はすべてを一度に返すのではなく、より小さな chunk に分けて結果を返せます。

Pagination は、internet 越しに外部 service へ接続する場合に特に重要ですが、大きな data set による性能問題を避けるために、ローカル統合でも有用です。

Pagination Model

MCP における pagination は、番号付き page ではなく、不透明な cursor ベースの方式を使います。

  • cursor は、結果集合内の位置を表す不透明な文字列 token です
  • page size は server が決定し、client は固定の page size を仮定してはなりません (MUST NOT)

Response Format

pagination は、server が次を含む response を返したときに始まります。

  • 現在の page の結果
  • さらに結果が存在する場合は、任意の nextCursor field
{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "resources": [...],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}

Request Format

cursor を受け取った後、client はその cursor を含む request を発行することで pagination を継続できます。

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

Pagination Flow

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

Operations Supporting Pagination

次の MCP operation は pagination をサポートします。

  • resources/list - 利用可能な resource の一覧
  • resources/templates/list - resource template の一覧
  • prompts/list - 利用可能な prompt の一覧
  • tools/list - 利用可能な tool の一覧

Implementation Guidelines

  1. server は次を行うべきです (SHOULD)。

    • 安定した cursor を提供する
    • 無効な cursor を適切に扱う

  2. client は次を行うべきです (SHOULD)。

    • nextCursor が存在しない場合を結果の終端として扱う
    • pagination あり・なしの両方のフローをサポートする

  3. client は、cursor を不透明な token として扱わなければなりません (MUST)。

    • cursor の format について仮定しない
    • cursor を parse したり変更したりしない
    • session をまたいで cursor を永続化しない

Error Handling

無効な cursor は、コード -32602（Invalid params）の error になるべきです (SHOULD)。