1. 为什么要在 WorkBuddy 里接一个自定义 MCP 连接器WorkBuddy 这类 AI 工作台用久了你会发现一个很现实的问题内置能力再全也覆盖不了你手头那些私有工具链。比如团队内部的设计素材库、自研的图片生成服务、某个只在公司内网跑的接口——这些都没法直接让 WorkBuddy 调用。MCPModel Context Protocol模型上下文协议就是来解决这件事的它把外部能力包装成 WorkBuddy 能识别的工具让 AI 在对话里直接调用而不是你复制粘贴来回倒腾。我这次要接的是腾讯混元生图的 SSE 云托管服务。选它当例子有两个原因一是生图这种能力特别适合放进工作流写文案的时候顺手出一张配图效率提升非常直观二是它走的是 SSEServer-Sent Events长连接和常见的 HTTP 请求式接口不一样踩坑点集中讲透了之后你接别的 SSE 类 MCP 也能照搬。先说清楚 MCP 到底是个什么定位。很多人第一次听到协议两个字会犯迷糊以为是什么硬件标准。其实 MCP 是软件层面的通信约定你可以把它理解成AI 和工具之间的 USB 接口标准——只要工具按这个标准做了插头AI 就能即插即用不用为每个工具单独写适配代码。WorkBuddy 作为客户端Host通过mcp.json这个配置文件去发现和加载各个 MCP ServerServer 再把具体能力比如生成图片暴露成一个个 tool。这篇文章适合三类人看一是刚上手 WorkBuddy、想扩展它能力边界的新手二是手里有自研服务、想接进 AI 工作流的开发者三是被 SSE 长连接坑过、想找个完整案例对照排查的人。我会从配置文件怎么写、SSE 连接为什么容易断、参数怎么传、报错怎么查一路讲到实测中的那些文档不会写但你必须知道的细节。全程按我实际操作的顺序来你可以直接抄作业。2. 动手前必须搞清楚的 MCP 加载机制2.1 mcp.json 在 WorkBuddy 里扮演什么角色WorkBuddy 启动的时候会去读mcp.json这个配置文件里面登记了所有要加载的 MCP Server。这个文件的结构不复杂但字段的含义必须弄明白否则后面报错你都不知道从哪查。核心字段大概是这样几类mcpServers是顶层容器下面每个键就是一个 Server 的名字你自己起见名知意就行每个 Server 里要声明它是怎么启动的——是本地命令行进程commandargs还是远程 URLurl。这里有个特别容易混淆的点本地 stdio 型 Server 和远程 SSE 型 Server 的配置字段完全不同。stdio 型靠command拉起一个本地进程通过标准输入输出通信SSE 型则是直接给一个urlWorkBuddy 去连这个地址。我这次接的混元生图是云托管服务属于后者所以配置里写的是url而不是command。很多人第一次配 SSE 失败就是因为照着 stdio 的模板抄把url写成了command结果 WorkBuddy 一直在那找不存在的本地可执行文件。提示改完mcp.json之后WorkBuddy 一般需要重启或者手动触发一次重新加载 MCP配置才会生效。别改完就在那等它不会自动热更新。2.2 SSE 和普通 HTTP 接口的本质区别要接 SSE 服务先得理解它和普通接口差在哪。普通 HTTP 接口是一问一答你发一个请求服务器返回一个完整响应连接就关了。SSE 不一样它是一次连接、持续推送客户端发起连接后服务器保持这个连接不关有数据就顺着这条通道推过来。MCP 用 SSE 是为了支持服务端主动通知、流式返回这类场景——比如生图任务耗时较长服务端可以边处理边推状态。这个特性带来一个直接后果连接是有生命周期的而且可能被各种中间环节掐断。网络抖动、服务端空闲超时、代理层超时都会让这条长连接断掉。你可能会遇到类似stream disconnected before completion: idle timeout waiting for SSE这样的报错翻译过来就是SSE 流在完成前断开了因为空闲超时。这不是你代码写错了而是连接闲置太久被回收了。理解这一点后面排查问题就有方向了。2.3 云托管 SSE 服务的连接地址怎么拿混元生图的 SSE 云托管服务接入前你需要拿到两样东西服务端点 URL和鉴权凭证。URL 一般形如https://xxx/mcp或带路径的 SSE 地址鉴权通常是一个 token拼在 URL 的 query 参数里或者放在请求头里。具体怎么拼取决于服务方的约定接入前一定要把服务方的接入文档翻一遍确认 token 是走 query 还是走 header。我踩过的一个坑是token 里如果包含特殊字符比如、/、直接拼进 URL 可能被截断或转义出错。稳妥做法是先做一次 URL 编码或者干脆确认服务方是否支持 header 传 token。另外 token 是有有效期的过期后连接会直接被拒表现就是连不上或者一连就断。所以配置完之后如果连不上第一件事就是确认 token 是不是新鲜的。3. 一步步把混元生图 MCP 配进 WorkBuddy3.1 找到并编辑 mcp.json 的正确姿势第一步是定位mcp.json。WorkBuddy 的配置文件通常放在它的用户配置目录下不同系统路径不一样。Windows 一般在用户目录的 AppData 相关路径里macOS 和 Linux 则在~/.config或~/.workbuddy这类目录下。如果你找不到最直接的办法是在 WorkBuddy 的设置界面里找打开配置目录之类的入口或者搜一下mcp.json这个文件名。找到之后用任意文本编辑器打开。强烈建议改之前先备份一份因为 JSON 格式对逗号、引号极其敏感少一个逗号整个文件就废了WorkBuddy 会直接加载失败。我一般会复制一份mcp.json.bak放旁边改崩了直接还原。编辑的时候注意 JSON 语法字符串必须用双引号对象之间用逗号分隔最后一个字段后面不能有逗号。这些看着是常识但手写配置时十次有八次栽在这上面。3.2 写对 SSE 型 Server 的配置块下面是我实际用的配置结构你可以对照着改。注意这是 SSE 型远程 URL的写法和本地 stdio 型完全不同{ mcpServers: { hunyuan-image: { url: https://你的混元生图服务地址/mcp?token你的token, type: sse } } }几个关键点解释一下。hunyuan-image是我给这个 Server 起的名字你可以改成任何你记得住的名字但建议用英文、别带空格因为有些地方会拿这个名字当标识符用。url就是服务端点token 按服务方要求拼在 query 里。type字段声明这是 SSE 类型有些版本的 WorkBuddy 靠这个字段决定用哪种连接方式漏了可能被当成默认类型处理导致连不上。注意如果你的 token 需要放在请求头而不是 URL 里配置结构会不一样通常要加一个headers字段。具体写法以服务方文档为准别硬套。3.3 重启加载与连接状态确认配置写完保存接下来重启 WorkBuddy 或者触发重新加载。加载成功后你一般能在 MCP 管理界面看到这个 Server 的状态是已连接并且能看到它暴露出来的工具列表——混元生图这边应该能看到类似生成图片查询任务状态这样的 tool。如果状态是连接失败或者一直转圈先别急着改配置按这个顺序查第一URL 能不能在浏览器或命令行里直接访问通排除网络和服务地址问题第二token 是不是过期了第三JSON 格式有没有语法错误。这三步能解决八成以上的初次接入失败。我实测下来最容易忽略的是服务地址末尾的斜杠。有的服务对/mcp和/mcp/处理不一样多一个斜杠就 404。所以如果连不上把末尾斜杠去掉或加上各试一次成本很低。4. SSE 长连接的稳定性问题与排查链路4.1 idle timeout 报错的完整排查过程前面提到的idle timeout waiting for SSE是我这次踩得最深的坑这里把完整排查链路还原一遍你遇到类似问题可以照着走。现象是配置好后第一次调用生图工具能成功但隔一段时间再调用就报流断开、空闲超时。第一反应我以为是 token 过期换了新 token 还是这样排除。第二步怀疑是服务端问题但用命令行工具直接连 SSE 端点发现连接能建立、也能收到数据说明服务本身没问题。第三步才意识到是空闲超时——连接建立后如果一段时间没有数据往来中间的网络层可能是负载均衡、可能是代理会主动把这条看起来没在用的长连接回收掉。定位到原因后解决思路就清晰了要么让连接保持活跃心跳要么在每次调用前重建连接。MCP 客户端一般会有自己的重连机制但重连需要时间如果超时设置太短就会出现刚断就要用的尴尬。我的做法是确认 WorkBuddy 侧有没有可调的超时或心跳配置没有的话就接受首次调用可能稍慢这个现实别在超时参数上死磕。4.2 连接建立成功但工具调用失败的区分方法还有一种情况更迷惑Server 状态显示已连接但一调用工具就失败。这时候要区分是连接层问题还是业务层问题。判断方法很简单看报错信息里有没有 HTTP 状态码。如果是 401/403那是鉴权问题token 或权限不对如果是 404是地址问题如果是 500 及以上是服务端内部错误如果压根没有状态码、只有流断开之类的描述那才是连接层问题。我遇到过一次已连接但调用失败最后发现是工具参数格式不对。混元生图生成图片需要传 prompt提示词我一开始传了个空字符串服务端直接拒绝。这种错误不会体现在连接状态上只会体现在调用返回里。所以看到已连接别高兴太早一定要实际调一次工具验证端到端通不通。4.3 让连接更稳的几个实操习惯基于这次经验我总结了几个让 SSE 连接更稳的习惯。第一token 定期更换别用一个快过期的 token 硬撑过期瞬间断连很难排查。第二配置里尽量精简不要加一堆用不上的字段字段越多越容易因为某个字段格式不对导致整体加载失败。第三保留一份能用的配置备份改崩了随时还原这是最省时间的兜底手段。还有一个反直觉的点不是所有 SSE 服务都适合长时间挂着。如果你的使用频率很低比如一天就用一两次与其让它一直挂着等超时不如接受每次调用时重新建立连接的开销。稳定性有时候不是靠保持连接换来的而是靠快速重建换来的。5. 参数传递与工具调用的实战细节5.1 生图工具的参数怎么传才不出错混元生图这个工具核心参数就是提示词prompt可能还有尺寸、风格之类的可选参数。传参的时候有两个坑。第一个是中文提示词的编码问题如果服务端对编码处理不严谨中文可能乱码稳妥做法是确认服务端支持 UTF-8或者必要时做一次编码转换。第二个是参数名必须和服务端定义完全一致大小写、下划线都不能错prompt写成Prompt或prompts都会失败。我建议第一次接入时先用最简单的参数调通只传一个 prompt确认端到端没问题之后再逐步加可选参数。这样出问题时你能快速定位是哪个参数引起的而不是一上来就传一堆参数然后对着报错发呆。5.2 从调用到拿到图片的完整链路一次完整的生图调用链路是这样的WorkBuddy 通过 SSE 连接把工具调用请求发给 MCP ServerServer 收到后去调用混元生图的实际接口生图完成后把结果通常是图片 URL 或 base64通过 SSE 推回来WorkBuddy 再展示给你。这里面耗时主要花在生图本身SSE 传输反而是快的。所以如果调用很慢别怀疑连接大概率是生图任务本身在排队或计算。如果返回的是图片 URL注意这个 URL 可能有时效性过期就访问不了。需要长期保存的话拿到 URL 后第一时间下载到本地。如果返回的是 base64那数据量可能比较大注意别在日志里把它整个打出来会刷屏。5.3 调用失败时的错误信息怎么读MCP 工具调用失败时返回的错误信息通常分两层一层是 MCP 协议层的错误比如连接断开、超时一层是业务层的错误比如参数不合法、额度不足。读错误信息的时候先看它属于哪一层。协议层的错误往往比较笼统需要结合连接状态一起判断业务层的错误通常很具体直接告诉你哪里不对。我遇到过一次额度不足的报错一开始以为是技术问题查了半天连接最后发现是账户余额不够。所以看到报错先别急着往技术方向想把错误信息完整读一遍很多时候答案就写在里面。6. 实测中那些文档不会告诉你的经验6.1 配置文件的字段冲突与优先级mcp.json里如果同一个 Server 名字出现了两次或者同时配了url和command行为是不确定的——有的版本会取最后一个有的会直接报错。所以配置的时候一定要保证每个 Server 名字唯一、每种连接方式只配一种。我见过有人复制粘贴配置块的时候忘了改名字结果两个 Server 重名加载行为诡异查了半天才发现是重名。另外如果 WorkBuddy 支持多级配置比如全局配置 项目级配置要注意优先级。通常项目级会覆盖全局级但不同版本可能不一样。如果你改了配置没生效先确认你改的是不是当前生效的那一份。6.2 网络环境对 SSE 连接的影响SSE 是长连接对网络环境的稳定性比普通请求敏感得多。如果你在公司网络里中间可能有代理或防火墙它们对长连接的处理策略和短连接不一样可能几分钟就掐一次。这种情况下与其和网络环境较劲不如接受连接会断这个前提把重点放在断了能快速重连上。我在不同网络环境下测过同一个配置表现差异很明显。所以如果你在一个环境里配好了换到另一个环境连不上先别怀疑配置很可能是网络层的问题。用命令行工具直接测一下 SSE 端点能不能连通能快速区分是配置问题还是网络问题。6.3 安全审核相关的注意事项接入外部服务的时候token 这类凭证一定要妥善保管别把它提交到代码仓库或者发到公开渠道。mcp.json如果会被分享出去记得先把 token 替换成占位符。另外接入的服务要确认是可信来源别随便接来路不明的 MCP Server因为它能拿到你传给它的数据。WorkBuddy 本身如果有安全审核机制接入自定义 Server 时可能会触发审核流程。这是正常的按提示走就行别想着绕过。审核的目的是防止恶意 Server 窃取数据对你自己也是一种保护。7. 把这套方法迁移到其他 SSE 类 MCP7.1 换一个服务要改哪些地方这套流程不只适用于混元生图。你要接任何 SSE 型的 MCP 服务需要改的其实就三处Server 名字改成新服务的名字、URL换成新服务的端点、token换成新服务的凭证。配置结构、加载方式、排查思路都是通用的。所以你把这次配混元生图的经验吃透下次接别的 SSE 服务基本就是改几个字段的事。唯一需要注意的是不同服务暴露的工具不一样参数也不一样。接入新服务后第一件事是看它暴露了哪些工具、每个工具要什么参数然后拿最简单的参数调通一次再逐步深入。7.2 本地 stdio 型 MCP 的配置差异如果你要接的是本地 stdio 型 MCP比如某些本地工具配置写法完全不同。它不用url而是用command指定可执行文件、args传参数、env传环境变量。这种类型的 Server 是 WorkBuddy 在本地拉起一个进程来通信所以你要确保那个可执行文件存在、路径正确、有执行权限。stdio 型的好处是不依赖网络稳定性通常更好坏处是只能在本机跑没法共享给团队。SSE 型正好相反能共享但有网络依赖。选哪种取决于你的场景没有绝对优劣。7.3 判断一个服务该用哪种接入方式拿到一个服务怎么判断它该用 SSE 还是 stdio看它提供什么。如果服务方给的是一个远程 URL那就是 SSE或类似的远程连接方式如果给的是一个本地可执行文件或脚本那就是 stdio。有些服务两种都支持那就看你的使用场景要团队共享、要跨设备用选远程要稳定、要离线可用选本地。我个人的习惯是能用远程就用远程因为省去了本地环境配置的麻烦团队里别人也能直接用同一份配置。但如果是涉及敏感数据的服务本地跑更放心。8. 我个人的几点实操体会配完这套东西最大的感受是MCP 接入的难点从来不在配置本身而在排查。配置就那么几行抄都能抄对真正花时间的是连不上、断了、调不通的时候怎么快速定位问题在哪一层。我的经验是永远按网络通不通 → 鉴权对不对 → 配置格式对不对 → 参数对不对这个顺序查从外到内一层层排除比东一榔头西一棒子高效得多。另外SSE 长连接的稳定性问题很多时候不是你能完全控制的。与其追求永不掉线不如接受会掉线这个现实把精力放在快速重连和清晰报错上。我现在的做法是配置里保持最简出问题先看报错属于哪一层然后针对性解决不瞎改。最后分享一个小技巧每次改完mcp.json先用一个最简单的工具调用验证端到端通不通通了再去用复杂功能。这样一旦出问题你能确定是配置问题还是使用问题排查范围直接缩小一半。这个习惯帮我省了不知道多少时间。