페이지네이션

페이지네이션 (Pagination)

큰 결과 집합을 반환할 수 있는 목록 연산을 페이지네이션하는 방법을 설명하는 페이지예요. MCP는 번호가 매겨진 페이지 대신 불투명한 커서(cursor) 기반 접근을 사용해요.

출처: 문서

본문

Model Context Protocol (MCP)은 큰 결과 집합을 반환할 수 있는 목록 연산의 페이지네이션을 지원해요. 페이지네이션은 서버가 결과를 한꺼번에 내놓는 대신 더 작은 덩어리로 나누어 내놓을 수 있게 해 줘요.

페이지네이션은 인터넷으로 외부 서비스에 연결할 때 특히 중요하지만, 로컬 통합에서도 큰 데이터 집합의 성능 문제를 피하는 데 유용해요.

참고 (Note): 간결함을 위해 이 페이지의 요청 예시는 _meta 요청 메타데이터(io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo, io.modelcontextprotocol/clientCapabilities)를 생략해요. 모든 요청은 MUST 필수 _meta 필드를 포함해야 해요. _meta를 참조하세요.

페이지네이션 모델 (Pagination Model)

MCP의 페이지네이션은 번호가 매겨진 페이지 대신 불투명한 커서 기반 접근을 사용해요.

커서(cursor) 는 결과 집합의 위치를 나타내는 불투명한 문자열 토큰이다
페이지 크기는 서버가 결정하며, 클라이언트는 MUST NOT 고정 페이지 크기를 가정해서는 안 된다

응답 형식 (Response Format)

서버가 다음을 포함하는 응답을 보내면 페이지네이션이 시작돼요:

결과의 현재 페이지
더 많은 결과가 있다면 선택적 nextCursor 필드

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

요청 형식 (Request Format)

클라이언트는 커서를 받은 후, 그 커서를 포함한 요청을 발행해 페이지네이션을 계속할 수 있어요:

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

페이지네이션 흐름 (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 연산이 페이지네이션을 지원해요:

resources/list - 사용 가능한 리소스 나열
resources/templates/list - 리소스 템플릿 나열
prompts/list - 사용 가능한 프롬프트 나열
tools/list - 사용 가능한 도구 나열

구현 지침 (Implementation Guidelines)

서버는 SHOULD:
- 안정적인 커서를 제공한다
- 유효하지 않은 커서를 우아하게 처리한다
클라이언트는 SHOULD:
- 누락된 nextCursor를 결과의 끝으로 취급한다
- 페이지네이션된 흐름과 페이지네이션되지 않은 흐름을 모두 지원한다
클라이언트는 MUST 커서를 불투명한 토큰으로 취급해야 한다:
- 커서 형식에 대해 가정하지 않는다
- 커서를 파싱하거나 수정하려 하지 않는다
- non-null 값이 제공됐는지(예: 빈 문자열은 유효한 커서이므로 MUST NOT 결과의 끝으로 취급해서는 안 됨) 외에 커서 값에 기반한 어떤 판단도 하지 않는다

오류 처리 (Error Handling)

유효하지 않은 커서는 SHOULD 코드 -32602 (Invalid params)의 오류가 되어야 해요.