페이지네이션

MCP(Model Context Protocol)는 대규모 결과 집합을 반환할 수 있는 목록 조회 작업에 대한 페이지네이션(pagination)을 지원합니다. 페이지네이션을 통해 서버는 모든 결과를 한꺼번에 반환하는 대신 작은 단위로 나누어 제공할 수 있습니다.

페이지네이션은 인터넷을 통해 외부 서비스에 연결할 때 특히 중요하며, 대용량 데이터 집합에서의 성능 문제를 방지하기 위한 로컬 통합에도 유용합니다.

페이지네이션 모델

MCP의 페이지네이션은 번호 매기기 방식 대신 불투명한 커서(cursor) 기반 방식을 사용합니다.

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

응답 형식

페이지네이션은 서버가 다음을 포함하는 응답을 보낼 때 시작됩니다.

• 현재 페이지의 결과
• 더 많은 결과가 있는 경우 선택적 nextCursor 필드

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

요청 형식

커서를 받은 후, 클라이언트는 해당 커서를 포함한 요청을 보내 페이지네이션을 계속할 수 있습니다.

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

페이지네이션 흐름

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

페이지네이션을 지원하는 작업

다음 MCP 작업은 페이지네이션을 지원합니다.

• resources/list - 사용 가능한 리소스 목록 조회
• resources/templates/list - 리소스 템플릿 목록 조회
• prompts/list - 사용 가능한 프롬프트 목록 조회
• tools/list - 사용 가능한 도구 목록 조회

구현 지침

1. 서버는 다음을 수행해야 합니다(SHOULD). * 안정적인 커서 제공 * 잘못된 커서를 우아하게 처리

2. 클라이언트는 다음을 수행해야 합니다(SHOULD). * nextCursor가 없는 경우 결과의 끝으로 처리 * 페이지네이션 및 비페이지네이션 흐름 모두 지원

3. 클라이언트는 커서를 불투명한 토큰으로 처리해야 합니다(MUST). * 커서 형식에 대한 가정 금지 * 커서 파싱이나 수정 시도 금지 * 세션 간 커서 유지 금지

오류 처리

잘못된 커서는 코드 -32602 (Invalid params)의 오류를 반환해야 합니다(SHOULD).

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination