MCP 도구 목록 페이지네이션 검수, 첫 페이지에 도구가 없다면

2026년 11월 기준, MCP 도구 목록은 nextCursor가 생략됐을 때 끝납니다. 값이 빈 문자열이어도 다음 요청에 그대로 보내며, 페이지 길이로 끝을 판단하지 않습니다.

사내 에이전트에 재고 조회 도구를 연결하는데 첫 페이지에는 상품 검색 도구만 있다고 가정해 보겠습니다. 페이지가 짧아도 서버가 다음 커서를 보냈다면 재고 조회 도구가 다음 페이지에 있을 수 있습니다. 첫 페이지만 읽은 상태에서 에이전트에 도구가 없다고 알려주면 연동 누락을 기능 제약으로 오인하게 됩니다.

이 글은 MCP 클라이언트의 도구 발견을 인수하는 IT·플랫폼 책임자를 위한 기준입니다. 저장한 목록을 언제 다시 읽어야 하는지는 MCP 도구 목록 캐시, 스트림에서 응답을 온전히 복원하는 문제는 MCP SSE 수신 검수에서 다룹니다.

목록의 마지막 페이지는 무엇으로 확인하나요?#

MCP 2026-07-28의 목록 규칙은 페이지 크기를 서버가 정한다고 설명합니다. 클라이언트는 받은 항목 수나 요청 횟수로 마지막 페이지를 추정할 수 없습니다. 응답에서 nextCursor가 생략되면 현재까지의 결과로 종료합니다. 문자열이 있으면 해석하거나 고치지 않고 다음 요청의 cursor로 보냅니다. 빈 문자열도 포함합니다. 같은 값이 다시 와도 커서 값으로 끝을 판단할 수 없습니다.

예를 들어 if (!nextCursor)로 끝을 검사하면 유효한 빈 문자열에서 멈춥니다. 반대로 tools: []이고 커서도 없다면 정상적으로 끝난 빈 목록일 수 있습니다. 빈 배열과 커서가 함께 오면 커서가 가리키는 다음 페이지를 읽습니다.

무엇을 표본으로 검수하나요?#

같은 서버와 같은 인가 범위에서 도구 목록을 한 번 수집한다고 가정합니다. 각 행은 첫 요청부터 별도로 시작합니다. 가상 요청 기록에서 커서를 그대로 보냈는지와 호출 수를 확인하고, 응답 처리에서 목록 완료 여부를 확인합니다.

async function collect(list, limit) {
  const tools = [];
  let cursor;
  for (let n = 0; n < limit; n++) {
    const params = cursor === undefined ? {} : { cursor };
    const page = await list(params);
    tools.push(...page.tools);
    const next = page.nextCursor;
    if (next === undefined) return tools;
    if (typeof next !== "string") throw Error("bad cursor");
    cursor = next;
  }
  throw Error("page limit");
}

list는 요청 메타데이터를 채우고 응답에서 도구 배열을 꺼내거나 서버 오류를 던지는 함수로 가정했습니다. 코드의 오류명과 호출 한도는 예제 클라이언트의 선택입니다. 커서 값과 관계없이 한도를 적용합니다. 실제 오류 처리에서는 확인한 페이지 수와 실패 분류를 남기고 토큰 원문을 일반 로그에 남기지 않습니다.

첫 페이지만 보여줘도 되는 경우가 있나요?#

관리 화면이 다음 페이지를 열 수 있고 아직 읽지 않은 페이지가 있다는 점을 보여준다면 첫 페이지부터 표시해도 됩니다. 업무 흐름이 목록 전체를 바탕으로 필요한 도구가 없다고 결정한다면, 종료 신호를 보기 전까지는 그 판정을 미룹니다. 호출 한도나 서버 오류로 얻은 일부 결과를 전체 목록으로 저장하지 않습니다.

MCP 명세는 무효 커서에 -32602 응답을 권고합니다. 중간 오류가 나면 권한과 서버 범위를 확인한 뒤 필요할 때 첫 페이지부터 다시 수집합니다. 이전 목록 조각에 새 순회의 페이지를 섞으면 무엇이 빠졌는지 확인하기 어렵습니다. 수집을 끝냈더라도 그 사이 서버 목록이 바뀔 수 있으므로, 스냅숏 보장과 실제 도구 호출 권한은 별도로 확인합니다.

어떤 근거를 확인했나요?#

• MCP 2026-07-28 페이지네이션은 서버가 정하는 페이지 크기, 커서 전달, 빈 문자열과 커서 생략의 차이, 무효 커서 오류를 설명합니다.
• MCP 2026-07-28 도구 명세는 도구 목록의 페이지 구분과 요청 인가에 따른 목록 범위를 설명합니다. 공식 공개 발표는 2026년 7월 28일에 게시됐습니다.

원문과 알파카랩스 업무 자동화·API 연동 서비스는 2026년 11월 8일 확인했습니다. 공개 서비스는 연동 허용 범위, 예외 확인, 재처리와 운영 인수 조건을 협의한다고 안내합니다. 표와 코드는 위 명세를 바탕으로 만든 가상 검수 예시입니다.

MCP 도구 목록 페이지네이션 FAQ#

도구 목록 인수표 초안 협의#

도구 이름과 커서에서 사내 식별 정보를 뺀 목록 응답 표본을 준비해 주세요. 첫 범위 협의에서 완료와 중단을 구분할 인수표를 정리합니다. 소요 시간은 표본과 검수 범위를 확인한 뒤 협의합니다.