진행 상황 추적

MCP(Model Context Protocol)는 알림 메시지를 통해 장기 실행 작업에 대한 선택적 진행 상황 추적을 지원합니다. 어느 쪽이든 진행 상황 알림을 전송하여 작업 상태에 대한 업데이트를 제공할 수 있습니다.

진행 흐름

요청에 대한 진행 업데이트를 수신하려는 측은 요청 메타데이터에 progressToken을 포함합니다.

• 진행 토큰은 문자열 또는 정수값이어야 합니다(MUST).
• 진행 토큰은 전송측이 어떤 방법으로든 선택할 수 있지만, 모든 활성 요청에 걸쳐 고유해야 합니다(MUST).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "some_method",
  "params": {
    "_meta": {
      "progressToken": "abc123"
    }
  }
}

수신측은 다음을 포함하는 진행 알림을 전송할 수 있습니다(MAY).

• 원래의 진행 토큰
• 현재까지의 진행 값
• 선택적 "total" 값
• 선택적 "message" 값

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "abc123",
    "progress": 50,
    "total": 100,
    "message": "Reticulating splines..."
  }
}

• progress 값은 총계를 알 수 없는 경우에도 각 알림마다 증가해야 합니다(MUST).
• progress와 total 값은 부동소수점이 될 수 있습니다(MAY).
• message 필드는 관련 사람이 읽을 수 있는 진행 정보를 제공해야 합니다(SHOULD).

동작 요건

1. 진행 알림은 다음 조건을 충족하는 토큰만 참조해야 합니다(MUST). * 활성 요청에서 제공된 토큰 * 진행 중인 작업과 연관된 토큰

2. 진행 요청 수신측은 다음을 할 수 있습니다(MAY). * 진행 알림을 전송하지 않는 선택 * 적절하다고 판단되는 빈도로 알림 전송 * 총계를 알 수 없는 경우 total 값 생략

3. 태스크 보강 요청의 경우, 원래 요청에서 제공된 progressToken은 CreateTaskResult가 반환된 후에도 태스크의 수명 동안 계속 사용해야 합니다(MUST). 진행 토큰은 태스크가 종료 상태에 도달할 때까지 유효하며 태스크와 연결된 상태를 유지합니다. * 태스크에 대한 진행 알림은 초기 태스크 보강 요청에서 제공된 것과 동일한 progressToken을 사용해야 합니다(MUST). * 태스크에 대한 진행 알림은 태스크가 종료 상태(completed, failed, cancelled)에 도달한 후 중단되어야 합니다(MUST).

sequenceDiagram
    participant Sender
    participant Receiver

    Note over Sender,Receiver: Request with progress token
    Sender->>Receiver: Method request with progressToken

    Note over Sender,Receiver: Progress updates
    Receiver-->>Sender: Progress notification (0.2/1.0)
    Receiver-->>Sender: Progress notification (0.6/1.0)
    Receiver-->>Sender: Progress notification (1.0/1.0)

    Note over Sender,Receiver: Operation complete
    Receiver->>Sender: Method response

구현 참고사항

• 전송측과 수신측은 활성 진행 토큰을 추적해야 합니다(SHOULD).
• 양측은 폭주를 방지하기 위해 속도 제한을 구현해야 합니다(SHOULD).
• 진행 알림은 완료 후 반드시 중단되어야 합니다(MUST).

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

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