MCP Tasks 如何实现可取消工具调用：tasks/cancel、cancelled 与客户端收口

一个 MCP 工具调用如果要跑几分钟，客户端通常不能一直占着前台等待。MCP Tasks 可以给这次调用分配 taskId，让客户端轮询状态、读取结果；用户点击“停止”时，也必须走任务自己的取消协议。关键点是：取消请求返回后，客户端要按 cancelled、completed、failed 三种终态分别收口，不能把一次网络响应当成任务已经停止的证明。

可取消的 MCP 工具调用应先确认双方声明了 tasks.cancel 与对应的工具任务能力，再用 tasks/cancel 发送 taskId；客户端最终仍要用 tasks/get 或结果读取确认状态。

先把普通请求取消和任务取消分开

MCP 普通请求可以使用 notifications/cancelled，它表达的是“这次请求的结果已经不再需要”，接收方不一定返回一个新的终态。任务则不同：它有自己的状态机和可轮询的 taskId，取消必须发送 tasks/cancel，不能拿普通取消通知替代。

任务状态至少要区分 working、input_required、completed、failed、cancelled。其中 input_required 不是失败，客户端仍应读取任务结果来获得下一步输入；而 cancelled 才是用户取消后的任务终态。

初始化时核对 tasks.cancel 与工具任务能力

能力协商是第一道门。服务端要在初始化能力中声明 tasks.cancel，并声明哪些请求支持任务增强，例如 tasks.requests.tools.call。客户端不能因为某个工具名称看起来耗时，就擅自给它加上任务参数。

工具列表还会提供更细的 execution.taskSupport。缺省值或 forbidden 表示不能把这个工具作为任务调用；optional 允许客户端在普通调用和任务调用之间选择；required 则要求客户端使用任务方式。两层能力都满足后，才进入下面的任务生命周期。

{
  "capabilities": {
    "tasks": {
      "cancel": {},
      "requests": {"tools": {"call": {}}}
    }
  }
}

{
  "execution": {"taskSupport": "optional"}
}

创建任务后保存 taskId、ttl 与 pollInterval

客户端发起任务增强的工具调用时，可以在参数中请求 task.ttl。服务端返回的任务对象会带上服务端生成的 taskId，以及建议的 pollInterval。这些字段应该原样写入客户端的任务记录，不要自己解析或改写任务 ID。

{
  "task": {"ttl": 60000}
}

{
  "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
  "status": "working",
  "ttl": 30000,
  "pollInterval": 5000
}

轮询间隔可以参考 pollInterval，但不能把它当成“任务一定在这段时间内完成”的承诺。客户端应设置自己的页面超时和重试边界，同时保留服务端的 statusMessage，方便定位失败原因。

点击停止时发送 tasks/cancel

用户点击停止后，客户端发送一个 JSON-RPC 请求，参数只指向当前任务的 taskId：

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

服务端收到有效请求后，应尝试停止任务，并在响应前把任务转为 cancelled。已经是 completed、failed 或 cancelled 的任务不能再次取消，应返回 JSON-RPC 的 -32602 无效参数错误。

处理取消与完成同时到达的竞态

网络延迟会让取消请求和任务完成几乎同时发生。客户端发送取消后，可以先把按钮置为“正在停止”，但不要立即把结果标记成失败。随后调用 tasks/get 或读取任务结果，按照服务端最终返回的 status 更新界面：

如果服务器已经确认任务完成，取消请求可能被拒绝；如果取消已经生效，即使底层工作线程因为竞态继续运行，任务状态也不能再被改回完成。对用户来说，任务状态和底层资源停止是两个需要分别记录的事实。

常见问题

tasks/cancel 能取消普通 MCP 请求吗？

不能。它针对带任务状态的请求；普通请求应使用规范定义的 notifications/cancelled，两者的响应和终态语义不同。

收到 tasks/cancel 响应就能停止轮询吗？

不建议直接停止。客户端仍应确认任务状态，至少记录最后一次 tasks/get 结果，避免把传输层响应误当成业务终态。

已经 completed 的任务还能取消吗？

按 2025-11-25 Tasks 规范，终态任务再次取消应被视为无效参数，服务端返回 -32602。

任务取消后结果会一直保留吗？

不会有固定保证。任务有 ttl，服务端也可以在取消后删除任务；客户端要在取消前读取仍需要的结果和审计信息。

把任务取消验收写进客户端

实现完成后，至少测试四条路径：能力未声明时拒绝创建任务；working 任务取消后进入 cancelled；任务已完成时取消返回 -32602；取消请求和完成响应同时到达时，页面以最终状态为准。这样既能保护服务端资源，也能避免 UI 出现“显示已停止但结果又覆盖回来”的矛盾状态。