1. 为什么我要给 WorkBuddy 接一个自定义 MCP 连接器WorkBuddy 这类 AI 工作台用久了你会发现一个很现实的问题它自带的技能再全也覆盖不了你手头那些“偏门但高频”的需求。比如我最近做内容配图每次都要切到浏览器、打开生图页面、复制提示词、下载图片、再拖回项目目录一套动作下来三五分钟没了。如果一天要出十几张图这个时间成本非常吓人。MCPModel Context Protocol就是来解决这类问题的。你可以把它理解成 AI 工作台和外部工具之间的“标准插座”——只要对方提供了符合 MCP 协议的服务端WorkBuddy 就能通过一个统一的连接器去调用它不用为每个工具单独写适配代码。这次我选的目标是「腾讯混元生图」的 SSE 云托管服务原因很简单它是标准的 SSE 传输方式不需要我在本地跑任何进程配置一个 URL 就能用对新手最友好。这篇文章适合三类人看一是刚接触 WorkBuddy、想搞明白 MCP 到底怎么接的新手二是接过一两个 MCP 但总在 SSE 连接上翻车的朋友三是想把手头零散工具统一收进 WorkBuddy 工作流的效率党。我会从 mcp.json 的字段含义讲起把 SSE 连接的坑一个个拆开最后给你一份可以直接抄的配置。全程不涉及任何本地部署的复杂操作跟着做就行。2. 先把 MCP 和 SSE 这两个概念捋清楚2.1 MCP 到底是个什么东西很多人第一次听到 MCP 会懵因为它既像软件协议又像硬件概念。说白了MCP 是一套软件层的通信协议全称 Model Context Protocol核心作用是让 AI 应用客户端和外部能力服务端之间用统一格式对话。你可以类比成 USB 接口以前每个设备一个专用口现在统一成 USB插上就能用。MCP 就是 AI 工具界的 USB。它规定了三件事客户端怎么发现服务端有哪些能力tools/resources/prompts、调用时参数怎么传、返回结果怎么解析。WorkBuddy 作为客户端只要读到一份描述服务端能力的配置就能把这些能力变成自己可调用的“技能”。这也是为什么热词里总出现workbuddy skill、agent mcp这类词——MCP 接进来之后本质上就是给 WorkBuddy 扩了一组技能。2.2 SSE 传输方式和它的脾气MCP 服务端和客户端之间要传数据传输方式主要有几种SSEServer-Sent Events是其中一种基于 HTTP 的单向流式传输。它的特点是客户端发一个 HTTP 请求服务端保持连接不关闭持续往客户端推消息。对 AI 场景来说这很合适因为工具调用往往是“我发一个请求你分多次把结果流回来”。但 SSE 有个出了名的脾气热词里那句stream disconnected before completion: idle timeout waiting for sse就是它的典型症状——连接空闲一段时间就被掐断。云托管服务通常会在网关层设置空闲超时如果你的客户端没有及时处理心跳或者重连连接就断了任务做到一半失败。所以接 SSE 类 MCP超时和重连策略比配置本身更重要这一点后面我会专门讲。2.3 为什么选腾讯混元生图的 SSE 云托管选它有三个理由。第一它是云托管服务端在对方那边我本地不用装任何东西配置里填个 URL 就行这对不熟悉命令行的朋友极其友好。第二它走标准 SSE正好是 WorkBuddy 支持得比较成熟的传输方式。第三生图这个能力本身高频且结果直观接完立刻能用不像某些抽象工具接完还要研究半天怎么调。需要说明的是云托管服务通常需要鉴权也就是配置里那个 URL 往往带 token 或者需要额外的 header。这部分我会在配置章节里讲清楚字段怎么填但具体的 token 你得从服务提供方那里拿我不在这里贴任何真实凭证。3. 动手前的准备工作与 mcp.json 字段全解3.1 你需要提前拿到的东西在打开配置文件之前先把这几样东西备齐不然配到一半发现缺东西会很抓狂WorkBuddy 客户端确认版本支持自定义 MCP 连接器。老版本可能只有内置技能没有手动添加入口建议先更新到较新版本。混元生图 SSE 服务的接入地址通常是一个https://开头的 URL可能带查询参数形式的 token。鉴权信息如果服务方要求 header 里带 key提前记下来注意别泄露。一个干净的测试目录用来验证生图结果能不能正常落盘别直接在生产项目里试。提示token 这类凭证不要写进会公开分享的配置文件里。如果你要把配置发到社区求助记得先把 token 部分打码。3.2 mcp.json 的结构长什么样WorkBuddy 的自定义 MCP 配置一般放在一个叫mcp.json的文件里结构是固定的顶层一个mcpServers对象里面每个键就是一个连接器的名字值是这个连接器的配置。下面是一个通用骨架字段含义我逐个标注{ mcpServers: { hunyuan-image: { type: sse, url: https://your-endpoint.example.com/sse?tokenYOUR_TOKEN, headers: { Authorization: Bearer YOUR_KEY }, timeout: 60000, enabled: true } } }各字段的作用和常见取值我整理成一张表方便你对照字段是否必填作用常见取值/注意点type必填指定传输方式SSE 场景固定填sse别填成stdiourl必填服务端接入地址必须是完整 URL带 token 的别漏参数headers视服务而定附加请求头鉴权 key 放这里注意大小写timeout建议填单次请求超时毫秒生图较慢建议 60000 起enabled可选是否启用调试时可临时置 false3.3 字段填错会怎样三个高频翻车点第一个坑是type写错。有人看到 URL 是 https 就以为要填http结果客户端按普通请求处理根本建立不了流式连接表现就是“连接成功但没有任何工具出现”。记住SSE 就是sse。第二个坑是 URL 里的 token 被截断。有些 token 很长复制的时候容易漏掉尾部字符或者被编辑器自动换行。建议粘贴后从头到尾核对一遍长度或者用引号完整包住。第三个坑是headers的键名大小写。部分服务端对Authorization这种头是大小写敏感的写成authorization可能直接被拒。拿不准就按服务方文档原样抄。4. 手把手配置从新建文件到连接成功4.1 找到 WorkBuddy 的 MCP 配置入口不同版本的 WorkBuddy 入口位置略有差异但逻辑一致在设置里找“MCP”或“连接器”相关的面板选择“添加自定义连接器”或“编辑配置文件”。如果它直接给你打开一个mcp.json那就最省事直接在里面对应位置加一段。如果它只给了一个图形界面通常也会有“高级/JSON 模式”的切换切过去手动编辑。我的习惯是先备份原文件。把现有的mcp.json复制一份改名成mcp.json.bak万一改崩了能秒回滚。这个习惯救过我好几次尤其是同时接了多个连接器、括号容易配错的时候。4.2 写入混元生图连接器配置在mcpServers对象里新增一个键名字自己起建议用能一眼看懂用途的比如hunyuan-image。然后把上一节的骨架填进去把url换成你从服务方拿到的真实地址。填完之后整个文件应该是一个合法的 JSON——这一点极其重要JSON 不允许尾随逗号少一个引号整个文件就废了。{ mcpServers: { hunyuan-image: { type: sse, url: https://your-endpoint.example.com/sse?tokenYOUR_TOKEN, timeout: 60000, enabled: true } } }保存之后回到 WorkBuddy 的 MCP 面板应该能看到hunyuan-image这个连接器状态从“未连接”变成“已连接”或“就绪”。如果状态一直转圈先别急着改配置往下看排查章节。4.3 验证连接先看工具列表再跑一次真实调用连接状态变绿只是第一步真正要确认的是工具列表有没有拉回来。点开这个连接器的详情应该能看到它暴露的方法比如生成图片、查询任务状态之类。如果列表是空的说明连接建立了但握手/能力发现没成功多半是协议版本或鉴权问题。确认有工具之后跑一次最小调用给一句最简单的提示词比如“一只在窗台上晒太阳的橘猫写实风格”看它能不能返回图片地址或直接落盘。第一次调用建议把超时设长一点生图服务排队时响应会慢别因为等不及就以为失败了。注意首次调用如果返回的是任务 ID 而不是图片说明这是异步接口需要再调一次查询方法拿结果。别看到没有图片就以为接错了。5. SSE 连接稳定性超时、心跳与重连的实战处理5.1 为什么 SSE 总在“快完成时”断开热词里那句stream disconnected before completion: idle timeout waiting for sse描述的正是最气人的场景任务跑到 90% 断了。根因通常不在 WorkBuddy而在中间的网关。云托管服务的入口一般有负载均衡或 API 网关它们对“长时间没有数据流动的连接”会主动回收。生图这种任务提交后要等模型推理中间可能几十秒没有任何数据推送网关就认为这条连接死了。解决办法有两个方向一是让服务端定期发心跳这个你控制不了取决于服务方二是让客户端侧把超时设得足够长并且在断开后能自动重连。你能控制的是后者所以timeout这个字段别省直接给足。5.2 超时参数怎么定一个简单的估算方法超时不是越大越好设太大反而会让真正失败的请求卡很久。我的估算方法是超时 服务方承诺的最长处理时间 × 1.5 网络往返余量。假设生图服务文档说单张图最长 40 秒那 40 × 1.5 60 秒再加 10 秒网络余量timeout给 70000 毫秒比较稳。如果服务方没给承诺时间就按你实测的 P95 耗时再乘 1.5。场景建议 timeout说明快速文本类工具15000响应快超时短一点便于快速失败生图/生视频类60000~120000推理慢给足等待时间异步任务提交30000提交动作本身快查询另算5.3 断线重连把“失败”变成“重试”SSE 断开后理想情况是客户端自动重连并续上任务。但现实是很多云托管服务在断开后任务状态还在你只要重新查询就能拿到结果。所以我的做法是把生图拆成“提交”和“查询”两步提交失败就重试提交查询失败就重试查询而不是把整个流程当成一次调用。这样即使中间断了一次也不会白跑。如果你在 WorkBuddy 里能配置重试策略建议设置成指数退避第一次等 2 秒第二次 4 秒第三次 8 秒最多重试 3 次。这样既不会瞬间打爆服务端也能扛过短暂的网络抖动。6. 常见问题速查与避坑经验6.1 连接器显示已连接但工具列表为空这是最高频的问题。排查顺序我总结成一张表从上往下试基本能定位现象可能原因排查动作状态绿但无工具鉴权失败检查 headers 里的 key 是否正确、是否过期状态绿但无工具协议版本不匹配确认服务端支持的 MCP 版本必要时降级客户端状态绿但无工具URL 指向了错误路径确认/sse后缀是否必须有的服务是/mcp状态一直转圈网络不通用浏览器直接访问 URL 看是否有响应状态报错JSON 格式错误用在线 JSON 校验工具过一遍6.2 调用返回超时但服务端其实成功了这种情况很常见客户端等超时了但服务端其实已经把图生成好了。如果你直接重试可能会重复生成、浪费额度。我的经验是先查任务状态再决定要不要重试。如果服务端提供了查询接口超时后先查一次拿到结果就不要再提交了。这也是为什么我强烈建议把生图流程拆成提交查询两步。6.3 图片落盘路径和缓存目录的坑热词里有人问workbuddy 系统缓存目录能改到 d 盘吗这跟生图连接器其实相关——生成的图片默认可能落在系统缓存目录C 盘小的朋友很快就满了。我的做法是在连接器配置或 WorkBuddy 的通用设置里把输出目录显式指定到一个空间充足的盘。如果配置里没有这个选项就在调用工具时把目标路径作为参数传进去别依赖默认值。提示改缓存目录前先确认 WorkBuddy 有没有正在运行的任务运行中改路径可能导致文件写一半失败。6.4 几个我踩过的真实坑第一个坑token 里含有特殊字符直接拼在 URL 里没做编码结果请求被服务端拒绝。解决办法是确认 token 是否需要 URL 编码或者干脆放到 header 里传。第二个坑同时配了多个 SSE 连接器其中一个卡住导致整个 MCP 面板加载缓慢。后来我把不用的连接器enabled设为 false面板瞬间流畅。所以不用的连接器及时禁用别留着占资源。第三个坑以为timeout是全局的改了一个连接器结果影响了别的。实际上它是每个连接器独立的改的时候看清楚作用域。7. 接完之后还能怎么玩把生图嵌进工作流连接器接好只是起点。真正提升效率的是把它嵌进你的日常流程。比如我在写文章时会让 WorkBuddy 根据段落主题自动生成配图提示词再调用混元生图连接器出图最后按文章结构命名落盘。整个过程不用离开工作台配图从“额外任务”变成了“顺手一步”。再进一步你可以给 WorkBuddy 定几条规则让它在特定任务后自动触发配图比如“每次生成一篇带小标题的文档后为每个 H2 生成一张示意图”。热词里给 workbuddy 定几条规则后续对所有任务都生效说的就是这个思路。规则定好之后MCP 连接器就成了规则背后的执行手你只管下指令出图的事交给它。如果你手头还有其他 SSE 类的云服务配置思路完全一样换url、换鉴权、调timeout其余照抄。我个人的体会是MCP 这东西一旦接顺了第一个后面就是复制粘贴改参数的活真正的门槛只在第一次把 SSE 的超时和重连搞明白。