MCP 工具参考

端点信息

GET /mcp 返回 405 Method Not Allowed（Allow: POST）。

推荐请求头：

Authorization: Bearer <access-token>
Content-Type: application/json
Accept: application/json, text/event-stream

Token 缺失或无效时，HTTP 层直接返回 401，不进入 MCP 协议。

如果 MCP 客户端只能配置 server URL，无法设置自定义请求头，可使用 http://<console-host>:8089/mcp?token=<access-token>。查询参数名默认是 token，可通过 CONSOLE_MCP_TOKEN_QUERY_PARAM 修改。能设置请求头时仍建议优先使用 Bearer header，因为 URL token 可能出现在日志、浏览器历史或中间代理链路中；生产环境请使用 HTTPS。

支持的 MCP 方法

工具一览

所有工具的参数 schema 均设置 additionalProperties: false。传入未定义字段会返回 JSON-RPC 错误 -32602 invalid params。

在 CONSOLE_HIDDEN_TOOLS 中列出的工具会从 tools/list 中隐藏；如果客户端已知工具名，仍可继续调用。详见 Console 配置。

工具的 name、title、description 以及单个参数的 description 可以通过环境变量覆盖（CONSOLE_MCP_TOOL_<TOOL>_NAME / _TITLE / _DESCRIPTION / _PARAM_<PARAM>_DESCRIPTION）。_NAME 覆盖会改变客户端在 tools/list 中看到的、以及 tools/call 用作路由键的值；CONSOLE_HIDDEN_TOOLS 仍然填内部 capability ID。将参数描述设置为空串会把该参数从 tools/list 中隐藏，但 HTTP 调用仍然可以传入该字段——此时对应 schema 的 additionalProperties 会变为 true。详见 Console 配置。

工具详情

echo

连通性测试工具，验证 worker 可达性。

入参：

入参示例：

{ "message": "hello", "timeout_ms": 5000 }

出参：

出参示例：

{ "message": "hello" }

pythonExec

在 worker 上执行 Python 代码并返回执行结果。每次调用均在隔离环境中执行，不保留会话状态。

第三方依赖： 不支持在运行时安装包（如 pip install）。引用第三方包的唯一方式是 PEP 723 内联脚本元数据——在代码顶部声明 # /// script 块，worker 会在执行前自动安装其中列出的依赖。

入参：

入参示例：

{ "code": "print(1 + 1)", "timeout_ms": 60000 }

使用第三方依赖的入参示例（PEP 723）：

{
  "code": "# /// script\n# dependencies = [\"httpx\"]\n# ///\nimport httpx\nprint(httpx.get('https://example.com').status_code)"
}

出参：

出参示例：

{ "output": "2\n", "stderr": "", "exit_code": 0 }

exit_code 非 0 时依然作为正常工具输出返回，不触发 MCP 协议层错误。

terminalExec

在持久化 terminal 会话中执行 shell 命令，支持跨调用的会话状态保持（工作目录、环境变量、进程等）。

入参：

当 create_if_missing=true 时，以保留 Computer Use 前缀（默认 CU:）开头的 session_id 会被拒绝；当 create_if_missing=false 时，同一值仍按普通 sandbox session 查找处理。

入参示例：

{
  "command": "ls -la",
  "session_id": "sess_xxx",
  "create_if_missing": true,
  "lease_ttl_sec": 300,
  "timeout_ms": 30000
}

出参：

出参示例：

{
  "session_id": "sess_xxx",
  "created": true,
  "stdout": "total 0\ndrwxr-xr-x ...\n",
  "stderr": "",
  "exit_code": 0,
  "stdout_truncated": false,
  "stderr_truncated": false,
  "lease_expires_unix_ms": 1770000000000
}

并发与容量错误：

• session_busy 表示单个 session 内的并发上限已达到。
• no_capacity 表示 worker 级 capability 并发额度耗尽。
• session_capacity_exceeded 表示新建 session 时选中的 worker 已达到 WORKER_TERMINAL_MAX_ACTIVE_SESSIONS；已有 session 仍可使用。

这些情况会作为 MCP 工具错误返回，响应中的 isError 为 true，错误文本会保留对应错误码；它们不是 JSON-RPC 协议层错误。

computerUse

列出或定向使用调用账号自有的 worker-sys。命令固定投递到选定的真实宿主机，失败时不会回退到其他 Worker；不维护会话状态。

入参：

入参示例：

{
  "worker_id": "worker-id",
  "command": "screencapture -x /tmp/screenshot.png",
  "timeout_ms": 30000,
  "request_id": "req-001"
}

出参：

未提供 worker_id 时，Console 不派发命令（即使同时提供了 command），并返回当前账号全部在线与离线 Worker System：

{
  "worker_list": [
    { "worker_id": "worker-id", "node_name": "laptop", "status": "online", "capabilities": [] }
  ]
}

提供 worker_id 时返回执行结果：

出参示例：

{
  "stdout": "",
  "stderr": "",
  "exit_code": 0,
  "stdout_truncated": false,
  "stderr_truncated": false
}

与 terminalExec 的关键区别：无会话相关字段（session_id、create_if_missing、created、lease_expires_unix_ms）；命令直接在选定宿主机执行，无容器隔离。

readImage

从 terminal 会话工作环境或 worker-sys 宿主机读取图片文件，以 MCP 图片内容项返回，适合多模态 AI 工作流。

入参：

路由规则：

CU: 是默认前缀，大小写敏感。可通过环境变量 CONSOLE_COMPUTER_USE_SESSION_ID_PREFIX 或 TOML 配置项 computer_use_session_id_prefix 修改；下文示例均使用默认值。修改前缀会改变 readImage、exportFile 以及 terminalExec 对 session ID 的解释方式，通常不建议修改。

入参示例（从 terminal 会话读取）：

{ "session_id": "sess_xxx", "file_path": "/workspace/chart.png", "timeout_ms": 60000 }

入参示例（从 worker-sys 宿主机读取）：

{ "session_id": "CU:worker-id", "file_path": "/tmp/screenshot.png", "timeout_ms": 10000 }

出参：

• 若文件 MIME 类型为 image/*：返回一个 MCP 图片内容项（type: "image"），包含 base64 编码的图片数据。
• 若文件 MIME 类型非图片：返回一个 MCP 文本内容项（type: "text"），内容为：

unsupported mime type: <mime>; expected image/*

exportFile

将会话中的文件导出到 console 配置的 S3 兼容对象存储，并返回一个预签名下载 URL。

入参：

行为说明：

• 仅当 console 侧导出对象存储环境变量完整配置后才可用。
• 上传/下载预签名 URL 的有效期分别由 CONSOLE_EXPORT_FILE_UPLOAD_PRESIGN_TTL_SEC 和 CONSOLE_EXPORT_FILE_DOWNLOAD_PRESIGN_TTL_SEC 控制。
• 当 session_id 为 CU:<worker_id> 时，路由到该账号自有的指定 worker-sys 的 readImage capability，并以 action="export" 执行。
• 其他任意 session_id 会路由到持有该 terminal 会话的同一台 worker，并以 terminalResource 的 action="export" 执行。
• terminal 会话 worker 会先探测文件，再将文件从会话文件系统导出并通过预签名 HTTP PUT 上传，最后由 console 返回预签名下载 URL。
• worker 内部若出现非 JSON 的探针失败（例如 OCI / docker exec 启动失败），会直接作为工具错误返回 docker 退出码和输出摘要，不会再被包装成 JSON 解析错误。

入参示例：

{ "session_id": "sess_xxx", "file_path": "/workspace/report.png", "timeout_ms": 60000 }

入参示例（从 worker-sys 宿主机导出）：

{ "session_id": "CU:worker-id", "file_path": "/tmp/report.png", "timeout_ms": 10000 }

出参：

出参字段由环境变量 CONSOLE_EXPORT_RETURN_SCHEMA 控制：

出参示例（ALL 模式）：

{ "signed_url": "https://objectstore.example.com/bucket/exports/...", "object_key": "exports/sess_xxx/abc-report.png", "filename": "report.png" }

出参示例（SIGNED_URL 模式）：

{ "signed_url": "https://objectstore.example.com/bucket/exports/..." }

出参示例（OBJECTKEY 模式）：

{ "object_key": "exports/sess_xxx/abc-report.png", "filename": "report.png" }

常见约束：

• 未知会话会返回 session_not_found 等工具错误。
• 此工具不会以内联方式返回文件字节。

错误行为

旧公开别名 computerUse 不再具有特殊含义；客户端必须先列出/选择 Worker，再使用其 ID。Console 发给 worker-sys 的内部值仍保持 session_id="computerUse"。

另请参阅

• Console API 参考
• 安全与 FAQ