Claude Code MCP Tasks: 백그라운드 작업과 Elicitation

Claude Code MCP Tasks를 쓰려면 Tasks를 지원하는 MCP 서버를 연결한 뒤 v2.1.304 이상의 터미널 CLI에서 주 대화를 통해 도구를 호출하세요. 서버가 작업을 접수하면 Claude는 다른 일을 계속하고, 작업이 끝날 때 결과를 받습니다. 일반 호출이 2분 뒤 백그라운드로 전환되는 동작은 별도 방식이므로, 서버를 수정하기 전에 적용 조건부터 확인하세요.

2026-10-24 기준으로 Claude Code 문서는 MCP Tasks를 공개 베타로 안내합니다. 이 글은 프로토콜 2026-07-28을 기준으로 어떤 호출이 MCP Task로 처리될 수 있는지 설명합니다.

Tasks와 Elicitation의 역할

Tasks는 빌드, 테스트 실행, 내보내기, 조사처럼 서버가 접수한 뒤 독립적으로 실행 상태를 관리할 수 있는 긴 작업에 사용하세요. Elicitation은 서버가 다음 단계로 진행하기 전에 사용자에게 빠진 정보나 결정을 요청하는 기능입니다.

겉으로 비슷해 보이는 동작도 실제로는 다음 세 가지로 나뉩니다.

방식	동작	서버에 필요한 구현
일반 MCP 호출	Claude가 도구의 결과를 기다립니다.	일반적인 도구 구현.
자동 백그라운드 전환	주 대화에서 시작한 호출이 2분 후에도 실행 중이면 백그라운드로 이동합니다. 결과는 나중에 도착하지만, 세션을 종료하면 해당 백그라운드 호출은 유지되지 않습니다.	Tasks 지원이 필요하지 않습니다.
MCP Task	서버가 작업을 접수하면서 추적에 필요한 작업 핸들을 반환합니다. Claude Code는 이 핸들로 상태를 확인하고 결과를 가져옵니다. 원격 서버의 작업은 CLI를 종료한 뒤에도 계속될 수 있습니다.	Tasks 확장과 지속적인 작업 상태 관리.

Elicitation은 Tasks와 별개의 기능입니다. 보고서 도구는 먼저 어느 환경을 조회할지 물은 다음 내보내기를 Task로 실행할 수 있습니다. 짧게 끝나는 도구도 Task를 만들지 않고 같은 질문을 할 수 있습니다.

Elicitation은 이번 배포 이전부터 있었습니다. Claude Code v2.1.76 릴리스에서 입력 요청 대화상자와 Elicitation, ElicitationResult 훅이 도입됐습니다. 여기서 새롭게 다루는 기능은 서버가 관리하는 Tasks입니다.

내 호출이 MCP Task가 될 수 있는지 확인하기

공식 지원 조건을 모두 충족해야 합니다. CLI를 최신 버전으로 설치하는 것만으로는 아래 표의 첫 번째 조건만 충족합니다.

확인 항목	필요한 조건
Claude Code 버전	`v2.1.304` 이상.
서버 구현	서버가 Tasks 확장을 지원해야 합니다. MCP 연결이 된다는 사실만으로는 Tasks 지원을 확인할 수 없습니다.
전송 방식과 프로토콜	HTTP, stdio 또는 claude.ai 커넥터 서버가 프로토콜 리비전 `2026-07-28`로 연결되어 있어야 합니다.
이전 프로토콜 강제 설정	`MCP_SDK_GENERATION=v1`이나 `MCP_PROTOCOL_NEGOTIATION=legacy`가 연결에 이전 프로토콜을 강제해서는 안 됩니다.
기능 활성화	세션이 기능 플래그를 가져오고, Anthropic이 해당 세션 유형에 Tasks를 활성화해야 합니다.
지원 실행 환경	터미널 CLI, Agent SDK, GitHub Actions. VS Code 확장과 데스크톱 앱은 현재 MCP Tasks를 지원하지 않습니다.
호출 주체	주 대화에서 시작한 호출이어야 합니다. 하위 에이전트가 실행한 호출은 MCP Task가 되지 않습니다.
입력 방식	대화형 세션이거나, 아래 조건을 충족하는 Agent SDK 또는 스트리밍 입력 세션이어야 합니다.

비대화형으로 실행할 경우, Agent SDK 세션이나 --input-format stream-json을 사용하는 claude -p 실행에는 다음 조건도 필요합니다.

CLAUDE_AUTO_BACKGROUND_TASKS=1
CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND가 1로 설정되지 않을 것
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS가 0으로 설정되지 않을 것

입력 스트림을 열어 두세요. 입력이 닫히면 실행 프로세스는 MCP Tasks의 완료를 기다리지 않습니다. 일회성 claude -p "..." 호출에서는 Tasks를 사용할 수 없습니다. GitHub Actions가 지원 실행 환경에 포함돼 있어도 이 입력 방식 조건은 그대로 적용됩니다.

환경 변수 레퍼런스에는 기능 플래그를 가져오지 못하게 하는 설정도 나와 있습니다.

DISABLE_GROWTHBOOK=1 또는 true
DO_NOT_TRACK=1
비어 있지 않은 모든 DISABLE_TELEMETRY 값
비어 있지 않은 모든 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 값

마지막 두 변수는 0이나 false여도 해당 동작을 비활성화합니다. Amazon Bedrock을 비롯한 일반적인 외부 제공자 세션도 기능 플래그를 가져오지 않습니다. 문서에는 호스트가 관리하는 Claude Code 내장 환경에 대한 예외가 설명되어 있습니다.

프로세스를 시작하는 환경과 실제로 적용된 설정을 확인하세요. 일반적인 설정 파일은 ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json이며, 관리형 설정도 함께 봐야 합니다. 각 설정의 적용 범위는 설정 레퍼런스에 설명되어 있습니다.

이전 프로토콜을 강제하는 설정을 제거해도 새 프로토콜을 지원하지 않는 서버가 업그레이드되지는 않습니다. 마찬가지로 게이트웨이의 API 호환성만으로 기능 플래그 조건까지 충족한다고 볼 수 없습니다. 배포 환경에서 Tasks를 막는 설정을 유지해야 한다면 일반 도구 호출을 사용하세요.

대화형 세션에서 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0은 Claude가 기다리도록 만듭니다. CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1도 Tasks를 기다리게 하지만, 이후 일반 자동 백그라운드 전환이 오래 걸리는 호출을 백그라운드로 옮길 수는 있습니다. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1만으로는 MCP Tasks가 포그라운드에 남도록 강제할 수 없습니다.

작업 하나를 실행하고 결과 확인하기

문서나 구현을 통해 Tasks 지원이 확인된 서버에서 인증을 마친 다음, 데이터를 손상시키지 않는 작업 하나로 동작을 확인하세요. Bash에서 설치 버전과 설정된 서버를 확인한 뒤 대화형 CLI를 엽니다.

claude --version
claude mcp list
claude

자체 업데이트가 가능한 설치 방식이고 최소 버전보다 낮다면 claude update를 실행한 뒤 버전을 다시 확인하세요. 이 명령들은 CLI 레퍼런스에 설명되어 있습니다.

Claude Code 안에서 /mcp로 서버 연결을 확인하고 필요한 인증을 완료하세요. 테스트 실행 도구가 연결되어 있다면 다음처럼 요청할 수 있습니다.

주 대화에서 이 저장소의 MCP 도구로 테스트 모음을 실행해 주세요. 테스트가 실행되는 동안 README를 바탕으로 테스트 구성을 설명해 주세요. 작업이 끝나면 결과와 실패한 항목을 알려 주세요.

동작은 두 곳에서 확인합니다.

Claude Code에서: MCP 작업 수를 확인하고 /tasks를 살펴보세요. 일반 백그라운드 호출도 표시되므로 /tasks에 항목이 있다는 사실만으로는 충분하지 않습니다.
서버 추적 기록에서: tools/call이 resultType: "task"를 반환했는지, 이후 tasks/get 요청이 같은 taskId를 참조하는지 확인하세요.

작업이 완료되면 Claude Code가 결과를 받습니다. Claude에게 결과를 보고해 달라고 요청하세요. Claude가 대기 중이라면 결과를 자동으로 받아 후속 처리를 시작할 수도 있습니다. 호출이 계속 일반 호출로 처리된다면 도구를 다시 작성하기 전에 실제 요청의 지원 기능 정보와 적용 조건을 먼저 확인하세요.

서버 작성자: 작업 핸들을 반환하고 최종 결과 전달하기

오래된 실험용 예제를 복사하지 말고 현재 Tasks 확장을 구현하세요. MCP 2026-07-28 변경 사항에서는 tasks/result를 tasks/get 폴링으로 대체하고, tasks/update를 추가했으며, tasks/list를 제거했습니다.

요청이 허용할 때만 Task 반환하기

요청마다 다음 위치에서 클라이언트의 Tasks 지원 여부를 확인하세요.

params._meta["io.modelcontextprotocol/clientCapabilities"].extensions["io.modelcontextprotocol/tasks"]

이 값은 {}입니다. 서버는 server/discover 응답의 capabilities.extensions 아래에 해당 확장 지원을 알립니다. 두 위치 모두 Tasks 확장 개요에 나와 있습니다.

클라이언트가 지원을 선언하면 서버는 해당 작업을 Task로 처리할지 결정합니다. 지원 선언이 없다면 가능한 경우 일반 결과를 반환하세요. 반드시 Tasks가 필요한 작업이라면 확장에 정의된 기능 미지원 오류 -32021을 사용합니다. Tasks를 지원하지 않는 호출자에게 작업 핸들을 반환하면 안 됩니다.

응답하기 전에 작업을 영속 저장해 tasks/get으로 해당 ID를 바로 조회할 수 있게 하세요. 연결이 바뀌어도 같은 ID에 응답할 수 있어야 하며, 후속 요청에서도 인증과 해당 작업에 대한 접근 권한을 확인해야 합니다.

다음 JSON-RPC 응답은 빌드 작업을 접수하는 형식을 보여 줍니다. ID, 타임스탬프, 뒤에 나오는 결과는 설명용 예시이며 실제 실행 기록이 아닙니다.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "task",
    "taskId": "6f17bfa2-4c5e-4d21-b563-2f7e83a902bc",
    "status": "working",
    "createdAt": "2026-10-24T08:00:00Z",
    "lastUpdatedAt": "2026-10-24T08:00:00Z",
    "ttlMs": 3600000,
    "pollIntervalMs": 5000
  }
}

작업 필드는 JSON-RPC의 result 바로 아래에 둡니다. 별도의 task 객체로 감싸지 않으며, 최초 핸들에는 content 배열도 필요하지 않습니다.

필드	요구 사항
`resultType`	최초 작업 응답에서는 `"task"`.
`taskId`	필수. 서버가 생성하며 쉽게 추측할 수 없어야 합니다. Claude Code는 추가로 공백 없는 출력 가능한 ASCII 문자 128자 이내로 제한합니다.
`status`	필수. `working`, `input_required`, `completed`, `failed`, `cancelled` 중 하나.
`createdAt`, `lastUpdatedAt`	필수. ISO 8601 형식의 타임스탬프 문자열.
`ttlMs`	필수. 생성 시점부터 계산한 보존 기간을 정수 밀리초로 지정합니다. 보존 기간 제한이 없으면 `null`입니다. 작업 실행 시간의 예상치가 아닙니다.
`pollIntervalMs`	선택 사항. 폴링 간격을 정수 밀리초로 지정하며 `null`을 보내면 안 됩니다.
`statusMessage`	선택 사항. 진행 상황이나 상태를 설명하는 텍스트.

구조는 공개된 확장 스키마에 정의되어 있습니다. Claude에서 추가로 수행하는 검증은 서버 작성자용 레퍼런스를 확인하세요.

Claude가 Unsupported result type 'task' for tools/call을 표시하면 먼저 들어온 요청에 확장이 포함됐는지 확인하세요. 그런 다음 taskId, status, createdAt, lastUpdatedAt, ttlMs 중 빠진 필드가 없는지 살펴보세요. 지원하지 않는 status 값도 같은 오류를 일으킵니다. 작업 ID 형식이 잘못됐다면 대신 작업 핸들의 형식이 잘못됐다는 오류가 발생합니다.

완료된 도구 결과를 `tasks/get`에 담기

각 폴링 요청에 작업의 현재 상태를 반환하세요. 성공한 tasks/get 응답은 작업의 status가 아직 working이어도 resultType: "complete"를 사용합니다. 완료된 것은 상태 조회 요청이며, 작업 자체가 끝났다는 뜻은 아닙니다.

앞서 든 빌드 예시가 완료됐을 때의 응답은 다음과 같습니다.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "taskId": "6f17bfa2-4c5e-4d21-b563-2f7e83a902bc",
    "status": "completed",
    "createdAt": "2026-10-24T08:00:00Z",
    "lastUpdatedAt": "2026-10-24T08:03:00Z",
    "ttlMs": 3600000,
    "result": {
      "resultType": "complete",
      "content": [
        {
          "type": "text",
          "text": "Build completed successfully."
        }
      ]
    }
  }
}

중첩된 result에는 일반 도구 결과를 담습니다. isError: true로 나타내는 도구 수준 오류도 completed 작업에 포함됩니다. failed는 error에 담기는 JSON-RPC 실행 오류에만 사용합니다.

tasks/cancel도 구현하되, 취소는 서버의 협조가 필요한 요청으로 다루세요. 확장 명세는 취소가 이미 진행 중인 작업을 반드시 멈춘다고 보장하지 않습니다. 현재 Claude Code는 폴링으로 결과를 가져오므로, 결과 전달을 notifications/tasks에 의존해서는 안 됩니다.

도구가 결정할 수 없는 사항은 Elicitation으로 묻기

환경, 대상 위치, 승인 여부가 정해지지 않았다면 그 결정에 의존하는 동작을 수행하기 전에 사용자에게 물으세요. 폼 모드 Elicitation은 구조화된 필드로 입력을 받고, URL 모드는 외부 서비스 로그인처럼 브라우저에서 진행하는 절차를 제공합니다.

Task가 실행되는 중에 질문하려면 tasks/get 응답에 status: "input_required"와 inputRequests 맵을 담습니다. 각 항목은 고유한 키를 사용하며, elicitation/create 같은 요청 method와 해당 params를 포함합니다. Claude Code는 inputResponses에 동일한 키를 사용해 tasks/update로 답변을 보냅니다.

대화형 CLI에서 질문이 /tasks 화면 뒤에 가려져 있다면 해당 화면을 닫으세요. 거절하거나 Esc를 누르는 것도 입력 요청에 대한 응답입니다. 그 뒤 작업을 계속할지는 서버가 결정합니다.

비대화형 세션의 Task가 사용자 입력을 요청하면 Claude Code는 Elicitation 훅이나 Agent SDK의 onElicitation 콜백을 실행하지 않고 서버에 작업 취소를 요청합니다. 무인 실행을 시작하기 전에 필요한 선택을 모두 전달하거나, 대화형 세션을 사용하세요. 이 제한은 MCP Tasks를 통해 요청한 입력에 적용됩니다.

Elicitation을 사람의 승인으로 취급하기 전에 훅도 점검하세요. 훅 레퍼런스는 다음 동작을 설명합니다.

Elicitation은 자동으로 답변하고 대화상자를 표시하지 않게 할 수 있습니다.
ElicitationResult는 사용자의 응답을 바꿀 수 있습니다. 잘못 작성하면 거절을 수락으로 바꿀 수도 있습니다.
Elicitation 훅이 이미 답했다면 ElicitationResult는 실행되지 않습니다.

사용자, 프로젝트, 로컬, 관리형 설정과 플러그인에서 실제로 적용되는 훅을 모두 살펴보세요. 저장소의 설정 파일만 확인하면 자동 응답을 보내는 훅을 놓칠 수 있습니다.

중지·종료·초기화·재개 시 작업은 어떻게 되나요?

원격 Task를 취소하려면 명시적으로 중지 요청을 해야 합니다. CLI를 종료하는 것만으로는 취소되지 않습니다. 문서의 수명 주기 설명은 서버에서의 실행과 Claude Code의 추적을 구분합니다.

동작	결과와 다음 조치
`/tasks`에서 Task를 선택하고 `x`를 누르거나 Claude에게 중지를 요청	Claude Code가 추적을 중단하고 취소를 요청합니다. 서버는 그래도 작업을 끝낼 수 있습니다.
일반적인 대화 중 `Esc`를 누름	백그라운드 Task는 중지되지 않습니다.
원격 Task 실행 중 CLI를 종료	서버 작업은 계속됩니다. 다시 추적하려면 원래 세션을 재개하세요.
stdio Task 실행 중 CLI를 종료	로컬 서버 프로세스가 종료됩니다. 서버가 해당 프로세스와 독립적인 실행을 명시적으로 지원하지 않는 한 작업이 살아남는다고 가정하지 마세요.
Claude Code를 열어 둔 상태에서 `/clear`, `/branch`를 사용하거나 `/resume`으로 세션 전환	현재 대화에 결과가 도착할 수 있습니다. CLI를 종료한 뒤에는 Task를 처음 시작한 세션을 재개하세요.
원래 세션을 대화형으로 재개	서버가 Task 정보를 유지하고 있다면 다시 연결된 뒤 추적이 재개됩니다. 서버 이름과 연결 설정은 변경하지 마세요.
새 세션을 시작하거나 `--fork-session` 사용	새 세션에는 해당 Task의 추적 상태가 이어지지 않습니다.
일회성 `claude -p`로 세션 재개	해당 실행에서는 Task를 추적하지 않습니다. 대화형 재개 또는 조건을 충족하는 스트리밍 입력을 사용하세요.

서버 연결이 끊겼다면 Task를 중지하기 전에 /mcp로 다시 연결하세요. 그렇지 않으면 취소 요청이 서버에 도달하지 않고 Claude Code는 해당 Task의 추적 정보를 잊어버립니다.

claude --resume으로 원래 대화를 선택하세요. 서버의 보존 정책도 중요합니다. 대화를 재개할 수 있더라도 서버가 이미 삭제한 결과까지 복구할 수는 없습니다.

MCP 설정을 점검하는 프롬프트

서버나 설정을 바꾸기 전에 읽기 전용 점검으로 필요한 최소 변경을 찾으세요. 아래 프롬프트는 @Voxyz_ai의 MCP 점검 제안을 바탕으로 현재 응답 형식과 스트리밍 세션의 동작을 확인하는 항목을 추가했습니다.

Goal: Audit my Claude Code MCP setup for Tasks and Elicitation.

Read the current official documentation:
https://code.claude.com/docs/en/mcp
https://code.claude.com/docs/en/env-vars
https://code.claude.com/docs/en/hooks
https://modelcontextprotocol.io/extensions/tasks/overview

Scope: Inspect connected MCP servers, their configuration, effective settings, and any MCP server implementation in this repository. Say explicitly if no server implementation is present. Keep credential values out of the report.

Check:
1. Long-running tools: identify builds, test runs, exports, or research that could benefit from Tasks. For my server code, recommend the smallest change to return a valid task handle, persist it across connections, and deliver the final result through tasks/get. For third-party servers, cite evidence for the deployed version's support; otherwise mark support unknown.
2. Eligibility: check the CLI version, transport, actual protocol revision, per-request Tasks capability, feature-flag fetching, provider, supported surface, main conversation versus subagents, and input mode. Include MCP_SDK_GENERATION, MCP_PROTOCOL_NEGOTIATION, privacy/flag-fetching variables, CLAUDE_AUTO_BACKGROUND_TASKS, CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND, and CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS. Distinguish one-shot claude -p from stream-json input.
3. Elicitation: find tools that guess missing parameters or perform irreversible actions without obtaining the necessary decision. Inspect Elicitation and ElicitationResult hooks for automatic acceptance or changes to a user's refusal, including hooks outside this repository.
4. Lifecycle: check cancellation, remote versus stdio execution, retention, and resume. Identify unattended Tasks that might request user input.

Output: For each finding, name the tool or setting, cite the evidence, describe current behavior, recommend the smallest change, and give one verification step. Mark conditions you cannot observe as unknown.

Do not edit files, change settings, or invoke operational jobs during this audit. Show recommendations first.