教程2026-10-25 · 智涌AI

Claude Code MCP Tasks 上手：长任务回 taskId

ClaudeMCPAgent编程工具
Claude Code MCP Tasks 上手：本机服务器回 task、轮询完成，并在 mcp list 显示 Connected

Claude Code 从 CLI v2.1.304 起把 MCP Tasks 放进公测：MCP 服务器可以用 resultType: "task" 接手构建、导出这类长活，工具调用先回任务 ID，会话继续干别的，页脚出现「1 MCP task」，结果到了再交给模型。今天快讯《Claude Code 公测 MCP Tasks》说过它是什么，这篇在本机（Claude Code 2.1.309）写了一个最小服务器，把握手、tasks/get 轮询和 elicitation 形状跑通，并记下哪些步骤还碰不到云端开关。

站内已有 MCP 入门配置、40 行写 MCP 服务器、Skill 和 MCP 怎么分工、Claude Code hooks 护栏。这篇不重复配 filesystem，只盯 Tasks 这一条新能力线。

前置条件

先分清：Tasks 不是「超时丢后台」

官方 MCP 文档同一页写了两套不堵会话的机制，名字接近，行为差很多：

机制工作在哪一侧退出 CLI 之后怎么触发
自动后台（auto-background）仍是这一次工具调用，只是挪到后台任务视图一般不保留；文档写明不跨退出主对话里工具跑过约 2 分钟；可用环境变量 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 改阈值，设 0 关闭
MCP Tasks（公测）MCP 服务器自己调度的长任务远程 HTTP 服务器上的任务可继续；stdio 本地进程退出通常停服务器对 tools/call 回 resultType: "task"，且会话满足协议版本 / feature flag / 表面条件

远程 MCP task 可以跨退出接着跟；stdio 任务跟进程同生共死——文档建议退出前先在 /tasks 收尾。

公测表面（文档原文）：终端 CLI、Agent SDK、GitHub Actions。VS Code 扩展和桌面端还没有。任务中途可以弹 elicitation 问用户；非交互会话（含 claude -p）遇到提问会直接取消任务，也不会跑你的 Elicitation hook。

MCP task 的进度来自服务器的 tasks/get，页脚会显示类似「1 MCP task」的计数。结果进模型上下文，transcript 里通常只有一句完成提示——文档写结果要去问 Claude。

第 1 步：最小服务器，按文档回 task

Claude Code 文档「MCP tasks for server authors」给出的首包形状如下（字段名以官方为准；缺 taskId / status / 时间戳 / ttlMs 会变成工具错误）：

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

客户端随后反复发 tasks/get。完成时应答里带 resultType: "complete"，并把普通工具结果放进 result.content。只有当请求 _meta["io.modelcontextprotocol/clientCapabilities"].extensions 里出现 io.modelcontextprotocol/tasks 时，才应该回 task——否则 Claude 会报 Unsupported result type 'task' for tools/call。

我们在 /workspace/proj-test/mcp-tasks/ 放了 task_server.py 和驱动脚本 test_handshake.py。两个工具：

终端输出：tools/call 返回 resultType task 与 taskId，tasks/get 轮询至 completed，全程约 2.1 秒
本机握手摘要：带 tasks 扩展时，2 秒模拟构建从 working 到 completed；不带扩展则回落成同步文本结果。

2026-10-25 实测：taskId build-17387a7a，端到端约 2.10 秒，第 8 次 tasks/get 看到 completed，结果文本为 demo build finished after ~2.0s。elicitation 路径：先 input_required 且 inputRequests.confirm 指向 elicitation/create，用 tasks/update 回 action: accept 后继续跑到 completed。

第 2 步：挂进 Claude Code，先拿 Connected

cd /workspace/proj-test/mcp-tasks
python3 -m venv .venv && .venv/bin/pip install mcp==2.3.0   # 可选
claude mcp add --transport stdio --scope project demo-tasks -- \
  .venv/bin/python task_server.py
# 项目级 .mcp.json 需要批准：交互里点允许，或在 ~/.claude.json
# 对应 project 写入 enabledMcpjsonServers: ["demo-tasks"] 并信任工作区
claude mcp list
claude mcp get demo-tasks
终端：claude --version 为 2.1.309；claude mcp list 显示 demo-tasks Connected
Claude Code 2.1.309 对本机 demo-tasks 的健康检查：✔ Connected。

抓到的健康检查 JSON-RPC 顺序是：

  1. 先发 server/discover，_meta 里带着协议 2026-07-28 和 clientInfo claude-code 2.1.309。
  2. 若服务器不懂 discover，再发 initialize，此时 protocolVersion 经常是 2025-11-25。
  3. 然后 notifications/initialized → tools/list。

第一版服务器只回 2026-07-28，claude mcp list 报错：Server's protocol version is not supported: 2026-07-28。改成按客户端声明的已知版本协商之后才 Connected。文档要求真正的 MCP task 连接谈成 2026-07-28。list 显示 Connected，只说明工具能列出来，不代表 Tasks 路径已经打开。

第 3 步：环境变量与你暂时看不到的 UI

2.1.309 二进制里能搜到 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS、CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND 等字符串。常见写法是放进用户 settings 的 env：

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "120000"
  }
}

设为 0：关掉自动后台，交互会话里 Claude 会一直等到 MCP 调用结束。设 CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1：文档说 Claude 会等 task 结果；若自动后台仍开启，短任务可能先按普通后台逻辑挪走，长任务则不挡你。

取消任务：在 /tasks 里选中按 x，或让 Claude 去停。文档强调——发出取消不等于服务器立刻停，可能已经做完一部分。按 Esc 不会停后台 MCP task。

未实测（写明原因）：

常见坑（本机踩到的优先）

完成标准

最后

给 Claude Code 写长耗时 MCP 工具时，先按官方字段表把 task 与 elicitation 做进服务器，用本文握手脚本在无账号环境把形状跑通；登录 Anthropic 后，再进交互会话确认 /tasks 里是否出现真实任务。若要看运行时层如何挂起 Agent，可读同日扩写的 AWS Infinity。

信息来源

相关教程

延伸阅读

更多实用教程 →

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测，也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注；不用微信的话，可以用 RSS 订阅本站。