企业官网建设流程全解析

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

WorkBuddy 这类 AI 工作台用久了，你会发现一个很现实的问题：内置能力再强，也覆盖不了你手头那些“私有工具链”。比如我最近想把「腾讯混元生图」直接挂进 WorkBuddy，让我在对话里说一句“帮我生成一张赛博朋克风格的产品主图”，它就能调云端模型出图，而不是我复制提示词、切浏览器、下载、再拖回项目目录。这个链路要打通，靠的就是MCP（Model Context Protocol）连接器。

MCP 是软件协议层面的东西，不是硬件协议，你可以把它理解成“AI 应用和外部工具之间的 USB-C 接口”：WorkBuddy 是主机，MCP Server 是外设，双方约定好 JSON-RPC 格式的消息，就能互相调用。而SSE（Server-Sent Events）是其中一种传输方式，服务端通过一条长连接持续把事件推给客户端，特别适合“云托管”这种你不想本地起进程、又需要流式返回结果的场景。腾讯混元生图官方提供的云托管 MCP 服务，走的就是 SSE。

这篇内容适合三类人：一是刚装好 WorkBuddy、想扩展能力但不知道mcp.json怎么写的新手；二是已经用过内置 MCP、想接自己公司内部服务的开发者；三是被 SSE 长连接、鉴权头、超时这些问题卡住过的老手。我会以「腾讯混元生图 SSE 云托管」为完整案例，把配置、鉴权、调试、排错一条龙讲透，你照着抄就能跑通。

2. 先把 MCP 和 SSE 这两个概念掰开揉碎

2.1 MCP 到底解决了什么问题

在没有 MCP 之前，每接一个外部能力，WorkBuddy 这类工具就得为它单独写一套适配代码：调 A 服务用一套参数，调 B 服务换一套鉴权，调 C 服务又是另一种返回格式。工具越多，适配层越臃肿，最后变成一坨谁都不敢动的祖传代码。

MCP 的思路是把“能力”抽象成标准化的Tools（工具）、Resources（资源）、Prompts（提示模板）三类原语。外部服务只要按协议暴露这些原语，任何支持 MCP 的客户端都能即插即用。对 WorkBuddy 来说，它不需要知道“混元生图”内部怎么实现，只需要知道“这个 Server 暴露了一个叫text_to_image的工具，入参是 prompt 和 size”，剩下的交给协议。

这里有个容易混淆的点：MCP 本身是协议规范，不是某个具体软件。你可以用 Python、TypeScript、Java 写 MCP Server，也可以用 SSE、stdio、Streamable HTTP 等不同传输方式承载它。协议和传输是两层，别混为一谈。

2.2 SSE 传输为什么适合云托管场景

MCP 常见的传输方式有三种，我做了个对比，你按场景选：

腾讯混元生图选 SSE，核心原因是生图是耗时任务：一次出图可能几秒到几十秒，服务端需要把“任务已接收”“正在生成”“生成完成”“返回图片 URL”这些中间状态持续推给客户端。如果用普通 HTTP 请求-响应，客户端要么傻等，要么反复轮询，体验都差。SSE 天然就是“服务端持续说话”的模型，正好对上。

注意：SSE 是单向的，服务端到客户端。客户端要发指令（比如“开始生图”），得另开一个普通 HTTP POST 请求。所以完整的 SSE MCP 交互是“POST 发指令 + SSE 收结果”两条通道配合，不是一条连接包打天下。

2.3 WorkBuddy 里 MCP 的加载机制

WorkBuddy 启动时会读取配置文件里的 MCP Server 列表，逐个尝试建立连接、拉取工具清单（tools/list），然后把这些工具注册进当前会话的可用能力池。配置文件通常是mcp.json，放在用户配置目录或项目根目录下。它长这样（先看结构，具体字段后面细讲）：

{ "mcpServers": { "hunyuan-image": { "type": "sse", "url": "https://your-mcp-endpoint/sse", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

关键点：mcpServers是固定顶层键，里面每个子对象是一个 Server，键名（如hunyuan-image）是你自己起的别名，会显示在 WorkBuddy 的工具列表里。type决定用哪种传输，SSE 场景就填sse。

3. 接入前的准备工作：账号、密钥与环境

3.1 拿到混元生图的 MCP 服务地址和凭证

腾讯混元生图的云托管 MCP 服务，你需要先在对应平台开通服务、创建应用，拿到两样东西：SSE 端点 URL和访问凭证（Token 或 API Key）。端点 URL 一般形如https://xxx.tencentcloudapi.com/mcp/sse或平台分配的专属域名，凭证通常是一串 Bearer Token。

这里有个坑我踩过：平台控制台里可能同时给你“API 密钥”和“MCP 接入凭证”两个东西，长得像但用途不同。MCP 连接器要的是后者，用错了会一直返回 401。判断方法很简单——看文档里这个凭证是不是配在Authorization头里、用于 MCP 端点鉴权，是就用它。

3.2 确认 WorkBuddy 版本支持自定义 MCP

不是所有版本的 WorkBuddy 都开放自定义 MCP 配置入口。你需要确认版本支持mcp.json手动编辑，或者设置界面里有“MCP 服务器”管理项。如果找不到入口，先升级到较新版本。国际版和国内版在配置目录路径上可能不同，这点后面排错章节会细说。

3.3 网络与证书的前置检查

SSE 是长连接，对网络中间层很敏感。接入前建议先做两件事：

1. 用curl直接测端点连通性，确认不是网络层被拦。
2. 确认你的环境能正常校验证书（企业内网有时会替换根证书，导致 TLS 握手失败）。

curl -N -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: text/event-stream" \ https://your-mcp-endpoint/sse

-N是关闭 curl 的缓冲，让你能实时看到 SSE 推送。如果这条命令能持续吐出event:和data:行，说明端点和凭证都没问题，可以进下一步。如果卡住不动或立刻断开，问题在网络或鉴权，先解决再配 WorkBuddy，否则你会分不清是配置错还是网络错。

4. 手把手写 mcp.json：字段逐个拆解

4.1 最小可用配置长什么样

先给你一份能跑的最小配置，再逐字段解释：

{ "mcpServers": { "hunyuan-image": { "type": "sse", "url": "https://your-mcp-endpoint/sse", "headers": { "Authorization": "Bearer YOUR_TOKEN" }, "timeout": 60000 } } }

把它保存到 WorkBuddy 的 MCP 配置路径下，重启或重载配置，工具列表里就应该出现混元生图相关的工具。

4.2 每个字段的含义与取值逻辑

type：传输类型。SSE 场景固定填sse。有些版本用transport作为键名，取决于 WorkBuddy 版本，以你本地文档为准。填错的表现是连接直接失败，日志里会提示不支持的传输类型。

url：SSE 端点完整地址，必须带协议头（https://）。注意不要漏掉路径末尾的/sse，很多平台把 SSE 端点和普通 API 端点分开，路径不同。

headers：附加到连接请求上的 HTTP 头。鉴权就靠这里。除了Authorization，有些平台还要求X-Api-Key或自定义头，按平台文档填。

timeout：连接和请求超时，单位毫秒。生图是长任务，这个值别设太小。我一般设 60000（60 秒）起步，出图慢的场景可以到 120000。设太小会出现“任务还没返回就被判定超时”的假故障。

disabled（可选）：设为true可临时禁用某个 Server，调试时很有用，不用删配置。

4.3 多 Server 共存时的命名与隔离

你不可能只接一个 MCP。多个 Server 共存时，键名（别名）要唯一且语义清晰，比如hunyuan-image、internal-search、db-query。别名会出现在工具名前缀里，起得乱会导致你在对话里分不清调的是哪个。

{ "mcpServers": { "hunyuan-image": { "type": "sse", "url": "...", "headers": {...} }, "internal-search": { "type": "sse", "url": "...", "headers": {...} } } }

提示：改完mcp.json后，WorkBuddy 不一定自动热重载。稳妥做法是重启应用，或在设置里手动点“重新加载 MCP”。我遇到过改了配置没生效、排查半天发现是没重载的情况。

5. 完整实操：从配置到第一次成功出图

5.1 第一步：定位并编辑配置文件

WorkBuddy 的 MCP 配置路径因平台而异。常见位置是用户配置目录下的mcp.json。如果你不确定，可以在设置界面找“打开配置文件”之类的入口，直接跳转。手动找的话，注意区分“全局配置”和“项目级配置”——全局的对所有项目生效，项目级的只对当前工作区生效。我建议先改全局的，跑通后再按项目隔离。

编辑时用支持 JSON 校验的编辑器，避免多一个逗号、少一个引号这种低级错误。JSON 不允许尾随逗号，这是新手最常见的翻车点。

5.2 第二步：填入混元生图 SSE 配置

把第 4 节的配置模板填上你的真实端点和 Token。填完先别急着开 WorkBuddy，用第 3.3 节的curl再验一次，确保配置里的 URL 和 Token 是能通的。这一步能帮你排除掉 80% 的“配置看起来对但就是连不上”的问题。

5.3 第三步：重载并验证工具注册

重启 WorkBuddy 后，打开工具或 MCP 面板，应该能看到hunyuan-image这个 Server 处于“已连接”状态，下面挂着它暴露的工具，通常包括文生图、图生图之类。如果显示“连接失败”，先看日志，日志里一般会写明是鉴权失败、超时还是协议错误。

5.4 第四步：发起一次真实生图请求

在对话里直接描述需求，比如“用混元生图生成一张 1024x1024 的极简风格咖啡杯产品图，白色背景”。WorkBuddy 会识别到可用工具，调用text_to_image，把参数通过 POST 发给服务端，然后通过 SSE 接收进度和结果。

一次成功的调用，日志里大致会经历这几个阶段：

1. 客户端 POST 提交生图任务，拿到任务 ID。
2. SSE 通道收到task_accepted事件。
3. 陆续收到progress事件（如果有）。
4. 收到completed事件，携带图片 URL 或 base64。
5. WorkBuddy 把结果渲染出来。

如果卡在第 2 步之后没动静，多半是 SSE 长连接被中间层掐了，看第 6 节。

5.5 参数怎么传：以生图工具为例

不同 MCP Server 暴露的工具参数名不一样，但生图类工具通常有这几个：

传参时别自己臆造参数名，以tools/list返回的 schema 为准。WorkBuddy 一般会按 schema 校验，传错会直接报参数错误。

6. 常见问题与排查技巧实录

6.1 连接建立失败：401、403、404 怎么区分

401 最常见的原因是 Token 复制时带了首尾空格，或者Bearer和 Token 之间少了空格。这种低级错误我见过太多次，排查时先看这个。

6.2 SSE 空闲超时：idle timeout 的成因与对策

stream disconnected before completion: idle timeout waiting for sse这个报错，本质是连接建立后一段时间没有数据流动，被中间层（负载均衡、反向代理、防火墙）判定为空闲连接给断了。生图任务如果前期准备时间长，就容易触发。

对策有三条：一是把客户端timeout调大；二是让服务端支持心跳事件（很多 MCP 服务会定期发ping或注释行保活）；三是缩短任务本身的等待，比如先提交任务再异步取结果。如果服务端不支持心跳，客户端能做的有限，这时候要和平台确认他们的 SSE 保活策略。

6.3 工具列表为空：连上了但没工具

连接显示成功，但工具列表是空的，通常是tools/list请求失败或返回空。可能原因：凭证只有连接权限没有工具调用权限；Server 端初始化还没完成；客户端解析响应出错。先看日志里tools/list的原始响应，再判断是权限问题还是解析问题。

6.4 配置改了不生效的几个隐藏原因

• 改错了配置文件（全局 vs 项目级）。
• JSON 语法错误导致整个文件被忽略。
• 应用没重载配置。
• 有多个同名 Server 定义，后者覆盖前者。

我建议每次改完配置，先做一次 JSON 语法校验，再重启应用，最后看日志确认加载的是哪个文件。这三步能省掉大量瞎猜时间。

7. 几个提升稳定性的实战心得

7.1 凭证不要硬编码在 mcp.json 里

把 Token 明文写进mcp.json，一旦这个文件被同步到云端或提交进版本库，就等于泄露。更好的做法是用环境变量引用，比如配置里写${HUNYUAN_TOKEN}，实际值放在系统环境变量或密钥管理里。WorkBuddy 是否支持变量插值取决于版本，支持的话强烈建议用。

7.2 给长任务留足超时，但别无限大

超时设太小会误杀正常任务，设太大又会让真正卡死的连接一直挂着。我的经验值是：普通工具 30 秒，生图这类重任务 90 到 120 秒。超过这个还没结果，基本可以判定有问题，让它超时反而能更快暴露故障。

7.3 用日志定位问题，而不是靠猜

WorkBuddy 的 MCP 日志通常会记录连接、请求、响应、错误。遇到问题先看日志，重点看三处：连接阶段有没有握手成功、请求阶段参数对不对、响应阶段有没有报错码。养成看日志的习惯，比反复改配置试错高效得多。

7.4 多环境配置分离

开发、测试、生产用不同的端点和凭证时，别在一个mcp.json里来回改。用项目级配置隔离，或者维护多份配置文件按需切换。这样能避免“本地测通了、上线用错凭证”的事故。

8. 后续还能怎么扩展这套连接器

跑通混元生图只是起点。同样的 SSE 接入套路，可以复用到任何提供云托管 MCP 的服务上：把url和headers一换，工具就接进来了。如果你想更进一步，可以在 WorkBuddy 里给这些工具定几条规则，比如“所有生图任务默认 1024x1024、默认加负向提示词”，让后续所有任务自动生效，省去每次重复描述。

我自己在实际操作中的体会是：MCP 接入的难点从来不在协议本身，而在鉴权细节、长连接稳定性和配置加载这几个“脏活”上。把这三块摸透，剩下的就是复制粘贴。踩过几次坑之后你会发现，一份写对的mcp.json加一次成功的curl验证，基本就能保证 90% 的接入一次成功。