个人 MCP：员工指南

谁该看这一篇

员工：你想让 Sira AI 在企业微信 / 飞书 / Web 上调用你自己电脑上的工具（GitHub / Notion / 本地文件等）
IT 管理员：先看个人 MCP：管理员指南完成部署前置

License 前置

需要 sandbox.user_pc (PROFESSIONAL 或以上 tier)
需要 mcp.personal (STANDARD 起，付费 org 默认开)
两者都没开 → UI 上「我的 MCP」tab 仍可见，但会一直是空状态

一句话说清

你在电脑上写一个 ~/.sandrpod/mcp.json，里面声明 N 个 MCP 服务器（带你的 GitHub Token / Notion Key 等个人凭据），AI 在任一渠道找到你时都能调用这些工具——凭据全程留在你电脑上，不进 Sira 服务器，不进同事的会话。

整体流程

你写 ~/.sandrpod/mcp.json           ┐
                                    │
sandrpod-agent (你电脑上常驻)        │  ↓ 拉起 N 个 stdio 子进程
   ├─ 解析 mcp.json                  │     (github / notion / ...)
   ├─ 聚合成单一 HTTP MCP endpoint   │
   └─ 通过反向 tunnel 暴露给远端     ↓
                                    
Sira 后端心跳 (30s)                  
   ├─ 拉一份 manifest 写 DB          
   └─ 在「我的 MCP」UI 显示状态      
                                    
你在 IM 跟 AI 对话                  
   └─ AI 想用某个 personal 工具     
       └─ 经隧道调用 → 你电脑上跑   
           └─ 敏感工具弹原生同意框

前置：注册电脑沙箱

~/.sandrpod/mcp.json 必须在已注册沙箱的电脑上才会被 sandrpod-agent 加载。先去 /agent-system/sandboxes → 「我的沙箱」tab 注册：

点「添加我的电脑」按钮
复制弹出对话框里的一行命令，在终端粘贴执行
等 LaunchAgent / systemd-user / NSSM 起来后，UI 状态变成「在线」

详见员工 PC 沙箱：安装指南。

写 mcp.json

路径

OS	文件位置
macOS	`~/.sandrpod/mcp.json`
Linux	`~/.sandrpod/mcp.json`（或 `$XDG_CONFIG_HOME/sandrpod/mcp.json`）
Windows	`%APPDATA%\sandrpod\mcp.json`

格式（与 Claude Desktop 完全兼容）

最简：从 Claude Desktop 直接复制过来即可：

bash

# macOS
mkdir -p ~/.sandrpod
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json \
   ~/.sandrpod/mcp.json
chmod 600 ~/.sandrpod/mcp.json   # 含凭据，建议 600

同时启用 Claude Desktop 和 sandrpod

两个进程会各自起一份 stdio 子进程，某些 MCP server（如 SQLite 写锁）会冲突。建议要么二选一，要么给 sandrpod 维护一份独立 mcp.json。

一个完整示例

json

{
  "mcpServers": {
    "github": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "filesystem": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents"
      ]
    },
    "notion": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["tool", "run", "mcp-server-notion"],
      "env": {
        "NOTION_TOKEN": "secret_xxxxxx"
      }
    }
  }
}

sandrpod 扩展字段（可选）

放在每个 server 配置的 sandrpod 子对象内，其他 MCP 工具（Claude Desktop / Cursor）会忽略：

jsonc

{
  "mcpServers": {
    "github": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." },
      "sandrpod": {
        "alias": "gh",                 // 工具前缀别名，AI 会看到 gh__list_issues
        "restart_policy": "on-failure", // always / on-failure / never
        "max_restart_per_min": 3,
        "startup_timeout_sec": 60,      // npm 包没装的话 30s 可能不够
        "tool_allowlist": ["list_issues", "create_pr"],  // 只暴露这两个
        "tool_denylist": ["delete_repo"]                  // 禁用这一个
      }
    }
  }
}

macOS 用户的 PATH 坑

必读

macOS LaunchAgent 启动 sandrpod-agent 时，默认 PATH 不含 /opt/homebrew/bin。如果你 mcp.json 里写 "command": "npx"，会报：

exec: "npx": executable file not found in $PATH

两种解决：

command 用绝对路径（推荐，最直观）：
json
```
"command": "/opt/homebrew/bin/npx"
```

在 server 配置里加 env.PATH：

json

"env": {
  "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}

Sira ≥ 5/28 的 installer 已经在 launcher 里默认 export PATH 含 Homebrew，新装的员工不会再踩这个坑。老版本装的请重装一遍，或手动给 ~/.sira/bin/sira-sandbox-launcher 加一行 export PATH="/opt/homebrew/bin:..."。

在 UI 上看状态

进入 /agent-system/sandboxes → 切到 「我的 MCP」 tab：

┌─ 我的 MCP ─────────────────────────────────┐
│ [在线]  3 个服务，共 24 个工具    上次同步: 12 秒前 │ [立即刷新]
│ ────────────────────────────────────────── │
│  □ github   [✓ 运行中]    工具数: 8         │
│  □ notion   [✓ 运行中]    工具数: 5         │
│  □ jira     [✗ 失败]      重启 3 次          │
│       ⚠ missing JIRA_TOKEN env              │
└─────────────────────────────────────────────┘

四种状态

状态条颜色	含义	你该做什么
🟢 在线	至少一个 server `ready` 且没 `failed`	啥也不用做，AI 已经能用
🟡 部分在线	有 `ready` 也有 `failed`	看 failed 卡片的 `last_error` 修配置（多半是凭据缺失）
⚪️ 离线	没有 `ready` server / 沙箱 / sandrpod 不可达	检查电脑是否开机，沙箱是否在线
🔵 未配置 mcp.json	沙箱在线但找不到 `~/.sandrpod/mcp.json`	按上文写一份

「立即刷新」按钮

后端每 30 秒自动心跳同步。刚改完 mcp.json 不想等？点「立即刷新」立即拉一次。单 IP 限速 6 次/分钟（防误操作），按多了会等 10 秒。

AI 用你的工具时会发生什么

普通工具

AI 直接调，立即返回。你的 PC 上不会有任何 UI 提示——本来就是后台静默执行。

敏感工具（不可绕过）

工具名包含以下子串时，每次调用都会在你的桌面弹原生同意框：

delete, remove, drop, truncate, purge, destroy, wipe,
send, publish, post, transfer, pay, charge,
merge, revoke, reset, unsubscribe

弹框是 sandrpod-tray 触发的（osascript on macOS / zenity on Linux / Windows native dialog）。点拒绝 = AI 这次操作失败；点同意 = 工具继续执行。

这一刻你跑哪去了？

AI 等你弹框响应的默认超时是 90 秒。你去喝咖啡了？回来一看 AI 在 IM 里说"我没收到你的授权，这次没操作，需要的话再让我试一次"。再点一次「立即刷新」或重发指令即可。

如果你确定某个看起来敏感的工具其实安全（比如 merge_dataframe 跟"删除"无关），可以在启动 sandrpod-agent 前 export 自定义模式：

bash

# 在 ~/.sira/bin/sira-sandbox-launcher 里加一行：
export SANDRPOD_MCP_SENSITIVE_PATTERNS_OVERRIDE="delete,destroy,wipe,send_money"

凭据怎么存的、谁能看见

凭据 / 数据	存在哪	谁能看到
`mcp.json` 的 `env` 块里的 token / API key	你电脑上 `~/.sandrpod/mcp.json` (chmod 600)	只有你本机的用户
sandrpod-agent 连远端的 `SANDRPOD_TOKEN`	macOS Keychain / Linux Secret Service / Windows DPAPI	只有你本机的用户
MCP Bearer (`SANDRPOD_MCP_TOKEN`)	同上（不同 service name）	只有你本机的用户
AI 用工具的事实（调了哪个工具、何时调、成功/失败）	Sira 的审计表 `sandbox_decision_events`	你 + IT 管理员
工具调用的参数 / 返回值	不上传任何地方	谁都看不到

别人解绑你电脑也调不到

即使 Sira 后端被入侵，攻击者也无法对你电脑发起新的 MCP 调用——他需要同时偷到 sandrpod 的 corp api_token 和你 sandbox 独有的 mcp_token，两个都是用 Fernet 加密的，且 mcp_token 仅 enrollment 后下发那一次接触明文。

常见错误排查

`exec: "npx": executable file not found in $PATH`

LaunchAgent 看不到 Homebrew。见上面 macOS 用户的 PATH 坑。

`transport error: transport closed`（启动后立刻退出）

npx 起来了，但它内部调 node 找不到（同一个 PATH 问题），或者 mcp server 凭据缺失立刻 crash。

bash

# 手动跑一遍同样的命令看实际错误：
/opt/homebrew/bin/npx -y @modelcontextprotocol/server-github
# 看看 stderr 报什么

日志显示 `no servers loaded yet`

mcp.json 还没创建。不用重启——sandrpod 在 watch ~/.sandrpod/ 目录，把 mcp.json 放进去（cp / mv / 编辑器保存都行），250ms 内自动接住。

这是新行为

sandrpod ≥ 5/28 fix 7794c8b 修了"启动时无 mcp.json = bridge 永久禁用"的老问题。如果你的 agent 还是老版本（看日志里有没有 bridge disabled 字样），重装一遍 installer 就能升上来。

想临时关掉所有 MCP

直接 rm ~/.sandrpod/mcp.json 即可：sandrpod 会自动 teardown 所有 child，manifest 清空。想恢复就把文件放回去（建议 cp 而不是 touch，确保配置内容完整）。这是 sandrpod 设计的"软停"姿势，比改 enabled=false 一个个 server 关方便。

state 卡在 `starting`

npm 第一次下载 context7-mcp 等包很慢（~30 秒）。如果你包大或网络慢，把 startup_timeout_sec 调大：

json

{
  "mcpServers": {
    "your-server": {
      "command": "/opt/homebrew/bin/npx",
      "args": [...],
      "sandrpod": { "startup_timeout_sec": 120 }
    }
  }
}

UI 显示「在线」但 server 列表空

后端 live fetch 偶发失败，会从 DB 缓存回退。出现这种情况通常是 sandrpod-agent 正在 hot-reload，等 5 秒再点「立即刷新」即可。

改完 mcp.json AI 还在用旧工具

sandrpod 默认开 fsnotify hot-reload，理论上你保存文件后 250ms 内自动 reload（Write / Create / Rename / Remove 四种事件都接住）。如果没生效，确认：

bash

ps aux | grep sandrpod-agent | grep -v grep
# 应该能看到进程，且 -mcp-hot-reload 不是 false

或者重启 LaunchAgent：

bash

launchctl kickstart -k gui/$(id -u)/com.sira.sandbox

完全卸载

bash

~/.sira/bin/sira-sandbox-uninstall

会做：

停 LaunchAgent / systemd-user / NSSM service
删除 sandrpod-agent + tray 二进制
从 Keychain / Secret Service / DPAPI 撤销 token
回调 Sira /self-revoke 让服务端把 sandbox 标 revoked

~/.sandrpod/mcp.json 不会被删——你的凭据由你管，卸载不动它。

别人卸载我电脑上的怎么办？

不会发生。~/.sira/bin/sira-sandbox-uninstall 走的是本机文件权限 + Keychain 用户权限。同事偷了 mcp_token 也卸载不动——他没你 macOS 账号密码。

参考

设计文档：SIRA_PERSONAL_MCP_INTEGRATION.md（消费方架构）
sandrpod 侧：MCP_BRIDGE.md（sandrpod 用户手册）
IT 管理员视角：personal-mcp-admin.md

个人 MCP：员工指南 ​

一句话说清 ​

整体流程 ​

前置：注册电脑沙箱 ​

写 mcp.json ​

路径 ​

格式（与 Claude Desktop 完全兼容） ​

一个完整示例 ​

sandrpod 扩展字段（可选） ​

macOS 用户的 PATH 坑 ​

在 UI 上看状态 ​

四种状态 ​

「立即刷新」按钮 ​

AI 用你的工具时会发生什么 ​

普通工具 ​

敏感工具（不可绕过） ​

凭据怎么存的、谁能看见 ​

常见错误排查 ​

exec: "npx": executable file not found in $PATH ​

transport error: transport closed（启动后立刻退出） ​

日志显示 no servers loaded yet ​

想临时关掉所有 MCP ​

state 卡在 starting ​

UI 显示「在线」但 server 列表空 ​

改完 mcp.json AI 还在用旧工具 ​

完全卸载 ​

别人卸载我电脑上的怎么办？ ​

参考 ​

个人 MCP：员工指南

一句话说清

整体流程

前置：注册电脑沙箱

写 mcp.json

路径

格式（与 Claude Desktop 完全兼容）

一个完整示例

sandrpod 扩展字段（可选）

macOS 用户的 PATH 坑

在 UI 上看状态

四种状态

「立即刷新」按钮

AI 用你的工具时会发生什么

普通工具

敏感工具（不可绕过）

凭据怎么存的、谁能看见

常见错误排查

`exec: "npx": executable file not found in $PATH`

`transport error: transport closed`（启动后立刻退出）

日志显示 `no servers loaded yet`

想临时关掉所有 MCP

state 卡在 `starting`

UI 显示「在线」但 server 列表空

改完 mcp.json AI 还在用旧工具

完全卸载

别人卸载我电脑上的怎么办？

参考