1. 长任务跑起来像卡死MCP Tool 进度通知到底缺在哪如果你在用 Cline、CC Switch 这类 AI 编码工具大概率遇到过这种场景让 Agent 调一个 MCP Tool 去跑批量任务比如扫描 200 个文件、拉取一批接口数据、做一次多步代码重构。工具确实在跑但界面上什么都没有光标转啊转你完全不知道它跑到第几步、还要多久、是不是已经挂了。这就是 MCP Tool 长任务执行时进度通知缺失的典型痛点。MCP 本身是支持进度通知的走的是 JSON-RPC 的notifications/progress方法关键在于调用方要在tools/call的_meta.progressToken里带一个令牌服务端每完成一步就回推一条通知。问题在于很多开发者把 MCP Server 接进来之后只配了模型通道没把这条通知链路和统一的 API 通道打通结果就是工具在后台默默跑前端毫无反馈。这篇就围绕这个场景给你一套能直接复制的配置骨架用 TaoToken 统一 Key 管住模型和工具调用通道用config.toml和settings.json把 MCP Server 挂进 Cline / CC Switch再演示一次带progressToken的进度回调验证。目标很明确10 分钟内让你跑通一条带进度反馈的 MCP Tool 调用链。适合已经在用 AI 编码工具、想让长任务可见的开发者。2. 前置准备TaoToken 统一 Key 与 API 通道在动配置之前先把通道这件事理清楚。MCP Tool 的调用链里有两个东西需要出网一个是模型推理请求一个是 MCP Server 自身的工具执行。如果每个都单独配 Key、单独配地址配置会散得到处都是排查起来很痛苦。TaoToken 的思路是给你一个统一 Key 和一个统一 API 入口模型对话、Coding Plan、工具调用都走同一个通道配置集中管理。你需要先拿到 Key。打开控制台在 API Keys 页面创建一个新 Key复制出来备用。这个 Key 后面会同时出现在config.toml和settings.json里所以别弄丢。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI 基础地址统一用https://taotoken.net/api注意这个地址后面不加任何查询参数直接作为 base_url 填进配置。如果你后面要验证模型通道是否通可以用模型对话页面先发一条测试消息确认 Key 有效再往下走模型对话https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite这里有个容易踩的坑有人把 Key 填进了 MCP Server 的启动参数里却没填进 AI 工具的模型配置里结果工具能调起来但模型请求 401。统一 Key 的意义就是两边用同一个减少这种错配。3. 可复制配置config.toml 与 settings.json 骨架下面给的是骨架不是完整业务配置你按自己的 MCP Server 路径和工具名替换占位符即可。先看config.toml这个文件通常放在你的 MCP Server 项目根目录用来声明服务端行为和通道参数。# config.toml - MCP Server 通道与进度通知骨架 [server] name long-running-tool-server version 0.1.0 transport stdio # 本地开发用 stdio远程可换 sse [api] base_url https://taotoken.net/api api_key sk-你的TaoToken统一Key timeout_seconds 120 # 长任务给足超时别用默认 30 [progress] enabled true method notifications/progress # 进度令牌由调用方在 _meta.progressToken 传入服务端原样回传 echo_token true interval_hint_ms 2000 # 建议前端刷新节奏非强制 [tools.longRunningOperation] description 演示带进度通知的长任务 default_duration 10 default_steps 5再看settings.json这是 Cline / CC Switch 这类工具读取的 MCP Server 注册文件。不同工具路径略有差异Cline 一般在扩展设置里能直接编辑CC Switch 走的是它自己的配置目录。核心结构是一样的在mcpServers下声明一个服务把启动命令和通道参数写进去。{ mcpServers: { long-running-tool: { command: dotnet, args: [ run, --project, /path/to/YourMcpServer/YourMcpServer.csproj ], env: { TAOTOKEN_API_BASE: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的TaoToken统一Key, MCP_PROGRESS_ENABLED: true }, disabled: false, autoApprove: [] } } }两个文件的分工要清楚config.toml管服务端自己怎么跑、进度通知开不开settings.json管 AI 工具怎么把服务端拉起来、环境变量怎么注入。Key 在两处都出现是刻意的服务端读环境变量工具侧读配置统一来源避免漂移。注意autoApprove留空是有意的。长任务工具如果自动批准Agent 可能在你不注意时连续触发进度通知反而被淹没。先手动确认跑通后再按需放开。4. 验证请求一次带 progressToken 的进度回调配置写完先别急着在 AI 工具里点。用最原始的方式验证一次确认服务端真的会推notifications/progress。MCP 走 JSON-RPC先发initialize拿 SessionId这个 Id 在响应的 Header 里不在 body 里很多人第一次找半天。# 第一步初始化拿 Mcp-Session-Id curl -i -X POST https://taotoken.net/api/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken统一Key \ -d {id:1,jsonrpc:2.0,method:initialize}响应头里会有Mcp-Session-Id: xxxxx记下来。第二步发tools/call关键是_meta.progressToken必须带上服务端才知道往哪条流回推。# 第二步调用长任务工具带 progressToken curl -N -X POST https://taotoken.net/api/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken统一Key \ -H Mcp-Session-Id: 上一步拿到的SessionId \ -d { id: 5, jsonrpc: 2.0, method: tools/call, params: { name: longRunningOperation, arguments: { duration: 10, steps: 5 }, _meta: { progressToken: 5 } } }-N是关掉 curl 缓冲这样 SSE 流会实时打出来。你会看到类似这样的输出每两秒一条progress从 1 递增到 6最后一条是最终结果event: message data: {method:notifications/progress,params:{progress:1,total:5,progressToken:5},jsonrpc:2.0} event: message data: {method:notifications/progress,params:{progress:2,total:5,progressToken:5},jsonrpc:2.0} ... event: message data: {result:{content:[{type:text,text:Long running operation completed.}]},id:5,jsonrpc:2.0}看到progress递增、progressToken和你传进去的一致就说明进度通知链路通了。服务端侧的实现逻辑是从context.Params.ProgressToken取出令牌每完成一步就SendNotificationAsync(notifications/progress, ...)把令牌原样带回。C# 里用ModelContextProtocol类库的话核心就是那个progressToken is not null判断别漏。5. 本篇常见错排查跑不通的时候按下面几条对号入座基本能覆盖九成问题。进度通知一条都不来。先查_meta.progressToken有没有传。很多人只传了arguments忘了_meta服务端拿不到令牌就直接跳过通知逻辑任务照跑但静默。再查config.toml里progress.enabled是不是true。SessionId 拿不到或报 401。检查Authorization头格式是Bearer sk-xxx别漏了Bearer和空格。Key 如果是从控制台复制的注意别把首尾空格带进去。统一 Key 在模型通道和工具通道都要有效如果模型对话页面能发消息、这里却 401多半是 Header 写错了。curl 卡住不输出。少了-NSSE 流被缓冲了看起来像卡死。加上-N再看。另外timeout_seconds如果配得太短长任务还没跑完连接就断了进度自然收不全。AI 工具里看不到进度。先确认settings.json的command和args路径对服务端根本没起来的话工具会报连接失败而不是没进度。再看工具版本是否支持渲染notifications/progress部分老版本只认最终结果。Cline 和 CC Switch 较新版本都支持升级一下。进度数字跳变或重复。检查服务端循环边界for (int i 1; i steps 1; i)这种写法会多推一条属于正常收尾但如果你前端按total算百分比最后一条会超过 100%做个Math.min兜一下。提示排查时把interval_hint_ms调大一点比如 5000让每条通知间隔明显肉眼更容易确认链路是通的跑通后再调回正常值。6. 把通道固定下来长任务才可控进度通知这件事本质是把「黑盒长任务」变成「可见的流」。你这次配好的config.toml和settings.json骨架可以直接复用到其他 MCP Tool 上只要服务端按同样的progressToken约定回推就行。统一 Key 的价值也在这里体现模型通道和工具通道共用一个入口换工具、加工具都不用重新折腾鉴权。如果你后面要长期跑编码类 Agent 任务建议把通道固定到 Coding Plan省得每次手动配Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteClaude Code 这类工具的接入方式在文档里有单独说明配置结构和上面这套骨架是通的Claude Code 接入https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-codeutm_campaignrewrite最后留个实操建议把progressToken用业务 ID 而不是固定字符串比如用任务 ID 或文件哈希。这样多个长任务并发时前端能按令牌区分是哪条任务在推进不会串台。这个细节在单任务演示里看不出来一旦 Agent 同时触发多个工具就是它救你的时候。