MCP 使用指南

本指南以 WorkBuddy AI 为例，演示如何把 YAMA 主控的 MCP 工具接入一个 AI 客户端。 换成 Claude Desktop、Cline、Trae 等客户端时，只有第 2 步的配置界面不同，地址与 Token 完全一致。

🎁 推荐注册：WorkBuddy AI 是一个开箱即用的 AI 客户端，支持自定义 MCP 连接器。 通过作者的邀请链接注册新账号，可获得积分奖励（具体奖励内容、发放条件与有效期以 WorkBuddy 官方页面为准）：

https://workbuddy.ai/invite?code=Q4MHDR2E

不通过邀请链接也能完成本文全部步骤，下面的配置与方法不受任何影响。

开始之前

• 主控（服务端）升级到 1.4.2 及以上，并且能正常看到在线主机。
• AI 客户端与主控在同一台电脑上运行。MCP 默认只监听 127.0.0.1，跨机使用见「常见问题」。
• 只对你拥有或获明确授权的设备操作。
• 工具清单与每个工具的说明见 MCP 工具 页面。

第一步：在主控中启用 MCP

1. 打开主控 →「扩展 → MCP设置」。

2. 勾选「启用 MCP」，确认下面几项：

   字段	说明	默认值
   端口	MCP 服务监听端口	6544
   绑定地址	监听网卡。只给本机用时保持回环地址	127.0.0.1
   Token	Bearer 鉴权口令，首次打开会自动预填一个随机值	随机 32 位十六进制

3. 先保持「只读模式（禁命令执行）」勾选——只读工具（查主机、看进程、截屏、读日志、列文件等）默认就能用，写操作以后再按需打开。

4. 点「确定」，完全退出并重新启动主控。开关、端口、Token 的改动都要重启才生效。

5. 重新打开「MCP设置」，把 Token 复制出来，下一步要用。

Token 也可以用环境变量 YAMA_MCP_TOKEN 覆盖（优先级更高，适合不想把 Token 写进主控配置的场景）。

主控配置存在哪里取决于版本：发布版（Release）在注册表 HKEY_CURRENT_USER\Software\YAMA\settings， 调试版（Debug）在程序目录的 settings.ini。

验证服务端是否就绪（可选）

在主控这台机器上打开 PowerShell，把 Token 换成你复制的那一串：

$token = "粘贴你的 Token"
Invoke-RestMethod -Uri "http://127.0.0.1:6544/mcp" -Method Post `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' |
  Select-Object -ExpandProperty result |
  Select-Object -ExpandProperty tools |
  Select-Object -ExpandProperty name

能看到一串工具名（list_online_hosts、list_processes……）就说明 MCP 已经在正常工作。 报 Unauthorized（HTTP 401）说明 Token 不对；连接被拒说明服务没起来或端口不对。

第二步：在 WorkBuddy 中配置 MCP 连接器

打开 WorkBuddy → 左侧导航「专家·技能·连接器」→「连接器」→ 右上角「自定义连接器」→「MCP 服务管理」→「配置 MCP」， 把下面的 JSON 粘贴进去（Token 换成你自己的），然后「保存」：

{
  "mcpServers": {
    "yama": {
      "type": "http",
      "url": "http://127.0.0.1:6544/mcp",
      "headers": {
        "Authorization": "Bearer 粘贴你的 Token"
      },
      "timeout": 120000,
      "disabled": false
    }
  }
}

各字段的作用：

保存后，连接器状态点变绿、显示工具已启用即为成功。若连接器没有立即出现，完全退出 WorkBuddy 再重新打开。

配置同时会写入本机的 %USERPROFILE%\.workbuddy\mcp.json，界面上改不动时可以直接编辑这个文件。 如果你的客户端支持 ${VAR} 形式的环境变量替换，也可以把 Token 放进环境变量，用 "Authorization": "Bearer ${YAMA_TOKEN}" 引用，避免明文落盘。

第三步：验证并开始对话

新开一个会话，先试只读操作（不需要打开任何开关）：

• 「现在有哪些机器在线？」→ 调用 list_online_hosts
• 「把 IP 含 10.0.0 的主机列出来」→ 调用 search_hosts
• 「截一张某某主机现在的画面」→ 调用 get_screenshot
• 「这台机最近有什么报错？」→ 调用 get_client_log
• 「现在开了哪些 MCP 能力？」→ 调用 get_server_status

确认链路正常后，再按需打开写权限。

第四步：按需打开写权限

所有开关都在「扩展 → MCP设置」里，改完要重启主控。工具的可见性由开关决定：开关没开，模型在 tools/list 里根本看不到这些工具。

权限给得越少越安全。用完写能力后建议把对应的开关关回去。

常见问题

连接器状态是红的，或提示 401 Unauthorized

• Token 与主控里的不一致：改过 Token 却没有重启主控；或者环境变量 YAMA_MCP_TOKEN 覆盖了界面上的值。
• Bearer 与 Token 之间少了一个空格，或复制时带了多余的空格、引号、换行。
• 上一轮连续失败次数太多被限流：同一 IP 在 60 秒内失败 10 次会被封锁 900 秒，返回 429 Too many failed authentication attempts。等封锁过去再试。

连接器显示正常，但模型看不到某个工具

• 对应开关没开。工具只在开关打开时才出现在 tools/list 里，改完开关要重启主控。
• 客户端缓存了旧的工具列表：新开一个会话，或重启 WorkBuddy。
• 只读模式勾着：大部分写工具被隐藏。

调用失败的错误码怎么处理

长任务总是超时

• 客户端侧：把连接器 JSON 里的 timeout 调大（最大 600000）。
• 服务端侧：工具默认等待 20 秒，可以改 McpToolTimeoutMs（单位毫秒，范围 1000–600000），重启主控生效。 发布版在注册表 HKEY_CURRENT_USER\Software\YAMA\settings 下新建字符串值（REG_SZ）McpToolTimeoutMs，值为 60000（DWORD 不生效）； 调试版在 settings.ini 的 [settings] 节加一行 McpToolTimeoutMs=60000。

AI 客户端在另一台电脑上

默认只监听 127.0.0.1，跨机连不上。两种做法：

• 把「绑定地址」改成 0.0.0.0，同时在防火墙里只放行特定来源 IP。不要把端口直接暴露到公网，Bearer Token 一旦泄露等于主控被接管。
• 或者用 FRP / SSH 隧道把远端的 127.0.0.1:6544 转发回本机，客户端配置仍写 127.0.0.1。

想走 HTTPS

在「MCP设置」里勾选「启用 HTTPS」，填 PEM 格式的证书与 PKCS#8 格式的私钥，重启主控；连接器里的 url 改成 https://…，客户端需信任该证书（自签时要导入信任库）。

审计与排查

• 所有鉴权失败与工具调用都记在主控程序目录的 logs\mcp_audit.log，超限后滚动为 mcp_audit.log.1。
• 主控界面上的消息日志里也能看到策略拒绝、工具不可用等记录。

安全建议

• 先只读，再逐项放开；用完把写开关关回去。
• Token 当密码对待：不要截图发人、不要提交到仓库；怀疑泄露就在「MCP设置」里换一个并重启。
• 只监听回环地址，跨机需求用隧道而不是把端口开到公网。
• 远程交谈、键盘记录、浏览记录、收藏夹都属于隐私数据，只在确有授权时开启。