태스크

MCP 장시간 작업을 위한 비동기 태스크 실행

experimental-ext-tasks 저장소에 MCP 태스크의 전체 명세와 문서가 있습니다.

모든 도구 호출이 즉시 반환되는 것은 아닙니다. CI 파이프라인, 배치 처리, 사람 승인 등 일부 작업은 초, 분, 또는 그 이상이 소요됩니다. MCP 태스크는 서버가 블로킹 대신 영속적인 핸들을 반환할 수 있게 하여, 클라이언트가 진행 상황을 폴링하고, 필요할 때 입력을 제공하며, 재연결 후 최종 결과를 가져올 수 있게 합니다.

왜 그냥 블로킹하지 않나요?

태스크는 블로킹이 해결할 수 없는 문제를 해결합니다:

• 장기 연결 불필요. 블로킹은 작업 기간 동안 연결을 묶어둡니다. 많은 클라이언트와 전송 중간자는 타임아웃을 적용합니다.
• 충돌 복원력. 태스크 ID는 영속적인 핸들입니다. 클라이언트가 연결을 끊거나 재시작해도 같은 ID로 폴링을 재개할 수 있습니다.
• 진행 상황 가시성. 태스크는 상태 메타데이터(working, input_required, completed, failed, cancelled)와 선택적 상태 메시지를 제공합니다.
• 실행 중 상호작용. 태스크에 입력이 필요할 때(예: 사용자 확인을 위한 요청) input_required로 이동하고 요청을 표시합니다. 클라이언트가 tasks/update를 통해 응답합니다.
• 서버 주도. 서버가 요청별로 태스크 생성 여부를 결정합니다.

태스크 작동 방식

1. Capability 협상. 클라이언트가 요청별 capabilities에 io.modelcontextprotocol/tasks를 포함합니다.
2. 태스크 생성. 서버가 taskId, 초기 상태, TTL, 권장 폴링 간격을 포함하는 CreateTaskResult(resultType: "task")를 반환합니다.
3. 폴링. 클라이언트가 taskId로 tasks/get을 호출합니다.
4. 실행 중 입력. input_required 상태이면 tasks/get 응답에 inputRequests가 포함됩니다. 클라이언트가 tasks/update를 통해 이를 처리합니다.
5. 완료. 상태가 completed이면 result 필드에 최종 출력이 포함됩니다.
6. 취소. 클라이언트가 언제든 tasks/cancel을 보낼 수 있습니다.

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: tools/call (with tasks capability)
    Server-->>Client: CreateTaskResult (taskId, status: working)

    loop Poll until terminal
        Client->>Server: tasks/get (taskId)
        Server-->>Client: Task (status: working)
    end

    Note over Client,Server: Server needs user input
    Client->>Server: tasks/get (taskId)
    Server-->>Client: Task (status: input_required, inputRequests)
    Client->>Server: tasks/update (taskId, inputResponses)
    Server-->>Client: ack

    loop Poll until terminal
        Client->>Server: tasks/get (taskId)
        Server-->>Client: Task (status: working)
    end

    Client->>Server: tasks/get (taskId)
    Server-->>Client: Task (status: completed, result)

태스크 사용 시기

장시간 작업. CI 파이프라인, 배치 데이터 처리, 모델 학습 작업(분 또는 시간 소요).

사람 개입 워크플로우. 승인 게이트, 검토 단계, 사용자 확인이 필요한 모든 작업.

외부 작업 시스템. 서버가 이미 작업 ID를 사용하는 API를 래핑하는 경우.

불안정한 연결. 모바일 클라이언트, 간헐적인 네트워크, 연결이 끊어지는 환경.

배치 처리. 많은 항목을 처리하는 작업에서 부분 진행 상황이 의미 있는 경우.

태스크 라이프사이클

completed, failed, cancelled는 종단 상태입니다 — 한번 도달하면 태스크 상태가 변경되지 않습니다.

알림

서버는 notifications/tasks를 통해 상태 업데이트를 푸시할 수 있습니다. 클라이언트는 subscriptions/listen 메커니즘을 통해 이를 옵트인합니다. 각 알림은 전체 태스크 상태를 전달하므로 추가 tasks/get 라운드 트립이 필요 없습니다. 기본적으로는 폴링을 사용합니다.

구현 가이드

MCP 클라이언트 구현

1. 요청별 capabilities에서 지원 선언:

{
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {
        "extensions": {
          "io.modelcontextprotocol/tasks": {}
        }
      }
    }
  }
}

2. 다형 결과 처리 — 표준 결과 또는 resultType: "task"의 CreateTaskResult를 받을 준비를 합니다.
3. pollIntervalMs를 준수하며 tasks/get으로 폴링합니다. 종단 상태에 도달할 때까지 계속합니다.
4. input_required 처리 — inputRequests를 읽고, 사용자 또는 모델에게 요청을 제시하고, tasks/update를 통해 응답을 제출합니다.
5. 충돌이나 재시작 후 폴링을 재개할 수 있도록 태스크 ID를 영속적으로 저장합니다.

MCP 서버 구현

1. 지원 광고:

{
  "capabilities": {
    "extensions": {
      "io.modelcontextprotocol/tasks": {}
    }
  }
}

2. CreateTaskResult를 반환하기 전에 클라이언트가 지원을 선언했는지 확인합니다.
3. 고유한 taskId, 초기 상태, ttlMs, pollIntervalMs와 함께 resultType: "task"를 반환합니다. 응답을 보내기 전에 태스크가 영속적으로 생성되어야 합니다.
4. tasks/get 처리 — 각 폴링에 현재 상태를 반환합니다. 종단 상태에는 result(완료 시) 또는 error(실패 시) 필드를 포함합니다.
5. tasks/update 처리 — 미처리된 inputRequests에 매핑된 inputResponses를 수락합니다. 빈 결과로 응답합니다.
6. tasks/cancel 처리 — 취소 요청을 빈 결과로 응답합니다. 가능할 때 이를 이행하지만, 취소는 협력적입니다.

클라이언트 지원

참고: MCP 태스크는 핵심 MCP 명세의 익스텐션입니다. 호스트 지원은 클라이언트마다 다릅니다.

익스텐션 지원은 클라이언트 매트릭스를 참조하세요. 태스크 지원은 클라이언트와 서버 모두의 명시적인 옵트인이 필요합니다.

원문(영어): https://modelcontextprotocol.io/extensions/tasks/overview · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/extensions/tasks/overview