byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

MCP 문서 · Specification

태스크

Tasks · 원문: modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

참고: 태스크는 MCP 명세 버전 2025-11-25에서 도입되었으며 현재 실험적으로 간주됩니다. 태스크의 설계와 동작은 향후 프로토콜 버전에서 변경될 수 있습니다.

MCP(Model Context Protocol)에서는 요청자(requestor) — 통신 방향에 따라 클라이언트 또는 서버 — 가 요청에 태스크(task)를 보강할 수 있습니다. 태스크는 래핑된 요청의 실행 상태 정보를 담고 있는 내구성 있는 상태 머신으로, 요청자의 폴링과 지연된 결과 조회를 위한 것입니다. 각 태스크는 수신자가 생성한 태스크 ID로 고유하게 식별됩니다.

태스크는 비용이 많이 드는 연산과 일괄 처리 요청을 표현하는 데 유용하며, 외부 작업 API와 원활하게 통합됩니다.

정의

태스크는 다음과 같이 "요청자(requestor)"와 "수신자(receiver)"로 참여자를 구분합니다.

사용자 상호작용 모델

태스크는 요청자 주도로 설계되어 있습니다. 요청자는 태스크로 요청을 보강하고 그 결과를 폴링할 책임이 있습니다. 수신자는 어떤 요청(있다면)이 태스크 기반 실행을 지원하는지 엄격하게 제어하고 태스크의 생명주기를 관리합니다.

이 요청자 주도 방식은 결정론적 응답 처리를 보장하고, 동시 요청 전송과 같은 정교한 패턴을 가능하게 합니다. 이는 요청자만이 충분한 컨텍스트를 가지고 조율할 수 있는 작업입니다.

구현체는 필요에 맞는 어떠한 인터페이스 패턴을 통해서도 태스크를 자유롭게 노출할 수 있습니다. 프로토콜 자체는 특정 사용자 상호작용 모델을 강제하지 않습니다.

기능 선언

태스크 보강 요청을 지원하는 서버와 클라이언트는 초기화 중에 tasks 기능을 선언해야 합니다(MUST). tasks 기능은 요청 카테고리별로 구조화되며, 어떤 특정 요청 타입이 태스크 보강을 지원하는지 boolean 속성으로 나타냅니다.

서버 기능

서버는 태스크 지원 여부와, 지원한다면 어떤 서버 측 요청이 태스크로 보강될 수 있는지 선언합니다.

기능 설명
tasks.list 서버가 tasks/list 작업을 지원합니다
tasks.cancel 서버가 tasks/cancel 작업을 지원합니다
tasks.requests.tools.call 서버가 태스크 보강 tools/call 요청을 지원합니다
코드 · 명령
{
  "capabilities": {
    "tasks": {
      "list": {},
      "cancel": {},
      "requests": {
        "tools": {
          "call": {}
        }
      }
    }
  }
}

클라이언트 기능

클라이언트는 태스크 지원 여부와, 지원한다면 어떤 클라이언트 측 요청이 태스크로 보강될 수 있는지 선언합니다.

기능 설명
tasks.list 클라이언트가 tasks/list 작업을 지원합니다
tasks.cancel 클라이언트가 tasks/cancel 작업을 지원합니다
tasks.requests.sampling.createMessage 클라이언트가 태스크 보강 sampling/createMessage 요청을 지원합니다
tasks.requests.elicitation.create 클라이언트가 태스크 보강 elicitation/create 요청을 지원합니다
코드 · 명령
{
  "capabilities": {
    "tasks": {
      "list": {},
      "cancel": {},
      "requests": {
        "sampling": {
          "createMessage": {}
        },
        "elicitation": {
          "create": {}
        }
      }
    }
  }
}

기능 협상

초기화 단계에서 양측은 tasks 기능을 교환하여 어떤 작업이 태스크 기반 실행을 지원하는지 확립합니다. 요청자는 수신자가 해당 기능을 선언한 경우에만 태스크로 요청을 보강해야 합니다(SHOULD).

capabilities.tasks가 정의되지 않은 경우, 상대방은 요청 중에 태스크 생성을 시도해서는 안 됩니다(SHOULD NOT).

도구 수준 협상

도구 호출(tool call)은 태스크 보강을 위해 특별히 고려됩니다. tools/list의 결과에서 도구는 execution.taskSupport를 통해 태스크 지원을 선언하며, 값은 "required", "optional", 또는 "forbidden"일 수 있습니다.

  1. 서버의 기능에 tasks.requests.tools.call이 포함되지 않으면, 클라이언트는 execution.taskSupport 값에 관계없이 해당 서버의 도구에 태스크 보강을 사용해서는 안 됩니다(MUST NOT).
  2. 서버의 기능에 tasks.requests.tools.call이 포함된 경우, execution.taskSupport 값에 따라 처리합니다.
  3. "forbidden" 또는 없는 경우: 클라이언트는 도구를 태스크로 호출해서는 안 됩니다(MUST NOT). 기본 동작입니다.
  4. "optional": 클라이언트는 태스크로 또는 일반 요청으로 도구를 호출할 수 있습니다(MAY).
  5. "required": 클라이언트는 반드시 태스크로 도구를 호출해야 합니다(MUST).

프로토콜 메시지

태스크 생성

태스크 보강 요청은 일반 요청과 다른 2단계 응답 패턴을 따릅니다.

태스크를 생성하려면 요청자는 요청 파라미터에 task 필드를 포함하여 요청을 전송합니다. 요청자는 태스크 생성 이후 유지 기간(밀리초)을 나타내는 ttl 값을 포함할 수 있습니다(MAY).

요청:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "New York"
    },
    "task": {
      "ttl": 60000
    }
  }
}

응답:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "task": {
      "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
      "status": "working",
      "statusMessage": "The operation is now in progress.",
      "createdAt": "2025-11-25T10:30:00Z",
      "lastUpdatedAt": "2025-11-25T10:40:00Z",
      "ttl": 60000,
      "pollInterval": 5000
    }
  }
}

태스크 조회

요청자는 tasks/get 요청을 전송하여 태스크 완료를 폴링합니다. 요청자는 폴링 빈도를 결정할 때 응답에서 제공된 pollInterval을 존중해야 합니다(SHOULD).

요청:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tasks/get",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

응답:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "status": "working",
    "statusMessage": "The operation is now in progress.",
    "createdAt": "2025-11-25T10:30:00Z",
    "lastUpdatedAt": "2025-11-25T10:40:00Z",
    "ttl": 30000,
    "pollInterval": 5000
  }
}

태스크 결과 조회

태스크가 완료되면 tasks/result를 통해 작업 결과를 조회합니다.

요청:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tasks/result",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

응답:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false,
    "_meta": {
      "io.modelcontextprotocol/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

태스크 상태 알림

태스크 상태가 변경되면 수신자는 요청자에게 변경 사항을 알리기 위해 notifications/tasks/status 알림을 전송할 수 있습니다(MAY).

알림:

코드 · 명령
{
  "jsonrpc": "2.0",
  "method": "notifications/tasks/status",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "status": "completed",
    "createdAt": "2025-11-25T10:30:00Z",
    "lastUpdatedAt": "2025-11-25T10:50:00Z",
    "ttl": 60000,
    "pollInterval": 5000
  }
}

요청자는 이 알림 수신에 의존해서는 안 됩니다(MUST NOT). 선택 사항이기 때문입니다.

태스크 목록 조회

요청:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tasks/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

응답:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "tasks": [
      {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
        "status": "working",
        "createdAt": "2025-11-25T10:30:00Z",
        "lastUpdatedAt": "2025-11-25T10:40:00Z",
        "ttl": 30000,
        "pollInterval": 5000
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

태스크 취소

요청:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tasks/cancel",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

응답:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "status": "cancelled",
    "statusMessage": "The task was cancelled by request.",
    "createdAt": "2025-11-25T10:30:00Z",
    "lastUpdatedAt": "2025-11-25T10:40:00Z",
    "ttl": 30000,
    "pollInterval": 5000
  }
}

동작 요건

태스크 상태 생명주기

  1. 태스크는 생성 시 반드시 working 상태에서 시작해야 합니다(MUST).
  2. 수신자는 다음 유효한 경로를 통해서만 태스크를 전환해야 합니다(MUST).
  3. working에서: input_required, completed, failed, cancelled로 이동 가능
  4. input_required에서: working, completed, failed, cancelled로 이동 가능
  5. completed, failed, cancelled 상태는 종료 상태이며 다른 상태로 전환해서는 안 됩니다(MUST NOT).
코드 · 명령
stateDiagram-v2
    [*] --> working
    working --> input_required
    working --> terminal
    input_required --> working
    input_required --> terminal
    terminal --> [*]
    note right of terminal
        Terminal states:
        • completed
        • failed
        • cancelled
    end note

TTL 및 리소스 관리

  1. 수신자는 모든 태스크 응답에 ISO 8601 형식의 createdAt과 lastUpdatedAt 타임스탬프를 포함해야 합니다(MUST).
  2. 수신자는 요청된 ttl 기간을 재정의할 수 있습니다(MAY).
  3. 수신자는 tasks/get 응답에 실제 ttl 기간(무제한이면 null)을 포함해야 합니다(MUST).
  4. 태스크의 ttl 수명이 경과하면 수신자는 태스크와 그 결과를 삭제할 수 있습니다(MAY).
  5. 수신자는 tasks/get 응답에 폴링 간격 제안(밀리초)인 pollInterval 값을 포함할 수 있습니다. 요청자는 제공된 경우 이 값을 존중해야 합니다(SHOULD).

결과 조회

  1. 태스크 보강 요청을 수락한 수신자는 반드시 CreateTaskResult를 응답으로 반환해야 합니다(MUST).
  2. 종료 상태의 태스크에 대한 tasks/result 요청을 받으면, 수신자는 반드시 기반 요청의 최종 결과를 반환해야 합니다(MUST).
  3. 비종료 상태의 태스크에 대한 tasks/result 요청을 받으면, 수신자는 태스크가 종료 상태에 도달할 때까지 응답을 반드시 차단해야 합니다(MUST).

태스크 취소

  1. 수신자는 이미 종료 상태인 태스크에 대한 취소 요청을 오류 코드 -32602 (Invalid params)로 반드시 거부해야 합니다(MUST).
  2. 유효한 취소 요청을 받으면, 수신자는 태스크 실행 중단을 시도해야 하며(SHOULD) 응답 전에 반드시 태스크를 cancelled 상태로 전환해야 합니다(MUST).

데이터 타입

태스크 상태

태스크는 다음 상태 중 하나에 있을 수 있습니다.

오류 처리

보안 고려사항

태스크 ID는 태스크 상태와 결과에 접근하는 주요 메커니즘입니다. 인증 컨텍스트가 제공된 경우, 수신자는 반드시 태스크를 해당 컨텍스트에 바인딩해야 합니다(MUST). 컨텍스트 바인딩이 불가능한 경우, 수신자는 반드시 추측을 방지할 만큼 충분한 엔트로피를 가진 암호학적으로 안전한 태스크 ID를 생성해야 합니다(MUST).

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

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