1. 为什么我要给 WorkBuddy 接一个自定义 MCP 连接器

WorkBuddy 这类 AI 工作台用久了，你会发现一个很现实的问题：它自带的技能再全，也覆盖不了你手头那些“偏门但高频”的需求。比如我最近做内容配图，每次都要切到浏览器、打开生图页面、复制提示词、下载图片、再拖回项目目录，一套动作下来三五分钟没了。如果一天要出十几张图，这个时间成本非常吓人。

MCP（Model 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 服务端和客户端之间要传数据，传输方式主要有几种，SSE（Server-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?token=YOUR_TOKEN", "headers": { "Authorization": "Bearer YOUR_KEY" }, "timeout": 60000, "enabled": true } } }

各字段的作用和常见取值，我整理成一张表，方便你对照：

3.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?token=YOUR_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。

5.3 断线重连：把“失败”变成“重试”

SSE 断开后，理想情况是客户端自动重连并续上任务。但现实是，很多云托管服务在断开后任务状态还在，你只要重新查询就能拿到结果。所以我的做法是：把生图拆成“提交”和“查询”两步，提交失败就重试提交，查询失败就重试查询，而不是把整个流程当成一次调用。这样即使中间断了一次，也不会白跑。

如果你在 WorkBuddy 里能配置重试策略，建议设置成指数退避：第一次等 2 秒，第二次 4 秒，第三次 8 秒，最多重试 3 次。这样既不会瞬间打爆服务端，也能扛过短暂的网络抖动。

6. 常见问题速查与避坑经验

6.1 连接器显示已连接但工具列表为空

这是最高频的问题。排查顺序我总结成一张表，从上往下试，基本能定位：

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 的超时和重连搞明白。