MCP CLI 与 API

XOPC 提供 出站 bundle-MCP（智能体调用外部 MCP 工具）和 入站通道桥接（xopc mcp serve，供 stdio MCP 客户端连接）。

配置、控制台操作、工具命名与生命周期详见主文档：MCP。

---

配置速查

MCP 服务器写在 ~/.xopc/xopc.json 的 mcp.servers 下：

{
  "mcp": {
    "sessionIdleTtlMs": 600000,
    "servers": {
      "fetch": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-fetch"]
      },
      "remote": {
        "url": "https://example.com/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MCP_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}

字段	说明
command + args	stdio 子进程启动 MCP
url + transport	远程 MCP：sse 或 streamable-http
headers / env	HTTP 头或 stdio 环境变量（支持 ${变量名}；stdio 会过滤宿主环境）
connectionTimeoutMs	连接 / 拉工具 / 调用超时（默认 30 秒）
sessionIdleTtlMs	会话级运行时空闲回收（默认 10 分钟；0 表示不回收）

扩展 .mcp.json 与用户配置合并（同名 id 以用户为准）。

---

关闭 MCP 工具

在 agents.defaults.tools.disable 或某个 agents.list 条目的 tools.disable 中加入 bundle-mcp。单个工具名格式为 服务器ID__工具名。

---

CLI

管理服务器

xopc mcp list
xopc mcp show [name]
xopc mcp set fetch '{"command":"npx","args":["-y","@modelcontextprotocol/server-fetch"]}'
xopc mcp unset fetch

xopc mcp set 的第二个参数是服务器条目的 JSON 对象；id 即 set / unset 使用的名称。

入站通道桥接

通过 stdio 把网关会话暴露给外部 MCP 客户端：

xopc mcp serve --url http://127.0.0.1:18790 --token-file ~/.xopc/gateway.token

参数	说明
--url	网关根地址
--token / --token-file	Bearer 令牌
--password / --password-file	密码鉴权（若网关配置了密码）
--claude-channel-mode	auto | on | off — Claude Desktop 通道兼容
-v	详细日志

---

网关 REST API

需网关鉴权（Bearer 令牌或配置的密码）。

接口	方法	说明
/api/mcp/servers	GET	列出已配置及扩展合并后的服务器
/api/mcp/servers/:id/tools	GET	某服务器的工具目录（读已保存配置）
/api/mcp/servers/:id/test	POST	连接并拉取工具（请求体可临时覆盖表单字段）
/api/mcp/approvals/respond	POST	通道桥接审批占位接口

测试 / 工具列表响应

每条工具示例：

{
  "name": "fetch__browse",
  "shortName": "browse",
  "description": "Fetch a URL and return readable content"
}

控制台 测试 与 查看全部 弹层使用上述字段。

MCP 配置的增删改通过通用配置 API：GET /api/config、PATCH /api/config（见 网关服务）。

---

Web UI

网关控制台 → 设置 → MCP（#/settings/agent-mcp）：

• 会话空闲 TTL
• 可折叠服务器卡片（stdio / SSE / Streamable HTTP）
• Headers 键值编辑（支持粘贴）
• 连接超时
• 测试 与可搜索的 查看全部 工具弹层

完整界面说明见 MCP 指南。

---

安全说明

• stdio MCP 使用过滤后的宿主环境（host-env-security-policy.json）。
• 委托子任务不能使用 MCP 工具（bundle-mcp 黑名单）。
• before_tool_call 扩展钩子可读取 isMcpTool、mcpServerId 做策略控制。