1. 为什么我要给 WorkBuddy 接一个自定义 MCP 连接器WorkBuddy 这个工具我用了一段时间日常写代码、查资料、整理文档都靠它。但用久了就会发现一个问题它内置的能力再强也覆盖不了我所有的需求。比如我经常需要根据一段文字描述直接生成配图用来做文章封面或者演示文稿的插图这个需求 WorkBuddy 原生并不支持。MCP 就是解决这类问题的关键。MCP 全称 Model Context Protocol翻译过来叫“模型上下文协议”你可以把它理解成一套标准化的插座接口。WorkBuddy 是电器外部工具是各种插头只要双方都遵循 MCP 这套接口规范就能即插即用。这个类比可能不完全精确但足够帮你理解它的定位——它不是什么高深的技术概念就是一个让 AI 助手和外部服务对话的通用语言。我这次要接入的是腾讯混元生图服务它提供了 SSE 方式的云托管 MCP 端点。SSE 全称 Server-Sent Events是一种服务器主动向客户端推送数据的技术。跟普通的 HTTP 请求不同SSE 建立连接后服务器可以持续不断地往客户端发消息非常适合 AI 生成图片这种需要等待一段时间才有结果的场景。你发一个生图请求过去服务器处理完了通过 SSE 通道把结果推回来整个过程不需要你反复轮询。这篇文章适合两类人看一类是已经装了 WorkBuddy 但还没折腾过 MCP 配置的想看看接入自定义连接器到底是怎么回事另一类是用过内置 MCP 但想接自己私有服务的需要一份能照着操作的完整流程。我会从配置文件怎么写、参数怎么填、踩过哪些坑一步步讲清楚。整个过程不需要你写代码核心工作就是编辑一个 JSON 文件然后重启 WorkBuddy。2. 接入前的准备工作与核心概念梳理2.1 先搞清楚 MCP 连接器的几种通信方式MCP 协议支持多种通信方式常见的有 stdio、SSE 和 WebSocket 三种。stdio 是标准输入输出通常用于本地进程之间的通信比如你写了一个 Python 脚本作为 MCP 服务端WorkBuddy 启动这个脚本然后通过标准输入输出跟它交互。SSE 走的是 HTTP 长连接服务端在远程服务器上你只需要一个 URL 就能连上。WebSocket 则是全双工通信双方都可以主动发消息。我这次选的腾讯混元生图 MCP 是 SSE 方式因为它是云托管服务我不需要在本地跑任何东西只要网络能通就行。这也是目前大多数云服务商提供的 MCP 接入方式毕竟让用户本地装一堆依赖再跑一个服务端门槛太高了。注意SSE 和 WebSocket 虽然都是长连接但 SSE 是单向的——只有服务器往客户端推消息。对于生图这种“客户端发一次请求、服务器回一次结果”的场景SSE 完全够用。如果你需要双向实时交互比如聊天室那种才需要考虑 WebSocket。2.2 腾讯混元生图 MCP 的接入信息从哪来腾讯混元生图服务的 MCP 端点信息需要从它的控制台获取。一般来说你在腾讯云控制台开通混元生图服务后会得到一个 API Key 和一个 SSE 端点 URL。这个 URL 的格式通常是这样的https://api.example.com/mcp/sse?keyYOUR_API_KEY不同云服务商的 URL 格式可能略有差异但核心要素就两个端点地址和鉴权凭证。有些服务把鉴权信息放在 URL 的查询参数里有些则要求放在请求头中。腾讯混元生图目前是放在 URL 查询参数里的所以你在配置的时候直接把完整的 URL 填进去就行。我建议你先把这两个信息记在一个临时文本文件里因为后面配置的时候要反复用到。另外API Key 这种东西不要截图发到群里或者提交到公开仓库这个不用我多说。2.3 WorkBuddy 的 MCP 配置文件在哪WorkBuddy 的 MCP 配置统一放在一个叫mcp.json的文件里。这个文件的位置跟你的操作系统有关Windows 系统通常在C:\Users\你的用户名\.workbuddy\mcp.jsonmacOS 系统通常在/Users/你的用户名/.workbuddy/mcp.jsonLinux 系统通常在/home/你的用户名/.workbuddy/mcp.json如果你找不到这个文件可以在 WorkBuddy 的设置界面里找“打开配置目录”之类的选项它会直接帮你定位到.workbuddy文件夹。如果mcp.json不存在手动创建一个就行WorkBuddy 启动时会自动读取。实操心得我建议在修改mcp.json之前先备份一份。这个文件里可能已经配置了其他 MCP 连接器改错了会导致所有连接器都失效。备份命令很简单复制一份改个名就行。2.4 确认 WorkBuddy 版本支持自定义 MCP不是所有版本的 WorkBuddy 都支持自定义 MCP 连接器。根据我的经验WorkBuddy 从某个版本开始才开放了mcp.json的手动编辑能力。你可以在 WorkBuddy 的“关于”页面查看版本号如果版本太旧建议先升级到最新版。另外WorkBuddy 国际版和国内版在 MCP 配置上基本一致mcp.json的格式是通用的。如果你用的是国际版操作步骤完全一样只是界面语言可能不同。3. 手把手配置 mcp.json 接入混元生图3.1 mcp.json 的基本结构长什么样mcp.json是一个 JSON 格式的配置文件顶层是一个对象里面有一个mcpServers字段这个字段下面挂载所有 MCP 连接器的配置。每个连接器有一个唯一的名字作为 keyvalue 是这个连接器的详细配置。一个最简单的 SSE 类型 MCP 连接器配置长这样{ mcpServers: { hunyuan-image: { type: sse, url: https://api.example.com/mcp/sse?keyYOUR_API_KEY, description: 腾讯混元生图服务 } } }这里有几个关键字段需要解释type通信方式SSE 就填sse如果是本地进程就填stdioWebSocket 就填websocket。urlSSE 端点的完整地址包含鉴权参数。description描述信息方便你自己识别这个连接器是干什么的WorkBuddy 界面上可能会显示这个描述。如果你之前已经配置过其他 MCP 连接器mcpServers下面会有多个 key你只需要在现有基础上增加一个新的 key 就行不要覆盖掉原有的配置。3.2 填入混元生图的 SSE 端点信息假设你从腾讯云控制台拿到的 SSE 端点 URL 是https://hunyuan.tencentcloudapi.com/mcp/sse?keysk-xxxxxxxxxxxxxxxx那么你的mcp.json应该这样写{ mcpServers: { hunyuan-image: { type: sse, url: https://hunyuan.tencentcloudapi.com/mcp/sse?keysk-xxxxxxxxxxxxxxxx, description: 腾讯混元生图 MCP 连接器 } } }这里我把连接器的名字取为hunyuan-image你可以取任何你喜欢的名字只要不跟已有的连接器重名就行。名字建议用英文小写加连字符避免空格和特殊字符因为有些系统对 key 的格式有要求。注意URL 中的key参数值要替换成你自己的 API Key不要直接复制我这里的示例。另外URL 中如果包含特殊字符比如、?等在 JSON 字符串里不需要额外转义直接写就行。3.3 多个 MCP 连接器共存时的配置方式如果你之前已经配置过其他 MCP 连接器比如 Playwright MCP 或者 Chrome DevTools MCP你的mcp.json可能长这样{ mcpServers: { playwright: { type: stdio, command: npx, args: [-y, playwright/mcp] } } }现在要加入混元生图只需要在mcpServers下面增加一个 key{ mcpServers: { playwright: { type: stdio, command: npx, args: [-y, playwright/mcp] }, hunyuan-image: { type: sse, url: https://hunyuan.tencentcloudapi.com/mcp/sse?keysk-xxxxxxxxxxxxxxxx, description: 腾讯混元生图 MCP 连接器 } } }这样两个连接器就共存了WorkBuddy 启动时会同时加载它们。你可以在 WorkBuddy 的 MCP 管理界面看到所有已加载的连接器列表。3.4 保存文件并重启 WorkBuddy配置写完后保存mcp.json然后完全退出 WorkBuddy 再重新启动。注意是“完全退出”不是最小化到托盘。Windows 上可以在任务管理器里确认 WorkBuddy 进程是否还在macOS 上可以用CmdQ彻底退出。重启后打开 WorkBuddy 的 MCP 管理界面你应该能看到hunyuan-image这个连接器出现在列表里状态显示为“已连接”或者类似的绿色标识。如果显示“连接失败”或者红色标识说明配置有问题需要排查。实操心得我第一次配置的时候忘了完全退出 WorkBuddy只是关掉了窗口结果重启后新连接器一直没加载出来。后来在任务管理器里发现 WorkBuddy 还在后台跑着彻底杀掉进程再启动就好了。这个坑很隐蔽因为大多数软件关掉窗口就等于退出了但 WorkBuddy 默认是最小化到托盘。4. 验证连接器是否生效并实际生图4.1 在 WorkBuddy 里检查 MCP 连接状态重启 WorkBuddy 后找到 MCP 管理界面。不同版本的 WorkBuddy 入口位置可能不同一般在设置或者侧边栏的“扩展”或“连接器”菜单里。进入后你应该能看到所有已配置的 MCP 连接器列表每个连接器会显示名称、类型、状态等信息。如果hunyuan-image的状态是“已连接”说明 WorkBuddy 成功跟混元生图服务建立了 SSE 连接。如果状态是“连接失败”可以点击查看详细错误信息。常见的错误包括Connection refusedURL 写错了或者网络不通。401 UnauthorizedAPI Key 无效或者过期。Timeout网络太慢或者服务端响应超时。4.2 用自然语言触发一次生图请求连接器状态正常后你就可以在 WorkBuddy 的对话窗口里直接让它生图了。比如输入帮我生成一张图片内容是一只橘猫坐在窗台上看夕阳风格偏水彩。WorkBuddy 会识别到这是一个生图请求然后调用hunyuan-image连接器。你会在对话里看到它调用了哪个工具、传了什么参数然后等待几秒钟图片就会以链接或者直接预览的形式返回。这里有个细节WorkBuddy 怎么知道该调用混元生图而不是其他连接器答案是它在理解你的意图后会根据连接器的描述和工具列表来匹配。所以你在description字段里写清楚“腾讯混元生图服务”是有意义的它会影响 WorkBuddy 的匹配准确率。4.3 生图参数怎么传混元生图 MCP 通常支持一些参数比如图片尺寸、生成数量、风格等。你可以在对话里直接指定比如生成一张 1024x1024 的图片内容是赛博朋克风格的城市夜景要 2 张。WorkBuddy 会把这些参数解析出来转换成 MCP 工具调用时需要的格式。如果某个参数它没识别出来你可以手动在对话里补充说明。实测下来尺寸和数量这两个参数识别率最高风格描述有时候需要多试几次。注意生图服务通常是按次计费的调试的时候不要一次性生成太多张。我一般先设成 1 张确认效果和参数都对了再批量生成。4.4 查看生图结果和日志图片生成后WorkBuddy 会在对话里展示结果。如果图片没有正常显示可以检查几个地方一是 MCP 连接器的日志看看请求是否成功发出、服务端是否返回了结果二是网络连接SSE 是长连接如果网络不稳定可能会导致连接中断。WorkBuddy 的日志文件通常在.workbuddy/logs目录下你可以用文本编辑器打开最新的日志文件搜索hunyuan-image关键字看看有没有报错信息。5. 常见问题排查与避坑指南5.1 连接器显示已连接但生图没反应这种情况我遇到过几次最常见的原因是 SSE 连接虽然建立了但实际请求发过去之后服务端没有正确响应。排查步骤是这样的首先确认 API Key 是否有余额或者权限。有些云服务开通后需要手动领取免费额度或者充值才能调用控制台上看着是开通状态实际调用时返回 403。其次检查 URL 是否完整。SSE 端点的 URL 有时候比较长复制的时候容易漏掉末尾的参数。你可以把 URL 复制到浏览器里直接访问看看返回什么内容。如果返回一个 JSON 格式的错误信息说明 URL 本身是通的问题出在鉴权或者参数上。最后看看 WorkBuddy 的版本是否支持 SSE 类型的 MCP。有些旧版本只支持 stdio 类型SSE 配置写了也不会生效。5.2 SSE 连接频繁断开怎么处理SSE 是长连接理论上可以保持很久但实际使用中可能会因为网络波动、服务端超时等原因断开。如果你发现连接器状态频繁变成“已断开”可以尝试以下几个方法检查网络环境尽量用稳定的有线网络而不是公共 Wi-Fi。在mcp.json里增加心跳配置如果 WorkBuddy 支持的话比如heartbeatInterval: 30000表示每 30 秒发一次心跳包。如果服务端有连接数限制确认没有其他程序在同时使用同一个 API Key。实操心得我在公司网络下用的时候SSE 连接经常过几分钟就断后来发现是公司防火墙对长连接有超时限制。换成手机热点测试就正常了。如果你也遇到类似情况可以先换个网络环境试试排除网络因素。5.3 mcp.json 格式错误导致 WorkBuddy 启动异常JSON 格式对语法要求很严格多一个逗号、少一个引号都会导致解析失败。如果你改完mcp.json后 WorkBuddy 启动报错或者 MCP 列表为空大概率是 JSON 格式有问题。我建议用 VS Code 或者任何支持 JSON 语法检查的编辑器来编辑mcp.json它会实时提示语法错误。另外JSON 不支持注释不要在里面写//或者/* */否则会解析失败。一个快速检查 JSON 是否合法的方法是用 Python 命令行python -m json.tool mcp.json如果输出格式化后的 JSON 内容说明格式没问题如果报错根据错误提示定位问题行。5.4 多个连接器名字冲突怎么办mcpServers下面的 key 必须是唯一的。如果你复制粘贴配置的时候忘了改名字两个连接器用了同一个 key后面的会覆盖前面的。WorkBuddy 启动时可能不会报错但你会发现其中一个连接器莫名其妙消失了。解决办法很简单给每个连接器取一个有意义且不重复的名字。我一般用“服务名-功能”的格式比如hunyuan-image、playwright-browser、mysql-local这样一看就知道是什么。5.5 常见问题速查表问题现象可能原因解决方法连接器列表里没有新配置WorkBuddy 没有完全退出重启在任务管理器里结束进程后重新启动状态显示连接失败URL 或 API Key 错误检查 URL 是否完整、Key 是否有效生图请求无响应API Key 余额不足或权限不够登录云控制台检查余额和权限SSE 连接频繁断开网络不稳定或防火墙限制更换网络环境或增加心跳配置WorkBuddy 启动报错mcp.json 格式错误用 JSON 校验工具检查语法多个连接器互相覆盖key 名字重复给每个连接器取唯一的名字6. 进阶玩法把 MCP 连接器用出花来6.1 结合 WorkBuddy Skill 实现自动化生图WorkBuddy 有一个 Skill 机制你可以把常用的操作流程固化成一个 Skill。比如我定义了一个“文章配图”Skill流程是读取当前文档的标题和摘要自动生成一段生图提示词调用混元生图连接器生成图片然后把图片插入到文档的指定位置。这个 Skill 配置好之后我写完文章只需要点一下“生成配图”剩下的全自动完成。对于经常写长文的人来说这个效率提升非常明显。6.2 用 MCP 连接器串联多个服务MCP 的威力在于它可以串联多个服务。比如你可以配置一个流程先用混元生图生成图片然后把图片上传到对象存储最后把图片链接插入到文档里。这三个步骤分别对应三个 MCP 连接器WorkBuddy 可以自动编排它们的调用顺序。当然这需要你对每个连接器的工具定义比较熟悉知道哪个工具接受什么参数、返回什么结果。建议先从单个连接器用起熟悉了之后再尝试串联。6.3 监控 MCP 连接器的调用情况如果你用混元生图比较频繁建议定期查看调用日志和费用情况。腾讯云控制台一般有调用统计和费用明细你可以看到每天调用了多少次、消耗了多少额度。WorkBuddy 这边的日志也可以配合着看确认每次调用是否都成功返回了结果。实操心得我一般会在月初设置一个费用预警比如当月费用超过 50 元就发通知。这样即使某天调用量突然暴涨也能及时发现避免月底账单吓一跳。6.4 后续可以扩展的方向混元生图只是 MCP 连接器的一个例子。同样的方法可以用来接入任何提供 MCP 端点的服务比如语音合成、视频生成、数据查询等。你只需要把mcp.json里的type和url换成对应服务的配置就行。另外如果你有开发能力也可以自己写一个 MCP 服务端把公司内部的 API 包装成 MCP 协议然后通过 SSE 或者 stdio 方式接入 WorkBuddy。这样 WorkBuddy 就能直接调用你内部的业务系统了想象空间很大。我在实际使用中最大的体会是MCP 这套机制把“AI 助手”和“外部工具”解耦了。以前每接一个新工具都要改 WorkBuddy 的代码或者等官方更新现在只需要改一个配置文件。这种设计思路值得很多做 AI 应用的团队借鉴。