MCP 진행률 검수: 100% 표시 뒤 최종 결과를 확인하는 법
MCP 진행률 100%만으로 도구 성공을 확정하면 후속 업무가 먼저 실행될 수 있습니다. progressToken과 최종 응답, 오류를 나눠 확인하는 인수표와 예외 처리 기준을 정리합니다.
이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스
MCP 진행률 100%도 최종 성공을 뜻하지 않습니다. 2026-11-06 기준, 최종 도구 응답과 업무 검수 조건까지 확인합니다.
진행 막대가 꽉 찼는데 결과가 도착하지 않으면 사용자는 다시 실행할지 기다릴지 망설입니다. 자동 후속 작업이 붙어 있다면 화면의 오해가 다음 업무로 이어집니다. 진행 표시와 성공 확정을 따로 검수하면 이 경계를 설명할 수 있습니다.
MCP 진행률 100%를 언제 완료로 표시하나요?#
최종 도구 응답을 받은 뒤 오류와 합의한 출력 조건을 확인해야 완료를 확정합니다. progress/total이 같아지는 순간에는 처리량 표시만 갱신하고, 최종 결과를 기다리는 상태를 유지합니다. 이 판정 방식은 아래의 설계 예시입니다.
MCP 공식 Progress 문서는 1.0/1.0 알림 뒤에 별도의 메서드 응답이 오는 흐름을 보여줍니다. progressToken을 보냈어도 서버가 진행 알림을 보내는 것은 선택 사항입니다. 알림을 못 받았다는 이유만으로 실패나 멈춤으로 단정해서도 안 됩니다. MCP Progress 공식 원문을 2026-11-06 확인했습니다.
화면 담당자는 처리 중·최종 결과 대기·성공·오류의 구분을, 연동 담당자는 어느 요청의 결과인지 확인합니다. 승인된 데이터나 외부 시스템의 변경까지 인수해야 한다면 그 조건을 최종 응답과 별도로 정합니다. 진행 퍼센트가 실제 반영 여부를 증명해 주지는 않습니다.
progressToken과 최종 응답은 어떻게 연결하나요?#
진행 알림은 progressToken으로 요청을 찾고, 최종 응답은 JSON-RPC 요청 id로 연결합니다. 두 식별자를 요청 단위로 함께 보관해야 같은 화면의 상태를 갱신할 수 있습니다. 활성 요청들이 같은 진행 토큰을 공유하면 어느 작업의 진척인지 구분할 수 없습니다.
공식 스키마는 요청의 \_meta.progressToken과 알림의 params.progressToken을 정의합니다. progress는 누적 진척, total은 알고 있을 때 제공하는 전체량입니다. total이 없으면 퍼센트를 만들지 않고 처리 중이라는 사실이나 현재 처리량을 보여주는 방식이 맞습니다. 2026-07-28 MCP 스키마를 2026-11-06 확인했습니다.
아래는 가상의 호출에서 화면과 후속 동작을 점검하는 표입니다. 모든 행은 같은 도구 호출의 관측 조건을 비교합니다. 비용·시간·실제 장애 빈도를 나타내는 표가 아닙니다.
| 관측한 이벤트 | 확인할 증거 | 표시 예시 | 후속 업무 |
|---|---|---|---|
| progress=100, total=100 | 연결된 활성 progressToken, 최종 응답 미도착 | 처리량 100%, 최종 결과 대기 | 보류 |
| total 없는 진행 알림 | 같은 요청의 토큰과 증가하는 progress | 처리 중, 처리량만 표시 | 보류 |
| 최종 도구 응답, isError=true | 요청 id와 도구 오류 내용 | 도구 오류 | 보류·오류 처리 |
| 최종 응답이 JSON-RPC error | 요청 id와 프로토콜 오류 | 호출 오류 | 보류·오류 처리 |
| 알림 없이 정상 최종 응답 | 요청 id, 오류 여부와 합의한 출력 | 검수 조건 충족 시 성공 | 합의한 조건으로 허용 |
| 다른 토큰 또는 종료 뒤 알림 | 활성 요청 매핑·종료 상태 | 기존 상태 유지, 이상 이벤트 분류 | 알림만으로 실행하지 않음 |
진행 알림은 완료 뒤 발신을 멈춰야 한다는 것이 공식 규칙입니다. 종료 뒤 들어온 알림으로 화면을 다시 처리 중으로 바꾸지 않는 처리는 방어 설계로 둡니다. 이런 알림의 발신이 규격상 허용된다는 뜻은 아닙니다.
100% 뒤 오류가 오는 흐름은 어떻게 시험하나요?#
같은 호출에 진행 완료 수치와 오류 응답을 차례로 넣고, 화면과 후속 작업이 성공으로 바뀌지 않는지 확인합니다. 아래 추적은 숫자와 토큰을 임의로 정한 축약 설계 예시입니다. 완전한 통신 메시지나 실제 SDK 실행 결과는 아닙니다.
요청: id=73, progressToken=call-73
알림: call-73, progress=100, total=100
화면: 처리량 100%, 최종 결과 대기
최종 tools/call 결과: resultType=complete, isError=true
화면: 도구 오류, 후속 업무 보류진행 알림에서 100/100×100=100%를 계산해도 성공 여부는 정해지지 않습니다. MCP tools/call의 도구 오류는 isError로 표현되며, JSON-RPC 오류 응답과 구분됩니다. MCP Tools 공식 문서를 2026-11-06 확인했습니다. resultType=complete만 확인하고 isError를 빠뜨리는 구현도 검수 대상입니다.
정상 최종 응답이 먼저 오는 경우에는 이후의 진행 알림을 기다리느라 완료를 늦추지 않아야 합니다. 반대로 최종 응답이 없으면 원인을 확인할 상태로 남깁니다. 이때 재호출 허용 여부는 별도로 정하며, 진행 표시만 보고 변경 작업을 다시 실행하지 않습니다.
기존 취소·추가 입력 검수와 무엇이 다른가요?#
이 글은 2026-07-28 규격의 서버→클라이언트 진행 알림과 일반 tools/call 최종 응답을 다룹니다. 공식 규격 발표문의 발표일은 2026-07-28이며, 확인일은 2026-11-06입니다. 이 버전은 요청마다 버전·클라이언트 기능을 전달하므로 이전 세션 방식의 예제를 그대로 복사하지 않습니다.
최종 응답에 추가 입력이 필요하다고 나오는 MRTR 흐름은 MCP 추가 입력 재개 검수에서 다룹니다. input_required를 성공으로 처리하거나 이 글의 오류 예시로 뭉뚱그리지 마세요. 확장 Tasks의 별도 작업 상태도 이번 인수표에 포함하지 않습니다.
중단 버튼을 누른 뒤 외부 영향이 남는 문제는 AI 에이전트 취소 검수, 결과의 구조화 값과 설명이 서로 다른 문제는 MCP 도구 결과 일치 검수에서 확인할 수 있습니다. 진행 화면을 고치는 것만으로 이 문제들이 해결되지는 않습니다.
알파카랩스는 온톨로지 구축 서비스에서 AI·MCP 조회의 PoC, 출처·권한과 운영 인수 범위를 협의한다고 공개합니다. 자사 제공 방식에 대한 자기표기이며, 진행률 기능의 납품 실적이나 성과 보장을 뜻하지 않습니다. 프로토콜 개정 또는 2026-12-06에 버전과 판정 조건을 다시 확인할 계획입니다.
MCP 진행률 검수 FAQ#
MCP 진행률 100%는 성공 응답인가요?
진행 알림의 수치는 성공 응답이 아닙니다. 같은 요청의 최종 도구 응답을 받은 뒤 isError와 합의한 업무 조건을 확인해야 합니다. 100% 뒤 최종 오류가 오는 흐름도 인수표에 넣습니다.
progressToken을 보내면 진행 알림이 반드시 오나요?
서버의 진행 알림 전송은 선택 사항입니다. 알림이 없어도 정상 최종 응답을 받을 수 있습니다. 알림 부재와 호출 실패를 구분합니다.
total이 없을 때 진행률 퍼센트를 보여줘도 되나요?
전체량을 모르면 신뢰할 퍼센트를 계산할 수 없습니다. 처리 중 상태와 제공된 현재 처리량을 표시하고, 추정치를 쓰려면 실제 진척과 구분하는 별도 설계가 필요합니다.
완료 뒤 진행 알림이 오면 다시 처리 중으로 바꾸나요?
규격은 완료 뒤 진행 알림 발신을 멈추도록 요구합니다. 클라이언트의 방어 설계로는 이미 종료한 요청의 상태를 유지하고 예상 밖 알림을 분류합니다. 알림만으로 후속 업무를 실행하지 않습니다.
resultType이 complete면 isError는 확인하지 않아도 되나요?
complete는 추가 입력을 요청하는 응답과 구분되는 결과 종류입니다. 도구 오류 여부는 isError로 따로 확인해야 합니다. 정상 도구 결과여도 실제 업무의 인수 조건을 충족하는지는 별도 검수 대상입니다.
MCP 완료 인수표 협의#
민감정보를 제거한 진행 이벤트와 최종 응답 표본을 준비하면 요청별 상태·오류·후속 허용 조건을 협의할 수 있습니다. 실제 고객 원문이나 비밀값은 보내지 않고, 필요한 자료와 접근 범위를 먼저 정합니다. 산출물은 요청별 완료 인수표 초안이며, 소요 시간은 자료와 연동 범위를 확인한 뒤 정합니다.