Claude Code MCP Tasks 사용법은? 긴 작업은 백그라운드 실행, Elicitations로 중간 확인, 2.1.304부터 지원 (서드파티 API Key 실측)

@ClaudeDevs가 10월 24일 게시한메인 게시글에 따르면 Claude Code가 MCP Tasks를 지원하기 시작했습니다. MCP 서버가 오래 걸리는 도구 호출을 '작업'으로 바꿔 서버에서 직접 실행하고, Claude는 작업 ID를 받은 뒤 다른 일을 계속합니다.후속 게시글은 Elicitations를 소개합니다. 작업이 중간쯤 실행되다가 팝업으로 입력을 요청하는 기능입니다. 또 다른후속 게시글은 CLI에서 이미 사용할 수 있다고 안내합니다.

먼저 결론부터 말씀드립니다.

• MCP Tasks는 현재 공개 베타이며, 공식 원문은 MCP tasks are in public beta in the Claude Code CLI and require Claude Code v2.1.304 or later 입니다.
• 서버가 tasks를 지원하고, 2026-07-28 프로토콜로 연결되며, 세션이 feature flags를 가져올 수 있고, 호출이 메인 대화에서 나오는 등의 조건을 모두 충족해야 MCP task가 됩니다.
• 저희 사이트의 API Key로 Claude Code v2.1.309에서 실측한 결과, 프로토콜은 2026-07-28로 협상되었고, 2분을 넘는 MCP 호출은 자동으로 백그라운드로 전환되어 /tasks에서 진행 상황을 볼 수 있었으며, Elicitation 중간 확인 팝업도 정상 동작했습니다. 다만 서버 측 MCP task는 활성화되지 않았습니다. 원인은 feature flags와 관련이 있으며 아래에서 자세히 설명합니다.
• 저희의 이전 튜토리얼에서는 DISABLE_TELEMETRY나 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC를 설정하라고 안내하지 않았습니다. 실측해 보니 설정 여부와 관계없이 위 동작은 동일했습니다.

API Key 만들기 →

어떤 문제를 해결하나요

예전에는 MCP 도구 호출 하나가 오래 걸리면(예: 리포트 내보내기, 빌드 실행) Claude가 멈춘 채 기다릴 수밖에 없었습니다. 공식 문서는 MCP task를 이렇게 정의합니다.

An MCP task is a long job, such as a report export or a build, that an MCP server runs itself using the MCP tasks extension. Claude's tool call returns once the server accepts the job, so Claude keeps working unless you make Claude wait.

즉, 서버가 작업을 받는 순간 도구 호출이 반환되어 Claude는 하던 일을 계속합니다. 작업이 끝나면 대화에 안내 한 줄이 나타나고 Claude가 결과를 받습니다. 하단 상태 표시줄에는 1 MCP task 같은 카운트가 표시됩니다. 원격 서버의 작업은 Claude Code를 종료한 뒤에도 계속 실행되며, 나중에 같은 세션을 복구하면 이어서 따라갈 수 있습니다.

Elicitations는 또 다른 문제를 해결합니다. 작업이 중간쯤 실행되다가 「지금 staging에 배포할까요」처럼 사용자의 결정이 필요할 때, 서버가 실패하거나 추측하는 대신 양식을 띄워 물어볼 수 있습니다.

「2분 초과 시 자동 백그라운드 전환」과는 다릅니다

이 부분이 가장 헷갈립니다. Claude Code에는 더 오래된 메커니즘이 하나 있습니다. 메인 대화에서 일반 MCP 호출이 2분을 넘기면 자동으로 백그라운드로 옮겨져 세션을 막지 않습니다. 문서 원문은 다음과 같습니다.

An MCP tool call in the main conversation that is still running after two minutes moves to a background task instead of blocking the session.

두 방식의 차이는 다음과 같습니다.

문서는 판별 방법도 제시합니다. /tasks에서 백그라운드 호출의 상세 화면에 runs on the server; survives exiting this session라고 표시되는 경우에만 서버 측 MCP task입니다.

버전과 전제 조건

공식 문서의 「What a call needs to become an MCP task」 절에 모든 조건이 나와 있습니다. 도구 호출이 다음을 동시에 충족해야 MCP task가 됩니다.

• 서버가 tasks를 지원합니다.
• 서버가 HTTP, stdio 또는 claude.ai connector이고 2026-07-28 프로토콜로 연결되어 있어야 합니다. 원문: Setting MCP_SDK_GENERATION=v1 or MCP_PROTOCOL_NEGOTIATION=legacy rules that out.
• 세션이 feature flags를 가져와야 합니다. 원문: so not on a third-party provider such as Amazon Bedrock, and not with telemetry or flag fetching turned off.
• Anthropic이 해당 세션에 MCP tasks를 활성화해 두었어야 합니다. v2.1.304부터 터미널 CLI, Agent SDK, GitHub Actions를 지원하며, 원문은 Other surfaces, such as the VS Code extension and the desktop app, don't have MCP tasks 입니다.
• 호출이 서브 에이전트가 아니라 메인 대화에서 나와야 합니다.
• 세션이 인터랙티브이거나, 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이 아니어야 합니다.

마지막 조건에 유의하세요. 일반적인 일회성 claude -p "..." 에서는 MCP task를 받지 못합니다. 원문은 A one-shot claude -p "" run doesn't get MCP tasks.

먼저 버전을 확인합니다:

claude --version
# 低于 2.1.304 就先升级
claude update

활성화 및 사용 단계

1. tasks를 지원하는 MCP 서버 연결하기

추가 방법은 일반 MCP 서버와 같고, 별도로 켜야 하는 스위치는 없습니다:

# 远程 HTTP 服务器
claude mcp add --transport http my-server https://mcp.example.com/mcp
# 本地 stdio 服务器
claude mcp add --transport stdio my-server -- python3 /path/to/server.py

서버 쪽에서 MCP tasks 확장을 구현해야 합니다. 문서에는 2026-07-28 연결에서 Claude Code가 보내는 모든 요청의 params._meta["io.modelcontextprotocol/clientCapabilities"] 안에 extensions 아래의 "io.modelcontextprotocol/tasks": {}를 담아 보낸다고 되어 있습니다. 작업으로 바꿀 수 없는 tools/call 에는 이 확장이 없습니다. 서버는 이 확장이 보일 때만 "resultType": "task" 로 응답할 수 있습니다. 확장이 보이지 않는데도 task를 반환하면 Claude는 Unsupported result type 'task' for tools/call를 받습니다.

MCP를 아직 연결해 본 적이 없다면 Codex 쪽의MCP 설정 튜토리얼을 먼저 보고 서버를 추가, 삭제, 조회하는 방법을 익히거나Claude Code로 Unreal Engine 제어하기와 같은 완전한 MCP 연동 사례를 살펴보시기 바랍니다.

2. /tasks로 진행 상황 보기, x로 중지하기

작업이 실행되면 /tasks 를 입력해 목록을 엽니다. 중지 방법의 원문은 다음과 같습니다:

To stop a running task, select it in /tasks and press x, or ask Claude to.

몇 가지 세부 사항입니다:

• 키보드에서 Esc 를 눌러도 백그라운드 작업은 중지되지 않습니다.
• 중지하면 Claude Code가 서버에 취소를 요청하지만, 서버는 작업을 끝까지 실행할 수도 있습니다.
• 서버 연결이 끊어졌다면 먼저 /mcp 에서 다시 연결해야 합니다. 그렇지 않으면 취소 요청을 보낼 수 없고, Claude Code도 더 이상 해당 작업을 추적하지 않습니다.

작업이 끝나면 대화에 다음과 같은 한 줄이 나타납니다:

MCP task <server task id> (<server>/<tool>) completed.

결과는 대화에 바로 출력되지 않고 Claude에게 전달됩니다. 확인하려면 Claude에게 물어보면 됩니다. Claude가 유휴 상태일 때 결과를 받으면 알아서 이어서 처리합니다.

3. 종료한 뒤 claude --resume으로 결과 가져오기

원격 서버의 작업은 종료 후에도 계속 실행됩니다. 돌아와서 해당 작업이 있던 세션을 복원합니다:

claude --resume

서버 이름과 연결 설정이 바뀌지 않아야 합니다. 새 세션을 열거나 --fork-session 를 쓰면 모두 기존 작업을 따라가지 않습니다. 일회성 claude -p 안의 --resume 도 따라가지 않습니다. 또한 stdio 서버의 프로세스는 Claude Code가 종료되면 함께 중지됩니다. /tasks에는 survives exiting this session이라고 똑같이 표시되지만, 서버 문서에 작업이 프로세스보다 오래 살아남는다고 명시되어 있지 않다면 작업을 먼저 끝내거나 중지한 뒤 종료하라고 문서는 권장합니다.

4. Claude가 결과를 기다린 뒤 이어가게 하려면

기본적으로 Claude는 기다리지 않습니다. 기다리게 하려면 settings.json 의 env 에서 둘 중 하나를 설정합니다:

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 를 0로 설정하면 Claude가 모든 MCP 호출이 끝날 때까지 기다리며, 일반 호출의 2분 자동 백그라운드 전환도 함께 꺼집니다.
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND 를 1로 설정하면 Claude는 작업 결과를 기다리지만 일반 호출의 자동 백그라운드 전환은 그대로 남아 있습니다. 그래서 2분을 넘는 호출은 여전히 백그라운드로 넘어가는데, 이때 넘어가는 것은 MCP task가 아니라 일반 백그라운드 호출이므로 종료하면 사라집니다.

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

단독으로 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 를 설정하거나 bare 모드를 사용해도 Claude가 MCP task를 기다리게 되지는 않습니다.

5. Elicitation: 작업 중간에 확인 요청

작업이 실행되는 중에 elicitation 대화상자가 나타날 수 있습니다. 두 가지에 유의하시기 바랍니다:

• /tasks 이 켜져 있으면 대화상자가 숨겨지므로 먼저 /tasks 를 닫아야 응답할 수 있습니다.
• Decline을 선택하거나 Esc를 눌러도 하나의 응답으로 처리되며, 작업을 계속할지는 서버가 스스로 결정합니다.

비대화형 세션에서는 작업이 입력을 요구하는 즉시 취소됩니다. 원문: In a non-interactive session, Claude Code asks the server to cancel a task that requests input, without running your Elicitation hooks or calling the Agent SDK's onElicitation callback.

서드파티 API에서 유의할 점

저희는Claude Code 서드파티 API 설정 튜토리얼의 방식대로 전역 ~/.claude/settings.json 에 본 사이트 Key를 설정했습니다(ANTHROPIC_BASE_URL 에는 /v1가 붙지 않습니다):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
    "ANTHROPIC_AUTH_TOKEN": "你的 API Key"
  }
}

그런 다음 Claude Code v2.1.309로 직접 작성한 최소 stdio MCP 서버를 연결했습니다. 이 서버는 tasks 확장을 구현했고 도구 두 개를 제공합니다. 하나는 느린 빌드, 다른 하나는 중간에 확인이 필요한 배포입니다. 아래는 실측 결과입니다.

실측 1: 프로토콜과 MCP task

• 연결은 정상이며 디버그 로그에 negotiatedProtocolVersion":"2026-07-28"가 기록되어 있으므로 새 프로토콜을 사용한다는 뜻입니다.
• 디버그 로그에는 mcp runtime arm: v2 (source: default)도 함께 기록됩니다. 문서에 따르면 feature flags를 가져오지 않은 세션은 기본적으로 v2 런타임으로 실행되며, 이 줄의 source는 flags가 아니라 default입니다.
• 서버가 받은 tools/call 안에서clientCapabilities 에는 roots와 elicitation만 있고 io.modelcontextprotocol/tasks는 없습니다. 따라서 서버는 task를 반환할 수 없고, 호출은 일반 MCP 호출로 실행됩니다.

결론: 본 사이트 Key를 사용할 때는 이번 테스트에서 서버 측 MCP task가 활성화되지 않았습니다. 이는 문서의 ‘세션이 feature flags를 가져올 수 있어야 한다’는 조건과 일치합니다. 공식 게시글과 문서에는 아직 공개 베타라고 되어 있으며, 이후 제공 범위가 바뀌면 이 글을 업데이트하겠습니다.

실측 2: 일반 장시간 호출의 자동 백그라운드 전환, /tasks

느린 빌드 도구를 150초 동안 실행했습니다:

• 약 2분이 되었을 때 호출이 백그라운드로 넘어갔고, Claude는 작업이 백그라운드로 전환되었다고 답했으며 하단에 다음이 표시됩니다: 1 MCP task.
• 실행 중에 /tasks 를 열면 진행 상황과 서버가 보고한 진행 메시지를 볼 수 있고, 하단에 다음 안내가 표시됩니다: Esc to go back · x to stop.
• 150초가 되자 완료 알림이 나타났고, Claude가 곧바로 결과를 알려 주었습니다.

claude-code-mcp-tasks-tasks

claude-code-mcp-tasks-done

참고: 이것은 일반 호출의 자동 백그라운드 전환입니다. /tasks에는 MCP task로 표시되지만 상세 화면에 runs on the server 문구가 없고, 세션을 종료하면 사라집니다. 장시간 작업은 종료 전에 끝내거나 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 로 임계값을 조정하시기 바랍니다.

실측 3: Elicitation으로 중간 확인

배포 도구를 호출하자 서버가 2026-07-28 프로토콜에서 입력이 필요하다는 결과를 반환했고, Claude Code가 폼을 띄웠습니다:

claude-code-mcp-tasks-elicitation

확인란을 체크하고 Accept를 선택하자 서버가 confirm: true를 받았고 도구가 결과를 반환했습니다. 질문부터 결과까지 약 7초가 걸렸습니다. 즉 일반 MCP 호출의 중간 확인은 서드파티 Key에서도 사용할 수 있습니다.

텔레메트리 변수 선택

일부 독자는 요청을 줄이려고 아래 두 변수 중 하나를 설정합니다:

export DISABLE_TELEMETRY=1
# 或
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

저희는 두 변수를 각각 설정하고 다시 실행했습니다. 런타임은 똑같이 v2 (source: default)로 나타났고, 서버는 마찬가지로 tasks 확장을 받지 못했으며, Elicitation 팝업은 평소처럼 사용할 수 있었습니다. 따라서 서드파티 Key 사용자에게는 이 두 변수의 설정 여부가 MCP 동작에 차이를 만들지 않습니다.

권장 사항:

• 공식 계정을 쓰면서 서버 측 MCP task를 원하는 경우: 문서에 따라 텔레메트리나 flag 가져오기를 끄지 마십시오.
• 서드파티 API Key를 쓰는 경우: 이 두 변수는 이 글에서 확인한 기능에 영향을 주지 않으므로 개인정보 보호와 네트워크 요구에 맞게 결정하시면 됩니다. 저희 Claude Code 튜토리얼에서도 원래 이 변수들을 설정하라고 하지 않습니다.
• ‘호환’을 위해 MCP_SDK_GENERATION=v1 또는 MCP_PROTOCOL_NEGOTIATION=legacy를 설정하지 마십시오. 그러면 MCP task가 곧바로 배제됩니다.

작업 문제가 아니라 응답이 느리거나 끊기는 문제라면Claude Code 응답 지연 점검을 참고하시기 바랍니다.

자주 보는 상태와 오류

아래 메시지는 /tasks 항목이나 작업 종료 줄에 나타나며, 의미는 공식 문서의 상태 표를 따랐습니다. 메시지가 표시되는 동안에도 작업은 계속 실행 중일 수 있고, Claude Code는 계속 상태를 조회합니다.

서버 작성자가 자주 겪는 두 가지 도구 오류입니다. 문서 원문은 다음과 같습니다.

• 클라이언트가 tasks 확장을 보내지 않았는데 task를 반환한 경우:Unsupported result type 'task' for tools/call.
• 작업 ID가 규칙에 맞지 않는 경우(출력 가능한 ASCII 문자 최대 128자, 공백 불가): 오류 메시지가 MCP server 로 시작하며, 다음 내용을 포함합니다: returned a malformed task handle for tool.

자주 묻는 질문

Claude Code MCP Tasks에는 어떤 버전이 필요합니까?

v2.1.304 이상이 필요하며, 현재 CLI에서 베타로 제공됩니다. Agent SDK와 GitHub Actions도 지원하며, VS Code 확장과 데스크톱 앱은 아직 지원하지 않습니다.

서드파티 API Key로도 MCP Tasks를 쓸 수 있습니까?

저희가 이 사이트의 Key로 v2.1.309에서 테스트했을 때는 서버 측 MCP task가 활성화되지 않았고, 클라이언트도 서버에 tasks 확장을 알리지 않았습니다. 2분을 넘으면 자동으로 백그라운드로 전환되는 기능, /tasks로 확인하고 중지하는 기능, Elicitation 중간 확인은 모두 정상적으로 동작했습니다.

DISABLE_TELEMETRY를 설정해도 쓸 수 있습니까?

문서에 따르면 텔레메트리를 끄거나 flag를 가져오지 않은 세션에서는 MCP task가 생성되지 않습니다. 서드파티 Key 환경에서 직접 테스트해 보니 설정 여부와 관계없이 동작이 같았고, Elicitation은 계속 사용할 수 있었습니다.

서브 에이전트나 claude -p에서도 작업으로 전환됩니까?

서브 에이전트가 시작한 호출은 작업으로 전환되지 않습니다. 일회성 claude -p "" 도 마찬가지입니다. Agent SDK 또는 --input-format stream-json 를 읽는 claude -p 는 CLAUDE_AUTO_BACKGROUND_TASKS=1 등의 조건을 만족할 때만 가능하며, 입력을 닫지 않고 유지해야 합니다.

Claude Code를 종료해도 작업이 남아 있습니까?

원격 서버의 MCP task는 그대로 남아 있습니다. claude --resume 로 같은 세션을 복원해 결과를 가져오면 되며, 서버 이름과 연결 설정은 바꿀 수 없습니다. 일반 호출의 자동 백그라운드 작업은 종료와 함께 사라집니다. stdio 서버의 프로세스는 종료 시 함께 중지됩니다.

Claude가 작업 결과를 기다렸다가 이어가게 하려면 어떻게 합니까?

다음 값을 설정합니다. CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0(모든 MCP 호출 대기) 또는 CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1(작업 결과 대기, 단 2분을 넘는 호출은 여전히 일반 백그라운드 호출로 전환됩니다).

Elicitation 팝업이 나타나지 않으면 어떻게 합니까?

먼저 /tasks가 켜져 있지 않은지 확인하십시오. 켜져 있으면 대화상자가 숨겨집니다. 비대화형 세션에서는 작업이 입력을 요구하면 바로 취소됩니다.

API Key 만들기 →