WorkBuddy接入自定义MCP连接器：SSE云托管与mcp.json配置实战

1. 为什么要在 WorkBuddy 里接一个自定义 MCP 连接器WorkBuddy 这类 AI 工作台用久了你会发现一个很现实的问题内置能力再强也覆盖不了你手头那些私有工具链。比如团队内部的设计素材库、自研的图片生成服务、某个只在公司内网跑的接口——这些都没法直接让 WorkBuddy 调用。MCPModel Context Protocol就是来解决这件事的。MCP 本质上是一套让 AI 客户端和外部工具对话的协议标准。你可以把它理解成 USB-CWorkBuddy 是电脑各种外部服务是外设MCP 就是那根统一接口的线。只要外设按 MCP 协议暴露能力WorkBuddy 就能识别、调用不需要为每个服务单独写适配代码。这也是为什么最近 MCP 相关的内容这么热——它把给 AI 接工具这件事从定制开发变成了配置工作。这篇要做的具体事情是给 WorkBuddy 接入一个自定义 MCP 连接器连接器背后是腾讯混元生图的 SSE 云托管服务。选这个例子不是随便挑的它同时踩中了三个新手最容易卡住的点SSE 传输方式MCP 支持 stdio 和 SSE 两种传输云托管服务基本都用 SSE而 SSE 的配置字段和本地命令式连接器完全不一样。远程云托管不是本地跑个进程而是要填 URL、处理鉴权、应对网络波动。mcp.json 配置WorkBuddy 靠这个文件识别连接器字段写错一个字符就连不上而且报错信息往往很含糊。适合谁看如果你已经装好 WorkBuddy、能用内置 skill 干活但想让它调用自己的服务这篇就是给你写的。全程不需要你懂 MCP 协议的完整规范但需要你能看懂 JSON、会用命令行验证接口。我会把每一步为什么这么填讲清楚而不是甩一份配置让你抄——因为抄配置的人遇到报错基本就废了。先说结论整个接入过程分四步——确认服务端 SSE 端点可用 → 写 mcp.json → 在 WorkBuddy 里加载并验证 → 处理鉴权和超时。听起来简单但每一步都有坑下面逐个拆。2. 动手前必须搞清楚的 MCP 传输方式与 SSE 端点2.1 stdio 和 SSE 到底差在哪为什么云托管只能用 SSEMCP 连接器有两种传输方式这个必须先分清否则你会在 mcp.json 里填错字段。stdio标准输入输出连接器是一个本地可执行程序WorkBuddy 启动它通过进程的标准输入输出收发 JSON-RPC 消息。典型配置长这样{ mcpServers: { local-tool: { command: node, args: [/path/to/server.js] } } }SSEServer-Sent Events连接器是一个远程 HTTP 服务WorkBuddy 通过一个 SSE 长连接接收服务端推送通过普通 HTTP POST 发送请求。配置长这样{ mcpServers: { remote-tool: { url: https://example.com/mcp/sse } } }关键区别在于stdio 的command字段和 SSE 的url字段不能混用。我见过有人把云托管地址填进command结果 WorkBuddy 直接报找不到可执行文件排查半天才发现是传输方式搞错了。为什么云托管只能用 SSE因为云服务不可能让你在本地起一个进程去连它的内部逻辑它只能暴露一个 HTTP 端点。SSE 的好处是服务端可以主动推送消息比如生图任务的进度更新这对生图这种耗时操作特别合适——你提交一个生图请求服务端可以分阶段推排队中生成中完成而不是让你傻等一个 HTTP 响应。注意SSE 是单向的服务端到客户端客户端到服务端的请求走的是另一个 POST 端点。MCP 的 SSE 传输实际上是SSE 接收 POST 发送的组合配置里通常只需要填 SSE 的 URL客户端会自动推导 POST 端点但不同实现推导规则不一样这点后面会讲。2.2 拿到腾讯混元生图 SSE 端点后先用 curl 验一遍在往 WorkBuddy 里塞配置之前一定要先用命令行确认这个 SSE 端点活着。这一步能帮你排除掉一半的问题——如果 curl 都连不上那绝对不是 WorkBuddy 的锅。假设你拿到的 SSE 端点是https://your-hunyuan-endpoint/mcp/sse先做一次探测curl -N -H Accept: text/event-stream \ -H Authorization: Bearer YOUR_TOKEN \ https://your-hunyuan-endpoint/mcp/sse几个参数解释一下-N关闭 curl 的缓冲让 SSE 消息实时打印出来。不加这个你会以为连接卡死了其实是 curl 在攒数据。Accept: text/event-stream告诉服务端我要的是 SSE 流。有些服务端不检查这个头但检查的也不少加上没坏处。Authorization云托管服务基本都要鉴权token 从哪来取决于你的服务开通方式。正常的话你应该看到类似这样的输出然后连接保持不断开event: endpoint data: /mcp/messages?sessionIdabc123这个endpoint事件非常关键——它告诉客户端你发请求要发到这个地址。很多 SSE 实现不会在配置里写 POST 端点而是靠这个事件动态告知。如果你 curl 的时候没看到这个事件说明服务端实现可能不标准后面 WorkBuddy 大概率也连不上。如果 curl 直接返回 401那是鉴权问题返回 404那是 URL 写错了一直挂着没输出可能是网络或服务端没启动。这三种情况在 WorkBuddy 里的报错都长一个样所以提前用 curl 定位能省你大量时间。2.3 一个容易被忽略的点SSE 端点的路径约定不同 MCP 服务端的 SSE 路径约定不一样。有的用/sse有的用/mcp/sse有的用/mcp。这不是随便起的而是服务端框架决定的。比如用官方 SDK 起的服务默认路径往往是/sse用某些封装框架可能是/mcp/sse。拿到端点后别自己猜路径以服务提供方给的文档为准。如果文档没写清楚就按 2.2 的方法挨个试。我遇到过有人把/sse写成/sse/多了个斜杠结果服务端返回 301 重定向而 WorkBuddy 的 SSE 客户端不跟随重定向直接报连接失败。这种问题用 curl 加-v看响应头一眼就能发现curl -v -N -H Accept: text/event-stream https://your-endpoint/mcp/sse看返回的HTTP/1.1 301还是HTTP/1.1 200一目了然。3. 写对 mcp.json字段、鉴权头和常见填错3.1 mcp.json 放在哪WorkBuddy 怎么读它WorkBuddy 读取 MCP 配置的位置通常有两个层级全局配置影响所有工作区路径一般在用户目录下比如~/.workbuddy/mcp.json具体路径以你的安装版本为准可以在设置里找到打开配置目录之类的入口。项目级配置只对当前项目生效放在项目根目录的.workbuddy/mcp.json或类似位置。我的建议是调试阶段用项目级配置。因为改全局配置一旦写错可能影响你其他项目的正常使用而且排查时不好隔离变量。等项目级跑通了再决定要不要提升到全局。配置文件的顶层结构是固定的{ mcpServers: { 连接器名字: { // 这里填传输方式和参数 } } }mcpServers这个 key 不能改改了 WorkBuddy 就找不到。连接器名字是你自己起的会显示在 WorkBuddy 的工具列表里建议起个有意义的名字比如hunyuan-image别用test1、abc这种过两天你自己都忘了它是干嘛的。3.2 SSE 连接器的完整字段写法针对腾讯混元生图这个 SSE 云托管服务一个完整的配置大概是这样{ mcpServers: { hunyuan-image: { url: https://your-hunyuan-endpoint/mcp/sse, headers: { Authorization: Bearer YOUR_TOKEN } } } }逐字段说urlSSE 端点地址必须和 curl 验证通过的那个完全一致包括协议、路径、有没有结尾斜杠。headers附加的 HTTP 头。鉴权 token 就放这里。注意headers是对象不是数组别写成[{Authorization: ...}]。有些 MCP 客户端还支持transport字段显式声明传输方式{ mcpServers: { hunyuan-image: { transport: sse, url: https://your-hunyuan-endpoint/mcp/sse, headers: { Authorization: Bearer YOUR_TOKEN } } } }transport字段不是所有版本都认但如果你的 WorkBuddy 版本支持强烈建议写上。因为当配置里同时有url和command时比如你从别处复制配置没删干净显式的transport能避免客户端猜错。3.3 鉴权 token 怎么放才安全别直接写死在文件里把 token 明文写在 mcp.json 里能跑通但有两个问题一是配置文件可能被同步到云端或提交到 gittoken 就泄露了二是 token 过期后你得手动改文件。更稳妥的做法是用环境变量。很多 MCP 客户端支持在配置里引用环境变量{ mcpServers: { hunyuan-image: { url: https://your-hunyuan-endpoint/mcp/sse, headers: { Authorization: Bearer ${HUNYUAN_TOKEN} } } } }然后在启动 WorkBuddy 之前把环境变量设好export HUNYUAN_TOKENyour-actual-tokenWindows 下用set HUNYUAN_TOKEN...或者通过系统环境变量界面设置。注意环境变量替换的语法${VAR}是否生效取决于你的 WorkBuddy 版本。有的版本支持有的不支持。如果不支持替换后 token 会变成字面量${HUNYUAN_TOKEN}服务端返回 401。验证方法很简单配置好后看 WorkBuddy 的日志里实际发出的请求头或者先用一个明显错误的 token 测试看报错是不是 401。如果环境变量方案不生效退而求其次把 mcp.json 加入.gitignore并且确认你的配置目录不在任何自动同步的文件夹里。这是底线。3.4 我踩过的三个配置坑坑一JSON 尾随逗号。JSON 标准不允许最后一个元素后面有逗号但很多人写 JS 写习惯了会加上。WorkBuddy 解析失败时往往只报配置格式错误不告诉你哪一行。用jq验证一下最快jq . mcp.json有语法错误 jq 会直接指出行号。坑二headers 里 key 大小写。HTTP 头理论上大小写不敏感但有些服务端实现会严格匹配。Authorization别写成authorization或AUTHORIZATION按文档给的来。坑三URL 里的特殊字符没转义。如果你的端点 URL 带查询参数比如?tokenxxxversion2在 JSON 字符串里是合法的不用转义但如果 token 里本身有、/、这些 base64 字符要确认服务端是否要求 URL 编码。这个坑比较隐蔽表现是curl 能连WorkBuddy 连不上因为两者对 URL 的处理可能不同。4. 在 WorkBuddy 里加载连接器并验证生图能力4.1 加载配置后先看工具列表有没有出现配置写好后重启 WorkBuddy或者用它的重新加载 MCP功能如果有的话。然后打开工具/skill 列表找你的连接器名字hunyuan-image。如果没出现按这个顺序排查配置文件路径对不对确认 WorkBuddy 读的是你改的那个文件。有的版本项目级配置优先级高于全局你在全局改了但项目级有个同名连接器覆盖了就会以项目级为准。JSON 能不能解析用jq . mcp.json过一遍。看日志WorkBuddy 一般有 MCP 相关日志会记录尝试连接 xxx连接失败原因。这是最直接的线索别跳过。连接成功后工具列表里应该能看到这个连接器暴露的具体工具。腾讯混元生图服务通常会暴露类似generate_image、text_to_image这样的工具每个工具有自己的参数 schema比如 prompt、尺寸、风格。这些 schema 是服务端定义的WorkBuddy 只是展示出来。4.2 用一句话触发一次生图观察完整链路验证连接器能不能真正干活最直接的办法是让 WorkBuddy 调一次。在对话里说用 hunyuan-image 生成一张图内容是一只在窗台上晒太阳的橘猫水彩风格然后观察几件事WorkBuddy 有没有识别出该调用hunyuan-image的工具而不是自己瞎编。调用参数有没有正确填充prompt 是不是你给的那句。返回结果是图片 URL、base64 还是别的格式。如果 WorkBuddy 说我没有这个能力说明工具没加载成功如果它调用了但报错看错误信息是鉴权、参数还是超时。这里有个经验第一次调用尽量用最简单的参数。别一上来就试复杂 prompt 加一堆可选参数那样出错了你分不清是连接问题还是参数问题。先用最简参数跑通再逐步加复杂度。4.3 SSE 长连接的稳定性idle timeout 怎么处理SSE 是长连接云托管服务通常有 idle timeout——一段时间没有数据传输就断开。生图这种操作从提交到出图可能几十秒如果中间服务端不推心跳连接可能被中间层负载均衡、网关掐断。典型报错是stream disconnected before completion: idle timeout waiting for SSE。这个报错的意思是SSE 流在完成前断开了原因是等待 SSE 数据超时。处理思路有三层第一层确认服务端有没有心跳。标准做法是服务端每隔 15-30 秒发一个注释行: heartbeat或空事件保持连接活跃。如果服务端没做客户端侧很难补救。第二层看客户端有没有超时配置。有些 MCP 客户端允许配置 SSE 超时时间在 mcp.json 里加类似timeout: 120000的字段单位毫秒。但不是所有版本都支持得查你用的版本文档。第三层缩短单次请求耗时。如果生图本身就要两分钟而网关 60 秒就断那只能改架构——比如服务端改成提交任务返回 taskId客户端轮询结果的模式。但这需要服务端配合不是客户端能单方面解决的。我实际遇到这个报错时先做的是用 curl 挂着 SSE 端点看它多久断time curl -N -H Accept: text/event-stream https://your-endpoint/mcp/sse如果 curl 也是 60 秒断那就是服务端或网关的问题跟 WorkBuddy 无关如果 curl 能挂很久那才是客户端配置问题。这个二分法能快速定位责任方。5. 让连接器真正好用的几个进阶调整5.1 给连接器起名和描述影响 AI 的调用判断WorkBuddy 决定要不要调用某个工具时会参考连接器和工具的名字、描述。如果你把连接器命名成tool1工具描述又是服务端默认的干巴巴一句话AI 很可能在该调用的时候不调用。能改的地方连接器名字在 mcp.json 里改成语义化的比如hunyuan-text-to-image。工具描述如果服务端暴露的 schema 里描述太简略而你又有权限改服务端把描述写清楚比如根据中文或英文 prompt 生成图片支持水彩、油画、赛博朋克等风格返回图片 URL。描述里带上触发场景AI 判断会更准。如果服务端改不了可以在 WorkBuddy 的自定义指令里补一句比如需要生成图片时优先使用 hunyuan-image 连接器。这是绕过服务端限制的实用技巧。5.2 多个 MCP 连接器共存时的命名冲突当你接了多个连接器可能出现工具重名。比如两个连接器都暴露了generate_imageWorkBuddy 调用时可能选错。解决办法是在 mcp.json 里给连接器起不冲突的名字并且如果客户端支持用命名空间前缀区分。有些实现会自动把工具名变成连接器名.工具名的形式有些不会。这个得实测——接两个连接器各调一次看日志里实际调用的是哪个。5.3 缓存目录和配置目录的坑WorkBuddy 有系统缓存目录MCP 连接器的某些状态比如 SSE sessionId可能缓存在那里。如果你改了配置但行为没变可能是缓存没刷新。可以尝试完全退出 WorkBuddy 再启动而不是只关窗口。找到缓存目录手动清理具体路径在设置里能查到。确认配置目录和缓存目录不在同一个被同步的网盘文件夹里否则多台机器之间会互相干扰。我遇到过配置改了但一直不生效最后发现是缓存目录里存了旧的连接器状态。清掉缓存重启就好了。这个坑不常见但一旦遇到很折磨人因为你会怀疑自己配置写错了反复改配置反而越改越乱。5.4 安全审核相关的注意事项WorkBuddy 这类工具通常有安全审核机制会检查 MCP 连接器请求的内容。生图场景下如果 prompt 触发了审核可能返回的是审核拦截而不是图片。这不是连接器故障是内容策略。处理方式把审核返回的错误信息完整读一遍通常会告诉你哪类内容被拦。调整 prompt 重试即可。别把审核拦截当成连接问题去排查方向错了白费功夫。另外自定义 MCP 连接器意味着你把外部服务接进了 AI 工作台要确认这个服务是你信任的。它会收到你通过 WorkBuddy 发送的内容包括可能敏感的 prompt。生产环境用之前先确认服务方的数据处理策略。6. 排查连接失败时我用的完整链路连接器连不上时别东一榔头西一棒子按这个顺序走能覆盖 90% 的情况步骤检查项命令/方法典型结论1端点是否可达curl -v -N -H Accept: text/event-stream URL连不上→网络/URL 问题2鉴权是否通过同上看返回码401→token 问题3是否收到 endpoint 事件同上看输出没有→服务端实现问题4JSON 是否合法jq . mcp.json报错→语法问题5配置路径是否正确查 WorkBuddy 设置里的配置目录不一致→改错文件6日志里连接尝试记录看 WorkBuddy MCP 日志有明确错误→按错误处理7缓存是否干扰清缓存重启行为变化→缓存问题这个链路的核心逻辑是从外到内先确认外部服务本身没问题再确认配置格式没问题最后才怀疑 WorkBuddy 内部。因为大部分WorkBuddy 连不上的案例根因都在前两步。我印象最深的一次排查折腾了一小时以为是 WorkBuddy 的 bug最后发现是服务端 URL 少写了一个路径段curl 时我用的另一个地址所以没发现。从那以后我养成了习惯——curl 验证用的 URL 和写进 mcp.json 的 URL直接从同一个地方复制粘贴绝不手打。7. 一些实测下来的经验和小技巧关于 SSE 连接器的调试我总结了几条用curl -N挂着看事件流比任何日志都直观。WorkBuddy 的日志可能只记录连接失败但 curl 能让你看到服务端到底发了什么、什么时候断的。这是排查 SSE 问题的第一工具。配置改完先别急着重启 WorkBuddy先jq验证 JSON。JSON 语法错误是最低级的错误但也是最容易犯的尤其是手写配置的时候。jq一秒就能告诉你哪行有问题。token 用环境变量别写死。哪怕你的 WorkBuddy 版本不支持${VAR}替换也至少把配置文件排除在版本控制之外。token 泄露的代价远大于多花五分钟配置环境变量。第一次调用用最简参数。跑通链路比测试功能边界重要。链路通了参数慢慢调。遇到 idle timeout先用 curl 测服务端的心跳行为。这能帮你快速判断是服务端问题还是客户端问题避免在错误的方向上浪费时间。连接器名字和工具描述值得花时间打磨。这直接影响 AI 会不会在该用的时候用上它。一个叫tool1的连接器和一个叫hunyuan-text-to-image且描述清晰的连接器被正确调用的概率差很多。最后说个心态问题MCP 接入这类事情第一次做大概率会卡在某个环节这很正常。关键是每一步都留下可验证的证据——curl 的输出、jq 的结果、日志的片段。有了这些证据问题定位就是线性的没有证据就只能在猜测里打转。我接过好几个自定义连接器最快的半小时搞定最慢的折腾了一下午差别往往不在技术难度而在排查方法是否系统。