MCP 服务器怎样为长任务报告进度而不阻塞请求

MCP 服务器可以在原请求仍执行时发送 notifications/progress，但进度通知不会自动结束请求，也不会自动把耗时计算移出事件循环。要让服务器继续处理其他消息，需要同时做好异步调度或工作执行器隔离；要让原调用尽快返回任务句柄，则应在双方支持时采用任务增强机制。

官方地址：https://modelcontextprotocol.io/

我会先把“长任务不阻塞”拆成两件事：消息还能不能被处理，以及调用方是否仍在等最终结果。两者混在一起，最容易把“有进度条”误认为“已经后台化”。本文按 MCP 2025-11-25 规范说明协议边界，不将设计建议写成实际部署成绩。

先分清等待结果和占住调度线程

假设一个工具负责给文档集合建立索引。服务端几十秒才完成，客户端在此期间需要知道处理到哪里，还可能发出取消。若索引计算直接占住负责收发消息的线程，即使代码里写了发送通知，消息也可能要等计算结束才有机会真正发出去。

我的设计取舍是先保证消息通路能运行，再增加进度报告：网络读写适合用运行时支持的异步接口；CPU 密集计算应交给合适的线程池、进程池或外部工作服务。具体选哪种取决于语言运行时和 SDK，不能只给函数加一个 async 就假定计算已经并行。

普通工具调用的最终响应依然需要等结果。进度只是期间的可选反馈，不是工具结果的分段替代，也不承诺客户端一定把它显示成进度条。

进度属于哪个请求

客户端在请求的 params._meta.progressToken 中提供令牌，服务端才有这个请求对应的进度关联。令牌可为字符串或整数，活动请求间应保持唯一。JSON-RPC 的 id 与 progressToken 用途不同：前者关联最终响应，后者关联通知。

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "index_documents",
    "arguments": {"collection": "handbook"},
    "_meta": {"progressToken": "index-handbook-a"}
  }
}

这是原创协议示例，不是抓包记录。collection 是工具自行定义的参数；progressToken 则由请求元数据提供。服务端报告已处理数量时，可以发出下面这样的通知：

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "index-handbook-a",
    "progress": 24,
    "total": 80,
    "message": "已处理24份文档"
  }
}

这里 progress 与 total 使用同一种计量单位，分别表示处理数量和预计总数。总量不明确时省略 total，不要捏造百分比。每次通知的 progress 必须递增；消息文字改变而数值不变，不应被包装成另一条同进度通知。没有令牌时，不要临时造一个令牌期望客户端识别。

计算不能堵住消息处理

我会给每次操作建立执行上下文，并放入任务注册表，保存原请求 ID、进度令牌、取消句柄和执行状态。这里的任务注册表是服务器内部组件，并不表示已经启用了 MCP Tasks。消息调度通过注册表找到对应工作，工作执行器负责计算并形成结果对象。

工作执行器把报告交给进度队列，通知发送器再按 SDK 允许的方式发送。不要在任意工作线程中直接调用有线程亲和要求的会话对象。单个共享变量也不够：多个工作并行时，必须保证上下文不会交叉复用，把甲请求的进度发给乙请求。

队列应有容量限制和合并策略。高频进度通常只需要保留最新计数，而不是让每个文件都积压一条通知。终态和错误需要单独处理，不能因为合并进度而丢失真正的结果。通知频率是工程取舍，应根据传输能力和客户端体验决定，不能以狂发通知代替有效工作。

正常完成时，服务端返回原工具调用的结果，并注销进度关联、清理临时资源。普通请求完成后继续发送旧令牌通知，会让客户端无法判断它还属于哪个活跃操作。把计数写到 total，也不能代替最终结果响应。

取消要传到底层工作

普通在途请求使用 notifications/cancelled，其中 requestId 指向原请求 ID，而不是 progressToken。我的处理原则是把取消句柄传给工作执行器及可取消的下游调用，停止接收新工作片段，释放资源，并按照 SDK 对取消的约定收尾。

协议建议接收方停止处理并不再为被取消请求发送响应；但取消可能晚到，底层操作也可能已经完成或无法取消。因此不能把收到通知理解为写入已回滚。业务上已产生副作用时，需要独立定义幂等和补偿策略。客户端也要容忍取消与结果到达的竞争，不能让晚到消息把界面从已取消重新改成成功。

什么时候改用 Tasks

如果调用方不能一直等待，或者操作需要独立的可查询生命周期，我更倾向于评估 Tasks。2025-11-25 规范中的 Tasks 是实验性能力，需要先确认双方能力以及具体工具的任务支持声明，不能假定所有 MCP 客户端都能使用。

任务增强调用被接受后，先返回包含 taskId 的创建结果；状态通过 tasks/get 查询，最终工具结果通过 tasks/result 获取。要注意 tasks/result 在任务尚未到终态时仍可能阻塞，所以“立即创建任务”不等于所有相关接口都立即返回。

Tasks 的取消使用 tasks/cancel。原请求提供的 progressToken 可以在任务生命周期中继续关联进度，直到完成、失败或取消等终态才停止；这与普通请求响应结束后停止进度的边界不同。taskId、请求 ID、progressToken 应分别保存，避免混用。

上线后应该看什么

我会将活动操作数、进度队列积压、最后一次进度时间和终态后的残留上下文作为运行信号。这些指标用于发现消息堵塞和资源泄漏，不是本文提供的性能实测。客户端没显示进度时，应先确认是否提供令牌、是否接收通知、是否有展示支持，再排查服务端是否被计算占住。

没有通知并不必然意味着协议错误，因为进度报告是可选的；有通知也不证明后台任务可靠。对仍在请求生命周期内、耗时可控的工作，普通请求加异步执行和进度通常更简单。只有确实需要任务身份和独立生命周期，并确认兼容能力时，我才会增加任务状态存储与恢复机制。

参考：MCP Progress；MCP Cancellation；MCP Tasks。