WorkBuddy 怎么配 MCP？用户级与项目级怎么选，状态灯红了查哪三处
给 AI 工具接外部服务这件事，过去门槛主要卡在配置上：找到配置文件、按格式手写 JSON、猜哪个字段名写错了。WorkBuddy（Tencent WorkBuddy）在这一步上做了简化——官方文档明确写着，MCP 配置已经集成到界面中，无需编码、无需手动修改配置文件，可视化操作即可完成接入。
但”不用手写”不等于”不用理解”。真正要你做决定的地方有两处：这个能力配在哪一级，以及配完状态灯是红的该从哪儿查起。这两件事文档都给了原始信息，只是没告诉你怎么权衡。
一、MCP 是什么：官方的「USB 接口」比喻
MCP 的全称是 Model Context Protocol。官方给的比喻是AI 的「USB 接口」——这个比喻的重点不在”能插很多东西”，而在”接口标准统一，所以插上就能用”。
在 WorkBuddy 的体系里，MCP 不是孤立的一块。官方在《连接器》文档里说得很清楚，连接器是 WorkBuddy 与外部系统之间的桥梁，正是**基于标准化协议（如 MCP）**把外部服务能力引入 AI 工作流。区别在于，连接器是官方已经封装好的那几个（当前支持 QQ 邮箱、腾讯乐享、腾讯文档、TAPD、微云），点几下授权就通；而 MCP 是那条通用的口子——官方没做成连接器的服务，你自己接。
官方列的四项核心价值是这四条：
| 核心价值 | 含义 |
|---|---|
| 上下文共享 | 让 AI 拿到外部系统里的信息 |
| 工具调用 | 让 AI 能够调用外部服务的能力 |
| 可组合工作流 | 多个能力可以串起来使用 |
| 数据控制 | 支持本地或受控方式运行 |
这四条里最容易被略过的是数据控制。支持本地或受控方式运行，意味着接入的这个 Server 可以是跑在你自己机器上的进程，数据不必先绕一圈外部平台。如果你所在的团队对数据出不出本机有硬要求，这一条决定了 MCP 这条路走不走得通，值得在选型时先确认清楚你要接的那个 Server 属于哪一种。
二、两个配置级别：本篇最该搞清楚的一件事
配置界面里最先要你做的选择，就是把这份配置放在用户级还是项目级。官方给的对照是这样：
| 级别 | 适用场景 | 配置文件路径 |
|---|---|---|
| 用户级 | 配置一次，所有项目复用 | ~/.workbuddy/mcp.json |
| 项目级 | 仅当前项目生效，互不影响 | <项目目录>/.workbuddy/mcp.json |
官方给的选择原则是一句话：频繁跨项目使用的能力放用户级，仅特定项目需要的专属服务放项目级。
这句话本身没错，但按它去选，你只考虑了”方便不方便”。还有一个维度文档没展开，值得你自己补上：这个 Server 会往外做什么。
用户级配置一次全局生效，字面意思就是你后面开的所有项目都能用这个能力。对于查询类、只读类的 Server，这没什么问题——多一个项目能查，不会造成什么后果。但对于会往外发消息的 Server，情况不一样了。你在 A 项目里配了一个往部门群发通知的机器人，放在用户级，那么半年后你在 B 项目里随手说一句”通知一下”，它同样有能力把消息发出去。这条链路是通的，只是你当时没想到。
所以更实用的判据可以是两条叠加：
- 跨项目频率高 + 副作用可逆（查询、读取、检索） → 用户级，省事
- 只有这个项目要用，或者带外发、写入、下单这类不可撤回动作 → 项目级，哪怕你有三个项目都想用，也宁可配三次
多配两次的成本是几分钟，配错一次的成本是一条已经发出去的消息。这笔账不难算。
项目级还有一个附带好处：配置文件就落在项目目录里，你把项目交给同事、或者换台机器继续做的时候，配置是跟着走的（当然，里面的凭证不能跟着走，下一节说这件事）。
三、配置入口与官方示例
入口路径是：侧边栏「插件」→ 右上角「MCP 服务器」→「配置 MCP」。
官方给的示例是接入企业微信机器人，配置内容可以原样照抄：
{
"mcpServers": {
"wecom": {
"command": "uvx",
"args": ["wecom-bot-mcp-server"],
"env": { "WECOM_WEBHOOK_URL": "your-webhook-url" }
}
}
}
这段 JSON 虽然短，但结构值得看明白，因为几乎所有 MCP Server 的配置都是同一副骨架：
mcpServers下面的wecom是你给这个 Server 起的名字，用来在配置里区分不同 Server；command是用什么命令把这个 Server 跑起来，这里是uvx；args是传给这个命令的参数，这里是 Server 的包名wecom-bot-mcp-server；env是环境变量，凭证类信息放在这里，示例中WECOM_WEBHOOK_URL的值your-webhook-url是个占位符，需要你替换成真实地址。
WebHook 的获取方式官方也写了：企业微信群 →「添加群机器人」→ 获取 WebHook URL。
关于那个 WebHook URL
有一件事配置文档不会替你强调：WebHook URL 本身就是凭证。 它不是一个”地址”，它是一把钥匙——拿到这串地址的任何人，都能往这个群里发消息，中间没有第二道验证。
由此有两条纪律：
- 别把它提交进代码仓库。 项目级配置文件躺在项目目录里，跟着
git add .一起进版本库是很自然会发生的事。真要走这条路，先确认它在忽略规则里，或者把真实值留在用户级、项目级只放不带凭证的部分。 - 共享配置时先把值抹掉。 把配置发给同事参考时，保留
your-webhook-url这种占位符，让对方自己去群里取一份——他取的那份出问题也只影响他。
万一泄露了，处理方式是回到企业微信群里重新获取一个 WebHook URL，旧的作废。这件事越早做越省事。
四、配完之后怎么用：一句自然语言
MCP 接入完成后，用法上没有额外的开关要打——按官方说法，直接用自然语言描述需求即可，WorkBuddy 会自动调用对应的 MCP Server。
官方给的示例指令是这么一句：
请通过企业微信机器人通知：正式产品已发布，请 @xxxx 进行验收。
这句话里有个细节值得留意：它明确点了”通过企业微信机器人”。在只接了一个 Server 的时候，说不说都能通；但当你陆续接了三五个 Server 之后，把执行通道说清楚会让结果稳定得多。这和官方在《10 个上手技巧》里反复讲的那条是一个道理——别让 AI 猜你的意图，做什么、有什么、怎么样，一次说清。
官方列的适用场景是这四类：
| 场景 | 典型用法 |
|---|---|
| 发布通知 | 任务或流程完成后自动向群里同步 |
| 任务提醒 | 把待办、节点提醒推送到日常沟通工具 |
| 流程打通 | 把外部系统接进 AI 的执行链路 |
| 能力扩展 | 补充 WorkBuddy 本身不具备的能力 |
前两类之所以最容易见效，是因为它们都发生在一段工作已经做完之后——结果已经产出，MCP 只负责把它送出去，即使送错了，代价也就是补发一条。而”流程打通”这类要写入外部系统的用法，风险和收益都更高，建议放在你已经跑通过一两个只读 Server 之后再上。
五、状态灯：绿色和红色分别意味着什么
配好之后，界面上会有一个状态灯。官方的定义很简洁：
| 状态 | 含义 |
|---|---|
| 绿色 | 连接成功，可正常使用 |
| 红色 | 配置异常，需检查配置内容、命令环境或地址 |
红灯给的这三处是官方口径，但官方没说先查哪个。这里给一个按成本排的顺序——从最快能排除的往下走，别一上来就怀疑网络。
第一步：配置内容——先看 JSON 本身
这一步不需要联网，不需要装任何东西，几十秒就能排除，所以放在最前面。要看的是两类问题：
- JSON 语法错：少一个逗号、多一个逗号、引号没配对、大括号没闭合。JSON 对这些是零容忍的，一个字符不对整段就解析不了。最典型的是数组或对象最后一项后面多了个逗号。
- 字段名和层级写错：
mcpServers的大小写、command/args/env有没有放错层级、args是不是写成了字符串而不是数组（示例里它是["wecom-bot-mcp-server"]，方括号不能丢）。
对照官方示例那段 JSON 一行行比结构，比盯着自己写的那段看要快得多。这也是官方为什么建议从成熟示例起步——有个已知正确的样本在手边，比对成本极低。
第二步：命令环境——那个 command 能不能跑起来
配置本身没问题，下一个怀疑对象是 command 里那个命令在你这台机器上到底存不存在。示例里写的是 uvx，如果这台机器上根本没有装它，WorkBuddy 拿着这份配置也启动不了 Server，表现出来就是连不上。
判断方法也直接：在系统的终端里手动敲一次那个命令，看它认不认。命令不认识和命令能跑但报错，是两类完全不同的问题——前者是环境没装好，后者才轮到看参数和权限。顺带一提，args 里那个包名如果拼错，症状也会落在这一层，因为命令跑得起来但拉不到对应的 Server。
第三步：地址——最后才看它
地址放最后，不是因为它不重要，而是因为它是三者中唯一需要外部条件配合的，排查成本最高：可能是 URL 复制时漏了尾部字符，可能是凭证已经被重新生成过、旧的失效了，也可能是网络层面到不了。前两步都干净了再查这里，你至少能确定问题一定在这一段，而不是在三个可能性之间来回横跳。
需要说明的是，官方文档给出的是”检查配置内容、命令环境或地址”这三个方向，上面的先后顺序是按排查成本排的建议，不是官方规定的流程。如果你已经明确知道某一处刚改动过，当然是直接从那儿查最快。
六、去哪儿找 MCP Server，以及一条起步建议
官方给的资源入口是腾讯云 MCP 市场。
官方的最佳实践归纳起来是三条：公共能力配用户级、专属接入配项目级、从成熟示例起步。
第三条最容易被跳过，也最值得听。所谓”从成熟示例起步”，就是第一个接的不要挑冷门的、文档不全的 Server，而是先接像 WeCom Bot 这种路径清晰的——官方给了完整配置、凭证从哪儿拿写得明明白白。第一次接入的价值不在于接了什么，而在于你借这一次把整条链路走通了：配置格式长什么样、状态灯什么时候变绿、自然语言怎么触发。这条链路一旦在脑子里成型，后面接别的 Server 就只剩下换名字和换参数。
反过来，第一个就挑一个要自己摸索启动方式的 Server，红灯亮起来时你会同时怀疑五件事，而其中四件本可以提前排除掉。
小结
MCP 在 WorkBuddy 里是可视化配的，不用写代码、不用手改配置文件，所以真正需要你判断的只有两处。
配置级别上，官方原则是跨项目高频用用户级、项目专属用项目级；再叠一条自己的：凡是会往外发消息、往外写数据的 Server，优先放项目级，因为用户级意味着以后每个项目都握着这个能力。
状态灯变红时，官方指的三处是配置内容、命令环境、地址；按成本从低到高排，先对着官方示例查 JSON 语法和字段层级，再去终端确认 command 那个命令装没装，最后才查地址和凭证。
还有一条与功能无关但更要紧的：WebHook URL 是凭证不是地址，别进仓库，别原样转发。配置本身配错了可以重来，凭证漏出去是收不回来的。
相关阅读
- WorkBuddy 的记忆功能是什么？要不要开、该记什么、和任务上下文有何区别
- WorkBuddy 连接器怎么用？支持哪些服务、怎么连、授权范围该给到哪一步
- WorkBuddy 是什么？一篇讲清桌面 AI 办公 Agent 的能力边界与上手顺序
本文依据 WorkBuddy 官方文档（workbuddy.ai/docs/zh/workbuddy/ 的《MCP》《连接器》《10 个上手技巧》页面）整理，核对日 2026-08-08，非亲测操作记录。界面与功能以官方最新说明为准。