진행률 패턴

진행률 패턴 (Progress)

MCP는 알림 메시지를 통해 장기 실행 작업의 선택적 진행률 추적을 지원합니다. 서버는 클라이언트가 발행한 요청의 상태를 보고하는 진행률 알림을 보낼 수 있어요(MAY).

출처: MCP 공식 문서 — Progress

진행률 흐름 (Progress Flow)

클라이언트가 요청에 대한 진행률 업데이트를 받고 싶으면, 요청 메타데이터에 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 값은 전체(total)를 몰라도 각 알림마다 증가해야 합니다(MUST).
  • progress와 total 값은 부동소수점일 수 있어요(MAY).
  • message 필드는 관련 인간이 읽을 수 있는 진행 정보를 제공해야 합니다(SHOULD).

동작 요건 (Behavior Requirements)

  1. 진행률 알림은 다음 토큰만 참조해야 합니다(MUST):

    • 활성 요청에서 제공된 토큰
    • 진행 중인 작업과 연결된 토큰

  2. 진행 토큰이 든 요청을 받은 서버는 다음을 할 수 있어요(MAY):

    • 진행률 알림을 전혀 보내지 않기로 선택
    • 적절하다고 생각되는 빈도로 알림을 보냄
    • 전체 값을 모르면 생략
sequenceDiagram
    participant Client
    participant Server

    Note over Client,Server: Request with progress token
    Client->>Server: Method request with progressToken

    Note over Client,Server: Progress updates
    Server-->>Client: Progress notification (0.2/1.0)
    Server-->>Client: Progress notification (0.6/1.0)
    Server-->>Client: Progress notification (1.0/1.0)

    Note over Client,Server: Operation complete
    Server->>Client: Method response

구현 참고 (Implementation Notes)

  • 클라이언트와 서버는 활성 진행 토큰을 추적해야 합니다(SHOULD)
  • 양측 모두 플러딩을 막기 위해 속도 제한을 구현해야 합니다(SHOULD)
  • 진행률 알림은 완료 후 멈춰야 합니다(MUST)

더 알아보기 (Learn more)