很多团队在把 WorkBuddy 接入内部系统时，都会在 MCP 配置环节踩到类似的坑。下面把工程实践中出现频率较高的 10 个问题整理成问答，便于对照排查。

Q1：MCP 到底是什么，和传统的插件（Plugin）有什么不同？

MCP（Model Context Protocol，模型上下文协议）是一套开放的连接协议，用来让 AI 工具在运行时按需调用外部能力。和早期"插件"相比，差异主要体现在三点：

其一，MCP 把能力提供方和宿主应用解耦，同一个 MCP Server 可被多个支持该协议的客户端复用。
其二，MCP 定义了标准化的工具（Tool）、资源（Resource）、提示词（Prompt）三类原语，接入方按规范实现即可。
其三，MCP 支持本地进程（stdio）与远程服务（HTTP/Streamable）两种承载方式，部署更灵活。

Q2：mcp.json 的基本结构长什么样？

WorkBuddy 的自定义 MCP 配置存放在 ~/.workbuddy/mcp.json。一个最小可用结构如下：

{
  "mcpServers": {
    "demo-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-demo"],
      "env": {
        "MCP_SERVER_URL": "https://example.com/mcp",
        "MCP_TOKEN": "${DEMO_TOKEN}"
      }
    }
  }
}

注意：以上 command、args、env、url 等字段为 MCP 通用约定；具体服务器地址与鉴权参数以官方文档为准，example.com 仅作占位示意。

Q3：stdio 与 HTTP 两类 server 怎么选？

选择依据是部署形态与调用频率。

Step 1：能力脚本在本地、希望零网络暴露，优先 stdio，由宿主进程拉起子进程通信。
Step 2：能力部署在远端、需要被多个客户端共享，或要做集中鉴权，选 HTTP（Streamable HTTP / SSE）模式。

经验上，个人开发调试用 stdio 更省心，团队协作生产用 HTTP 更可控。

Q4：连接器配置好了却完全不生效，如何排查？

按以下顺序逐项确认：

其一，确认信任开关已开启。WorkBuddy 对新接入的 MCP Server 默认需要显式信任，未信任时不会加载。
其二，确认路径正确。~/.workbuddy/mcp.json 与项目级 .workbuddy/ 路径不要混淆。
其三，确认权限充足。stdio 模式依赖本地命令可执行，容器或受限环境可能缺少运行时。

Q5：如何接入企业微信机器人做消息推送？

思路是在 MCP Server 中封装"发送消息"这一动作，再由 WorkBuddy 在合适节点调用。关键不是去拼接口细节，而是把群机器人 Webhook 作为环境变量注入，由 Server 端负责实际请求。

# 示意：把企业微信机器人地址注入环境变量（实际地址以企业微信官方文档为准）
export WEBCOM_WEBHOOK="https://example.com/webhook/your-key"

注意：具体 Webhook 地址与消息体字段以企业微信官方文档（work.weixin.qq.com）为准，以上 example.com 仅为占位。

Q6：Skill 与 MCP 怎么配合？

可以把 Skill 理解为"面向任务的提示词与工作流包"，MCP 理解为"标准化的外部能力接口"。典型配合方式是 Skill 定义"做什么"，MCP Server 提供"调哪个工具"。例如一个"日报汇总"Skill，在内部声明调用某个 MCP 工具拉取数据，再交给模型组织文案。两者解耦后，同一套 MCP 能力可被多个 Skill 复用。

Q7：密钥管理有哪些注意事项？

核心原则是明文不入文件。

其一，密钥通过 env 注入，引用系统环境变量（如 ${DEMO_TOKEN}），不要写死在 mcp.json 里。
其二，项目级配置不要提交到代码仓库，建议加进 .gitignore。
其三，定期轮换 token，避免长期有效的凭证泄露后被持续利用。

Q8：多个项目如何共享一套 MCP 配置？

用户级配置放在 ~/.workbuddy/mcp.json，对该用户所有工作区生效；项目级放在 .workbuddy/mcp.json，只对当前项目生效并随仓库携带。需要团队统一能力时，把通用 Server 放进项目级配置并通过版本管理下发，个性化部分留在用户级，避免相互覆盖。

Q9：常见报错有哪些类型？

其一，启动失败：多为 command 不可执行或依赖缺失。
其二，握手超时：HTTP 模式下地址不通或服务未就绪。
其三，工具列表为空：Server 未正确实现 tools/list。
其四，鉴权异常：env 中 token 缺失或失效，返回 401/403。

Q10：如何验证连接器连通性？

最简单的是在 WorkBuddy 中触发一次该 MCP 提供的工具调用，观察返回。也可以单独运行 Server 进程看日志：

# 示意：本地前台启动某个 MCP Server，观察握手与工具注册日志
npx -y @example/mcp-demo
# 实际包名与运行参数以对应 MCP Server 官方说明为准

若日志中出现工具列表且能被宿主识别，说明链路已通。WorkBuddy 还提供 SkillHub 技能市场，可安装大量现成 Skills，存放于 ~/.workbuddy/skills/（用户级）或项目 .workbuddy/skills/（项目级）。

想深入了解 WorkBuddy 的 MCP 与 Skill 机制，可访问官方文档入口 https://cloud.tencent.com 与 SkillHub 技能市场。

公司简介

上海华万，专注为企业提供SaaS产品的一站式选型与集成服务。国内产品线涵盖腾讯会议、企业微信、腾讯电子签等腾讯生态产品，国际产品线包括Microsoft Teams、Zoom、DocuSign等协作与签约工具。从需求诊断、产品选型到系统部署、API集成与长期运维，华万为企业量身定制落地路径，覆盖售前咨询、方案设计、部署实施与售后服务全流程。目前已服务制造、零售、教育、金融等多个行业的中小企业客户。

配图提示词

A. A flat illustration showing an AI assistant connecting modular puzzle pieces labeled MCP and Skill, clean workspace scene with soft colors --ar 16:9 --style flat --stylize 100

B. A manga panel style comic showing a developer troubleshooting a config file with a floating robot helper pointing at errors, expressive face --ar 3:4 --style manga --stylize 500

C. A hand-drawn lineart sketch of a configuration file connected to multiple server nodes by dashed lines, minimalist pen style --ar 16:9 --style lineart