1. 为什么要在 WorkBuddy 里接入自定义 MCP 连接器WorkBuddy 这类 AI 工作台用久了你会发现一个很现实的问题内置能力再强也覆盖不了所有场景。比如我想让它直接调用腾讯混元生图接口把一段文字描述变成图片内置工具里根本没有这个选项。这时候就得靠MCPModel Context Protocol来扩展。MCP 本质上是一套让 AI 助手和外部工具、数据源对话的协议。你可以把它理解成 AI 世界的“USB 接口标准”——只要对方按这个标准提供服务AI 就能即插即用。WorkBuddy 支持通过mcp.json配置文件接入自定义 MCP 连接器这意味着我们可以把任何符合 MCP 协议的服务挂载进来让 WorkBuddy 直接调用。这次我选的是腾讯混元生图的 SSE 云托管服务作为案例。为什么选它一是生图需求高频且直观效果好不好一眼就能看出来二是 SSEServer-Sent Events这种传输方式在 MCP 里很典型搞懂一个其他基于 SSE 的 MCP 服务基本都能照葫芦画瓢。SSE 说白了就是服务器单向、持续地往客户端推消息适合流式返回结果的场景比如生图这种需要等待、可能分片返回的任务。这篇文章适合三类人刚接触 WorkBuddy 想扩展能力的新手、手里有现成 MCP 服务想接进来的开发者、以及想搞清楚mcp.json到底怎么配的折腾党。我会从配置文件的字段含义讲起到实际调用验证再到踩过的坑尽量把每一步都说透。2. 接入前的准备工作与核心概念梳理2.1 先搞清楚 MCP 连接器的三种传输方式在动手之前必须弄明白 MCP 连接器的传输方式因为mcp.json里最关键的字段就是transport。目前主流的有三种stdio通过标准输入输出通信通常用于本地进程。AI 助手启动一个子进程双方通过管道收发消息。优点是简单直接缺点是只能本地用。SSE基于 HTTP 的 Server-Sent Events服务端主动推送。适合云托管服务因为不需要本地起进程只要有 URL 就能连。WebSocket全双工通信适合需要双向实时交互的场景。这次用的腾讯混元生图是云托管服务官方提供的是 SSE 端点所以transport字段要填sse。这里有个容易混淆的点SSE 是单向的服务端到客户端但 MCP 协议在 SSE 之上做了封装客户端发请求走的是普通 HTTP POST服务端返回走 SSE 流。所以你在配置里看到的还是一个 URL但底层是两种通道配合。提示如果你手里的 MCP 服务同时提供 SSE 和 WebSocket 两种端点优先选 SSE。SSE 在云托管环境里更稳定断线重连逻辑也更简单。2.2 拿到腾讯混元生图的服务端点和鉴权信息腾讯混元生图的 MCP 服务通常由云托管平台提供你需要拿到两样东西服务端点 URL和鉴权 Token。端点 URL 一般长这样https://api.example.com/mcp/hunyuan-image/sseToken 通常是一串 JWT放在请求头里做鉴权。有些平台会把 Token 直接拼在 URL 的 query 参数里比如?tokeneyJhbGci...。两种方式 MCP 客户端都支持但推荐放在请求头里因为 URL 容易被日志记录安全性差一些。我实际拿到的配置信息是这样的敏感部分已脱敏配置项值说明端点 URLhttps://mcp.example.com/hunyuan/sseSSE 连接地址鉴权方式Bearer Token放在 Authorization 头TokeneyJhbGciOiJIUzI1NiIs...JWT 格式有有效期工具名hunyuan_text_to_image调用时用的工具标识注意Token 一般有有效期过期后会返回 401。如果你发现之前能用的连接突然失效先检查 Token 是不是过期了别急着怀疑配置写错了。2.3 WorkBuddy 的配置文件放在哪WorkBuddy 读取 MCP 配置的位置通常在用户配置目录下文件名就是mcp.json。不同系统路径不一样WindowsC:\Users\你的用户名\.workbuddy\mcp.jsonmacOS/Users/你的用户名/.workbuddy/mcp.jsonLinux/home/你的用户名/.workbuddy/mcp.json如果你找不到这个文件可以在 WorkBuddy 的设置里搜“MCP”或“连接器”一般会有“打开配置文件”的入口。有些版本支持在设置界面直接编辑但我觉得直接改文件更灵活尤其是要配多个连接器的时候。3. 手把手配置 mcp.json 接入混元生图3.1 mcp.json 的完整结构拆解先看一个最小可用的配置长什么样{ mcpServers: { hunyuan-image: { transport: sse, url: https://mcp.example.com/hunyuan/sse, headers: { Authorization: Bearer eyJhbGciOiJIUzI1NiIs... } } } }逐字段解释mcpServers顶层对象里面每个 key 是一个连接器的名字随便起但建议用有意义的名字比如hunyuan-image。transport传输方式这里填sse。urlSSE 端点地址。headers请求头鉴权 Token 放这里。有些平台的 Token 是拼在 URL 里的那就不需要headers直接写完整 URL 即可。但如果你同时要传其他自定义头还是用headers更清晰。3.2 加上超时和重连参数默认配置能跑但实际用起来会遇到两个问题一是生图耗时长默认超时可能不够二是网络抖动导致 SSE 断流。所以建议加上超时和重连相关参数{ mcpServers: { hunyuan-image: { transport: sse, url: https://mcp.example.com/hunyuan/sse, headers: { Authorization: Bearer eyJhbGciOiJIUzI1NiIs... }, timeout: 120000, reconnect: { enabled: true, maxRetries: 3, delayMs: 2000 } } } }timeout单位是毫秒这里设 120 秒因为生图有时候要等几十秒。reconnect里的maxRetries是最大重试次数delayMs是每次重试间隔。这几个参数不是所有版本都支持如果你的 WorkBuddy 报“未知字段”就把reconnect去掉只留timeout。实操心得我一开始没设 timeout结果生图任务跑到 60 秒就被掐断了返回一个“stream disconnected before completion: idle timeout waiting for sse”的错误。后来把 timeout 调到 120 秒就稳了。这个报错信息很典型看到 idle timeout 基本就是超时太短。3.3 配置多个连接器时的注意事项如果你不止接一个 MCP 服务mcpServers里可以放多个{ mcpServers: { hunyuan-image: { transport: sse, url: https://mcp.example.com/hunyuan/sse, headers: { Authorization: Bearer token1 } }, another-tool: { transport: stdio, command: node, args: [/path/to/server.js] } } }注意每个连接器的名字不能重复否则后面的会覆盖前面的。另外SSE 和 stdio 可以混用WorkBuddy 会分别处理。但如果你同时配了太多 SSE 连接器启动时可能会因为并发连接数限制导致部分连接失败建议按需启用。4. 验证连接与调用生图工具4.1 重启 WorkBuddy 并检查连接状态改完mcp.json后必须重启 WorkBuddy因为它只在启动时读取配置。重启后在对话界面输入类似“列出可用的 MCP 工具”的指令如果配置正确应该能看到hunyuan_text_to_image出现在工具列表里。如果没看到先检查三件事配置文件路径对不对、JSON 格式有没有语法错误比如多了个逗号、Token 有没有过期。JSON 语法错误是最常见的建议用编辑器的 JSON 校验功能过一遍。4.2 实际调用生图工具连接成功后直接对 WorkBuddy 说“用混元生图画一只在雨中打伞的猫”。WorkBuddy 会自动识别并调用hunyuan_text_to_image工具把描述作为参数传过去。调用过程中你会在界面上看到 SSE 流式返回的进度。生图任务通常分几个阶段接收请求、排队、生成中、返回图片 URL。如果一切顺利几十秒后就能看到图片。这里有个细节混元生图返回的可能是图片的临时 URL而不是直接返回图片二进制。WorkBuddy 拿到 URL 后会展示出来你可以点开查看或下载。如果 URL 有有效期记得及时保存。4.3 参数调优让生图效果更符合预期混元生图工具通常支持一些可选参数比如图片尺寸、生成数量、风格等。你可以在调用时明确指定比如“用混元生图生成一张 1024x1024 的赛博朋克风格城市夜景要 2 张”。如果 WorkBuddy 没有自动传这些参数你可以在mcp.json里给连接器加默认参数如果版本支持{ hunyuan-image: { transport: sse, url: https://mcp.example.com/hunyuan/sse, headers: { Authorization: Bearer token }, defaultParams: { size: 1024x1024, style: cyberpunk } } }这样每次调用都会带上这些默认值省得每次都说一遍。不过defaultParams不是标准字段能不能用取决于 WorkBuddy 版本实测不行就还是每次手动指定。5. 常见问题与排查技巧实录5.1 连接失败类问题速查现象可能原因解决方法工具列表里没有混元生图配置文件路径错误或 JSON 语法错误检查路径用 JSON 校验工具验证返回 401 UnauthorizedToken 过期或格式错误重新获取 Token确认 Bearer 前缀返回 404 Not FoundURL 写错或端点已下线核对官方文档的端点地址连接超时网络不通或端点不可达用 curl 测试端点连通性idle timeout waiting for sse超时设置太短把 timeout 调到 120000 以上5.2 SSE 断流问题的排查思路SSE 断流是最烦人的因为有时候能跑通有时候跑到一半就断了。我的排查顺序是先看是不是超时太短。生图任务如果超过 60 秒默认超时很容易触发断流。再看网络稳定性。如果你在公司网络里可能有代理或防火墙干扰长连接。换个网络试试。检查服务端是否有并发限制。有些云托管服务对同一 Token 的并发连接数有限制同时开多个任务会互相挤掉。最后看 WorkBuddy 版本。老版本对 SSE 重连支持不好升级到最新版通常能解决。踩坑记录我有一次怎么都连不上折腾了半天发现是 Token 里有个换行符复制的时候带进去了。这种问题最隐蔽建议把 Token 单独存到一个文本文件里用的时候再复制避免带入不可见字符。5.3 生图结果不符合预期的处理有时候图是生成了但效果不对比如风格跑偏、尺寸不对。这时候先确认参数有没有正确传递。可以在 WorkBuddy 的日志里看实际发出的请求参数对比你期望的是否一致。如果参数没问题但效果就是不好那可能是提示词的问题。混元生图对中文提示词的理解还不错但太抽象的描述效果会打折扣。建议把描述写具体比如“一只橘猫坐在窗台上外面下着雨水彩风格”就比“画个猫”好得多。6. 把配置经验迁移到其他 MCP 服务搞懂混元生图这个案例后其他 SSE 类型的 MCP 服务基本都能套用。核心就三步拿到端点 URL 和 Token、在mcp.json里配好transport和headers、重启验证。区别主要在于工具名和参数不同。比如你接一个天气查询的 MCP 服务工具名可能是get_weather参数是城市名。接一个数据库查询的 MCP 服务工具名可能是query_database参数是 SQL 语句。配置结构完全一样只是url和headers换一下。如果你接的是 stdio 类型的本地 MCP 服务把transport改成stdio去掉url和headers换成command和args即可。比如{ local-tool: { transport: stdio, command: python, args: [/path/to/mcp_server.py] } }这种本地服务的好处是不依赖网络响应快缺点是只能在本机用换台电脑就得重新配。我个人在实际操作中的体会是MCP 配置这件事难点不在写 JSON而在于搞清楚服务端的鉴权方式和传输协议。只要这两点弄明白了剩下的就是填空。另外强烈建议把每次成功的配置存一份备份因为 Token 会过期服务端点也可能变有个备份能省不少事。最后再分享一个小技巧如果你不确定某个 MCP 服务支持哪些工具连上之后直接问 WorkBuddy“这个连接器有哪些可用工具”它会列出来比翻文档快。
WorkBuddy接入自定义MCP连接器：SSE配置与混元生图实战
1. 为什么要在 WorkBuddy 里接入自定义 MCP 连接器WorkBuddy 这类 AI 工作台用久了你会发现一个很现实的问题内置能力再强也覆盖不了所有场景。比如我想让它直接调用腾讯混元生图接口把一段文字描述变成图片内置工具里根本没有这个选项。这时候就得靠MCPModel Context Protocol来扩展。MCP 本质上是一套让 AI 助手和外部工具、数据源对话的协议。你可以把它理解成 AI 世界的“USB 接口标准”——只要对方按这个标准提供服务AI 就能即插即用。WorkBuddy 支持通过mcp.json配置文件接入自定义 MCP 连接器这意味着我们可以把任何符合 MCP 协议的服务挂载进来让 WorkBuddy 直接调用。这次我选的是腾讯混元生图的 SSE 云托管服务作为案例。为什么选它一是生图需求高频且直观效果好不好一眼就能看出来二是 SSEServer-Sent Events这种传输方式在 MCP 里很典型搞懂一个其他基于 SSE 的 MCP 服务基本都能照葫芦画瓢。SSE 说白了就是服务器单向、持续地往客户端推消息适合流式返回结果的场景比如生图这种需要等待、可能分片返回的任务。这篇文章适合三类人刚接触 WorkBuddy 想扩展能力的新手、手里有现成 MCP 服务想接进来的开发者、以及想搞清楚mcp.json到底怎么配的折腾党。我会从配置文件的字段含义讲起到实际调用验证再到踩过的坑尽量把每一步都说透。2. 接入前的准备工作与核心概念梳理2.1 先搞清楚 MCP 连接器的三种传输方式在动手之前必须弄明白 MCP 连接器的传输方式因为mcp.json里最关键的字段就是transport。目前主流的有三种stdio通过标准输入输出通信通常用于本地进程。AI 助手启动一个子进程双方通过管道收发消息。优点是简单直接缺点是只能本地用。SSE基于 HTTP 的 Server-Sent Events服务端主动推送。适合云托管服务因为不需要本地起进程只要有 URL 就能连。WebSocket全双工通信适合需要双向实时交互的场景。这次用的腾讯混元生图是云托管服务官方提供的是 SSE 端点所以transport字段要填sse。这里有个容易混淆的点SSE 是单向的服务端到客户端但 MCP 协议在 SSE 之上做了封装客户端发请求走的是普通 HTTP POST服务端返回走 SSE 流。所以你在配置里看到的还是一个 URL但底层是两种通道配合。提示如果你手里的 MCP 服务同时提供 SSE 和 WebSocket 两种端点优先选 SSE。SSE 在云托管环境里更稳定断线重连逻辑也更简单。2.2 拿到腾讯混元生图的服务端点和鉴权信息腾讯混元生图的 MCP 服务通常由云托管平台提供你需要拿到两样东西服务端点 URL和鉴权 Token。端点 URL 一般长这样https://api.example.com/mcp/hunyuan-image/sseToken 通常是一串 JWT放在请求头里做鉴权。有些平台会把 Token 直接拼在 URL 的 query 参数里比如?tokeneyJhbGci...。两种方式 MCP 客户端都支持但推荐放在请求头里因为 URL 容易被日志记录安全性差一些。我实际拿到的配置信息是这样的敏感部分已脱敏配置项值说明端点 URLhttps://mcp.example.com/hunyuan/sseSSE 连接地址鉴权方式Bearer Token放在 Authorization 头TokeneyJhbGciOiJIUzI1NiIs...JWT 格式有有效期工具名hunyuan_text_to_image调用时用的工具标识注意Token 一般有有效期过期后会返回 401。如果你发现之前能用的连接突然失效先检查 Token 是不是过期了别急着怀疑配置写错了。2.3 WorkBuddy 的配置文件放在哪WorkBuddy 读取 MCP 配置的位置通常在用户配置目录下文件名就是mcp.json。不同系统路径不一样WindowsC:\Users\你的用户名\.workbuddy\mcp.jsonmacOS/Users/你的用户名/.workbuddy/mcp.jsonLinux/home/你的用户名/.workbuddy/mcp.json如果你找不到这个文件可以在 WorkBuddy 的设置里搜“MCP”或“连接器”一般会有“打开配置文件”的入口。有些版本支持在设置界面直接编辑但我觉得直接改文件更灵活尤其是要配多个连接器的时候。3. 手把手配置 mcp.json 接入混元生图3.1 mcp.json 的完整结构拆解先看一个最小可用的配置长什么样{ mcpServers: { hunyuan-image: { transport: sse, url: https://mcp.example.com/hunyuan/sse, headers: { Authorization: Bearer eyJhbGciOiJIUzI1NiIs... } } } }逐字段解释mcpServers顶层对象里面每个 key 是一个连接器的名字随便起但建议用有意义的名字比如hunyuan-image。transport传输方式这里填sse。urlSSE 端点地址。headers请求头鉴权 Token 放这里。有些平台的 Token 是拼在 URL 里的那就不需要headers直接写完整 URL 即可。但如果你同时要传其他自定义头还是用headers更清晰。3.2 加上超时和重连参数默认配置能跑但实际用起来会遇到两个问题一是生图耗时长默认超时可能不够二是网络抖动导致 SSE 断流。所以建议加上超时和重连相关参数{ mcpServers: { hunyuan-image: { transport: sse, url: https://mcp.example.com/hunyuan/sse, headers: { Authorization: Bearer eyJhbGciOiJIUzI1NiIs... }, timeout: 120000, reconnect: { enabled: true, maxRetries: 3, delayMs: 2000 } } } }timeout单位是毫秒这里设 120 秒因为生图有时候要等几十秒。reconnect里的maxRetries是最大重试次数delayMs是每次重试间隔。这几个参数不是所有版本都支持如果你的 WorkBuddy 报“未知字段”就把reconnect去掉只留timeout。实操心得我一开始没设 timeout结果生图任务跑到 60 秒就被掐断了返回一个“stream disconnected before completion: idle timeout waiting for sse”的错误。后来把 timeout 调到 120 秒就稳了。这个报错信息很典型看到 idle timeout 基本就是超时太短。3.3 配置多个连接器时的注意事项如果你不止接一个 MCP 服务mcpServers里可以放多个{ mcpServers: { hunyuan-image: { transport: sse, url: https://mcp.example.com/hunyuan/sse, headers: { Authorization: Bearer token1 } }, another-tool: { transport: stdio, command: node, args: [/path/to/server.js] } } }注意每个连接器的名字不能重复否则后面的会覆盖前面的。另外SSE 和 stdio 可以混用WorkBuddy 会分别处理。但如果你同时配了太多 SSE 连接器启动时可能会因为并发连接数限制导致部分连接失败建议按需启用。4. 验证连接与调用生图工具4.1 重启 WorkBuddy 并检查连接状态改完mcp.json后必须重启 WorkBuddy因为它只在启动时读取配置。重启后在对话界面输入类似“列出可用的 MCP 工具”的指令如果配置正确应该能看到hunyuan_text_to_image出现在工具列表里。如果没看到先检查三件事配置文件路径对不对、JSON 格式有没有语法错误比如多了个逗号、Token 有没有过期。JSON 语法错误是最常见的建议用编辑器的 JSON 校验功能过一遍。4.2 实际调用生图工具连接成功后直接对 WorkBuddy 说“用混元生图画一只在雨中打伞的猫”。WorkBuddy 会自动识别并调用hunyuan_text_to_image工具把描述作为参数传过去。调用过程中你会在界面上看到 SSE 流式返回的进度。生图任务通常分几个阶段接收请求、排队、生成中、返回图片 URL。如果一切顺利几十秒后就能看到图片。这里有个细节混元生图返回的可能是图片的临时 URL而不是直接返回图片二进制。WorkBuddy 拿到 URL 后会展示出来你可以点开查看或下载。如果 URL 有有效期记得及时保存。4.3 参数调优让生图效果更符合预期混元生图工具通常支持一些可选参数比如图片尺寸、生成数量、风格等。你可以在调用时明确指定比如“用混元生图生成一张 1024x1024 的赛博朋克风格城市夜景要 2 张”。如果 WorkBuddy 没有自动传这些参数你可以在mcp.json里给连接器加默认参数如果版本支持{ hunyuan-image: { transport: sse, url: https://mcp.example.com/hunyuan/sse, headers: { Authorization: Bearer token }, defaultParams: { size: 1024x1024, style: cyberpunk } } }这样每次调用都会带上这些默认值省得每次都说一遍。不过defaultParams不是标准字段能不能用取决于 WorkBuddy 版本实测不行就还是每次手动指定。5. 常见问题与排查技巧实录5.1 连接失败类问题速查现象可能原因解决方法工具列表里没有混元生图配置文件路径错误或 JSON 语法错误检查路径用 JSON 校验工具验证返回 401 UnauthorizedToken 过期或格式错误重新获取 Token确认 Bearer 前缀返回 404 Not FoundURL 写错或端点已下线核对官方文档的端点地址连接超时网络不通或端点不可达用 curl 测试端点连通性idle timeout waiting for sse超时设置太短把 timeout 调到 120000 以上5.2 SSE 断流问题的排查思路SSE 断流是最烦人的因为有时候能跑通有时候跑到一半就断了。我的排查顺序是先看是不是超时太短。生图任务如果超过 60 秒默认超时很容易触发断流。再看网络稳定性。如果你在公司网络里可能有代理或防火墙干扰长连接。换个网络试试。检查服务端是否有并发限制。有些云托管服务对同一 Token 的并发连接数有限制同时开多个任务会互相挤掉。最后看 WorkBuddy 版本。老版本对 SSE 重连支持不好升级到最新版通常能解决。踩坑记录我有一次怎么都连不上折腾了半天发现是 Token 里有个换行符复制的时候带进去了。这种问题最隐蔽建议把 Token 单独存到一个文本文件里用的时候再复制避免带入不可见字符。5.3 生图结果不符合预期的处理有时候图是生成了但效果不对比如风格跑偏、尺寸不对。这时候先确认参数有没有正确传递。可以在 WorkBuddy 的日志里看实际发出的请求参数对比你期望的是否一致。如果参数没问题但效果就是不好那可能是提示词的问题。混元生图对中文提示词的理解还不错但太抽象的描述效果会打折扣。建议把描述写具体比如“一只橘猫坐在窗台上外面下着雨水彩风格”就比“画个猫”好得多。6. 把配置经验迁移到其他 MCP 服务搞懂混元生图这个案例后其他 SSE 类型的 MCP 服务基本都能套用。核心就三步拿到端点 URL 和 Token、在mcp.json里配好transport和headers、重启验证。区别主要在于工具名和参数不同。比如你接一个天气查询的 MCP 服务工具名可能是get_weather参数是城市名。接一个数据库查询的 MCP 服务工具名可能是query_database参数是 SQL 语句。配置结构完全一样只是url和headers换一下。如果你接的是 stdio 类型的本地 MCP 服务把transport改成stdio去掉url和headers换成command和args即可。比如{ local-tool: { transport: stdio, command: python, args: [/path/to/mcp_server.py] } }这种本地服务的好处是不依赖网络响应快缺点是只能在本机用换台电脑就得重新配。我个人在实际操作中的体会是MCP 配置这件事难点不在写 JSON而在于搞清楚服务端的鉴权方式和传输协议。只要这两点弄明白了剩下的就是填空。另外强烈建议把每次成功的配置存一份备份因为 Token 会过期服务端点也可能变有个备份能省不少事。最后再分享一个小技巧如果你不确定某个 MCP 服务支持哪些工具连上之后直接问 WorkBuddy“这个连接器有哪些可用工具”它会列出来比翻文档快。
