CapOwn — MCP（Model Context Protocol）支持

CapOwn Master 暴露一个 MCP（Model Context Protocol） 端点，让 AI Agent （Claude Code、Codex 等）可以直接与 CapOwn Worker 交互。端点挂载在 /mcp， 使用 Streamable HTTP 传输（无状态、JSON 响应）。MCP 是可选的北向接口： 现有 REST API、纯标准库 capown CLI 以及 Agent skill 仍然可用。

端点

POST http://<master-host>:9210/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <client-token>

重要：客户端 必须 在请求头中发送 Accept: application/json, text/event-stream。 MCP 要求同时声明这两种可接受类型，即使 CapOwn 始终以 application/json 响应。

认证

MCP 使用与 REST API 相同的 client bearer token。Admin token、Worker session token，以及过期/已吊销的 token 都会被拒绝。认证覆盖每一项 MCP 操作，包括初始化与 tools/list。

# 通过 admin API 创建 client token
curl -X POST https://<master>/api/admin/users/<username>/tokens \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"token_type": "client"}'

然后将返回的 token 值放进 Authorization 头：

Authorization: Bearer 4638a10accf1...

Origin 校验

当请求带有 Origin 头时，Master 要求已配置 public_url （通过 MASTER_PUBLIC_URL 或 [master] public_url），并校验 Origin 的 scheme、host、port 是否与之匹配。格式错误、无 scheme，以及不匹配的 Origin 会以 HTTP 403 拒绝。若未配置 public_url，所有带 Origin 的请求都会被拒绝， 因为此时没有可信任的浏览器来源。

非浏览器 MCP 客户端通常不发送 Origin；这类请求仍然允许，并通过 client bearer token 完成认证。若要使用基于浏览器的 MCP 客户端，请先配置 public_url。

工具一览

每个工具的参数都以单个 Pydantic 输入模型的形式放在 input 键下：

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "shell_run",
    "arguments": {
      "input": {
        "worker": "wrk_abc123",
        "command": "ls -la"
      }
    }
  }
}

所有面向 Worker 的工具都接受 worker 参数，可以是规范的 worker_id （例如 wrk_a1b2c3d4e5f6），也可以是 worker_name（例如 my-server）。 名称只在已认证用户所拥有的 Worker 范围内解析，因此不会产生歧义。

Worker 工具

工具	说明	主要参数
workers_list	列出当前用户拥有的全部 Worker	（无）
system_info	获取 OS、主机名、能力列表	worker
shell_run	执行命令并等待输出	worker、command、timeout
shell_dispatch	异步派发命令（不等待完成）	worker、command、timeout

文件工具

工具	说明	主要参数
file_list	列出目录内容	worker、path
file_read	读取文件	worker、path、offset、limit
file_write	写入文件内容	worker、path、content
file_edit	对文件做文本替换	worker、path、operations
file_find	按 glob 模式查找文件	worker、pattern、root
file_search	按模式搜索文件内容	worker、pattern、root、regex

任务管理工具

工具	说明	主要参数
task_get	查询任务状态	worker、task_id
task_wait	等待任务完成	worker、task_id、timeout
task_list	列出 Worker 上的近期任务	worker
task_cancel	取消正在运行的任务	worker、task_id

响应格式

工具返回 TextContent 块，内容为对应操作的输出。成功的结构化结果会序列化为 JSON 文本。工具失败时返回 isError: true；文本中包含结构化的 CapOwn 错误详情：

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{...output or error JSON...}"
      }
    ],
    "isError": true
  }
}

错误内容包含标准 MCP 错误字段以及 CapOwn 专用错误码：

{
  "capown_error_code": "worker_offline",
  "mcp_error_code": -32000,
  "message": "worker offline or not connected"
}

软超时

当 shell_run 命令超过其 timeout 时，工具会返回 running 状态以及 task_id，以便稍后轮询结果：

{
  "status": "running",
  "task_id": "a1b2c3d4e5f6",
  "preview": "partial output so far...",
  "hint": "Task is still running. Use task_get or task_wait to check progress.",
  "next_actions": ["check_later", "wait_longer", "cancel"]
}

仍在运行的任务操作会包含 task_id 以及 MCP 后续动作提示。非任务类操作超时 （例如 task_list）会保留自身 hint，不会带上空的 task ID。

健康检查

MCP 适配器成功初始化后，GET /health 会包含 "mcp_enabled": true。 该字段表示适配器是否可用，不代表认证或 Worker 连通性。

连接示例

Claude Code（claude.ai/code）

写入 ~/.claude/settings.json 或工作区 .claude/settings.local.json：

{
  "mcpServers": {
    "capown": {
      "transport": "streamable-http",
      "url": "http://localhost:9210/mcp",
      "headers": {
        "Authorization": "Bearer <your-client-token>"
      }
    }
  }
}

通用 MCP 客户端（Python）

import httpx

response = httpx.post(
    "http://localhost:9210/mcp",
    json={"jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {}},
    headers={
        "Accept": "application/json, text/event-stream",
        "Authorization": "Bearer <your-client-token>",
    },
)
print(response.json()["result"]["tools"])

该示例用于诊断，直接发送 JSON-RPC 调用。正常使用时，应由支持 MCP 的 Host 管理初始化与调用。

手动（curl）

curl -X POST http://localhost:9210/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <token>" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

---

在 Nginx 后部署

同时支持 CLI/skill 与 MCP 的公网反向代理配置（路径对照、双 location、 public_url 与 master_url 的区别）见部署指南，此处不重复粘贴：

• 中文：配置 Nginx
• 英文：Deployment / Nginx

代理参数与路径策略只维护在部署文档中。

CLI 与 Skill 兼容性

MCP 不会取代现有 Client。当 Agent Host 不支持 MCP、仅短 HTTPS 请求更可靠， 或更偏好纯标准库客户端时，请继续使用 capown CLI 和 skills/capown-client/SKILL.md。MCP 与 REST/CLI 路径共享认证、归属校验、 任务路由以及 Worker 执行行为。

---

暂缓功能

以下内容在初始 MCP 实现中明确不在范围内：

功能	原因
OAuth 2.1 / 基于 OAuth 的 MCP 认证	现有 token 体系已覆盖鉴权需求；OAuth 需要新增 token 端点
动态 tools/list_changed	所有工具在启动时静态注册
MCP Tasks（实验性）	软超时返回 running + task_id；MCP Tasks 规范尚未稳定
Worker 协议变更	未改动 Worker 传输层 - 通信仍经 Master 转发
第三方 MCP 服务代理	CapOwn 暴露自身工具；托管外部 MCP 服务是独立功能