> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Cloud MCP
> 将任意 MCP 客户端连接到 Cyberun Cloud,驱动团队的工作流、任务、代理和容器服务。
Cloud MCP 服务器托管在:
```
https://core.cyberun.cloud/api/v1/mcp
```
它使用 MCP 规范(`2025-06-18` 及以后)定义的 **Streamable HTTP**。它封装了 Cyberun 的运行时 API,任何支持 MCP 的客户端 —— Claude Code、Cursor、Windsurf、Codex CLI、VS Code 1.101+、Claude Desktop —— 都可以列出工作流、提交任务、流式接收进度、获取结果、取消运行,而无需直接打到 REST。
## 服务器信息
| 字段 | 值 |
| ------------ | ---------------------------------------- |
| 端点 | `https://core.cyberun.cloud/api/v1/mcp` |
| 传输 | Streamable HTTP(单端点,POST + GET + DELETE) |
| 鉴权 | `Authorization: Bearer sk-…`(集成凭证) |
| Server name | `cyberun-cloud` |
| Server title | Cyberun Cloud |
| Capabilities | `tools.listChanged` |
## 获取凭证
服务器**仅**接受集成凭证 —— 带 `sk-` 前缀的密钥。设备凭证(`dk-`)和代理凭证(`ak-`)都会被拒绝。
在 Cyberun Cloud 中签发:
1. 在 [app.cyberun.cloud](https://app.cyberun.cloud) 登录。
2. 打开**访问 → 集成**。
3. 点击**创建集成密钥**并复制其值 —— 只显示一次。
4. 存入密钥管理工具(1Password、macOS 钥匙串、环境变量等)。
团队范围在签发时绑定到凭证。MCP 请求不需要 `X-Team-ID` 请求头。
## 连接
把 `$CYBERUN_API_KEY` 替换为你的 `sk-…` 凭证,或从环境读取。
```bash Claude Code (CLI) theme={null}
claude mcp add --transport http cyberun \
https://core.cyberun.cloud/api/v1/mcp \
--header "Authorization: Bearer $CYBERUN_API_KEY"
```
```json Claude Desktop / Code (config) theme={null}
{
"mcpServers": {
"cyberun": {
"url": "https://core.cyberun.cloud/api/v1/mcp",
"headers": {
"Authorization": "Bearer ${CYBERUN_API_KEY}"
}
}
}
}
```
```json Cursor (.cursor/mcp.json) theme={null}
{
"mcpServers": {
"cyberun": {
"url": "https://core.cyberun.cloud/api/v1/mcp",
"headers": {
"Authorization": "Bearer ${CYBERUN_API_KEY}"
}
}
}
}
```
```json VS Code 1.101+ (.vscode/mcp.json) theme={null}
{
"servers": {
"cyberun": {
"type": "http",
"url": "https://core.cyberun.cloud/api/v1/mcp",
"headers": {
"Authorization": "Bearer ${CYBERUN_API_KEY}"
}
}
}
}
```
```bash Codex CLI (one-shot) theme={null}
codex mcp add cyberun \
--url https://core.cyberun.cloud/api/v1/mcp \
--bearer-token-env-var CYBERUN_API_KEY
```
```toml Codex CLI (~/.codex/config.toml) theme={null}
[mcp_servers.cyberun]
url = "https://core.cyberun.cloud/api/v1/mcp"
bearer_token_env_var = "CYBERUN_API_KEY"
```
```json Windsurf / generic stdio shim theme={null}
{
"mcpServers": {
"cyberun": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://core.cyberun.cloud/api/v1/mcp",
"--header",
"Authorization: Bearer ${CYBERUN_API_KEY}"
]
}
}
}
```
`mcp-remote` shim 仅在尚未原生支持 Streamable HTTP MCP 的客户端中需要。最近的 Windsurf、Cursor 和 VS Code 版本都支持上面的原生形式。
注册服务器后重启客户端。Cyberun 工具会出现在工具选择器中。
## 工具
共 15 个工具。所有操作都限定在与集成凭证绑定的团队中。
### 工作流
| 工具 | 输入 | 描述 |
| ---------------------- | ----------------------------------------------------- | ----------------------------------- |
| `list_workflows` | `current_page`(int,可选)、`per_page`(int,可选) | 列出团队可访问的工作流模板,分页。 |
| `get_workflow` | `workflow_id`(UUID,必填) | 获取工作流的完整 schema,包含参数和默认值。 |
| `get_workflow_by_slug` | `workflow_slug`(string,必填 —— `slug` 或 `slug@version`) | 同 `get_workflow`,但按可读 slug 寻址。 |
| `presign_file_upload` | `body`(object —— 文件元数据) | 获取预签名 S3 PUT URL,用于上传工作流将作为输入消费的文件。 |
### 任务
| 工具 | 输入 | 描述 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `run_workflow` | `workflow_id`(UUID,必填)、`body`(object,可选 —— 工作流参数) | 提交工作流执行。返回 `{ task_id }`。 |
| `run_workflow_by_slug` | `workflow_slug`(string,必填)、`body`(object,可选) | 按 slug 而非 UUID 提交。 |
| `list_tasks` | `current_page`(int,可选)、`per_page`(int,可选)、`status`(enum,可选 —— `pending` · `waiting` · `queued` · `running` · `completed` · `failed` · `cancelled`) | 列出团队最近的任务。 |
| `get_task` | `task_id`(UUID,必填) | 读取当前任务状态。非终态时轮询。 |
| `get_task_result` | `task_id`(UUID,必填) | 获取已结束任务的输出(或错误)。在状态为 `completed` 或 `failed` 后调用。 |
| `cancel_task` | `task_id`(UUID,必填) | 取消非终态任务。对已结束任务无操作。 |
| `stream_task_events` | `task_id`(UUID,必填)、`timeout_seconds`(int,可选 —— 默认 300,最大 3600) | 订阅任务,在其推进时接收 MCP `notifications/progress` 事件。完成时返回终态 `task` 对象。 |
### 代理与容器服务
| 工具 | 输入 | 描述 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `list_agents` | `current_page`(int,可选)、`per_page`(int,可选) | 列出已连接的代理及其健康状态。 |
| `list_container_services` | (无) | 列出部署到团队代理上的容器服务。 |
| `get_container_service` | `service_slug`(string,必填) | 获取单个容器服务的 URL、状态和暴露端口。已设置时包含 `usage_prompt`(由服务作者撰写的面向 AI 的说明)和 `openapi_url`(容器上提供 OpenAPI 规范的路径)。 |
| `call_container_service` | `service_slug`(string,必填)、`method`(`GET` · `POST` · `PUT` · `PATCH` · `DELETE` · `HEAD` · `OPTIONS`)、`path`(string,必填)、`body_base64`(string,可选)、`headers`(object,可选) | 通过网关隧道向运行中的容器服务发送 HTTP 请求。返回容器的响应,含 `status_code`、`headers` 和 `body_base64`。 |
#### 调用容器服务
团队可以把任意 HTTP 服务(Ollama、vLLM、自定义 Flask 应用等)部署为**容器服务**。运行起来之后,MCP 代理无需离开 MCP 传输即可发现并调用:
1. `list_container_services` → 找到 `service_status` 为 `running` 的 slug。
2. 用该 slug 调用 `get_container_service` → 读取 `usage_prompt`(供 AI 代理的自由格式说明 —— 例如「POST `/api/generate`,带 `{model, prompt}`。可用模型:llama3、qwen2。」)以及已设置时的 `openapi_url`。
3. 用 `service_slug`、`method`、`path` 和 `body_base64` 调用 `call_container_service`(请求体用 base64,以便二进制载荷可经 JSON 传输 —— `GET`/`DELETE` 使用空字符串)。
响应的 `body_base64` 也是 base64 编码;在把 JSON 传回模型前先解码。
调用容器服务需要团队容器服务资源上的 **invoke** 权限。Viewer 角色的成员可以列出和读取服务,但不能调用。Member 及以上可以调用。
## 任务生命周期
任务在这些状态间推进:
```
pending → waiting → queued → running → completed
↘ failed
↘ cancelled
```
处于 `pending`、`waiting`、`queued` 或 `running` 的任务可以用 `cancel_task` 取消。阻塞至完成的工具(`stream_task_events`)在任务到达 `completed`、`failed` 或 `cancelled` 时返回。
## 错误
工具错误在结果信封内部呈现(不是作为 JSON-RPC 错误),遵循 MCP 规范。当底层请求以状态 `>= 400` 失败时,工具结果的 `isError` 为 `true`,上游错误体会同时作为文本内容块和 `structuredContent` 返回。该错误体是一个扁平对象,只有一个 `error_message` 字段:
```json theme={null}
{
"isError": true,
"content": [
{ "type": "text", "text": "{\"error_message\":\"human-readable error\"}" }
],
"structuredContent": {
"error_message": "human-readable error"
}
}
```
服务器返回 `401` 表示凭证无效、已撤销或已过期 —— 不要重试;用户需要签发新密钥。`403` 表示凭证有效但缺少该操作的权限(例如只有团队管理员能运行某些工具)。`429` 表示被限速 —— 退避后再试。
## 流式进度
`stream_task_events` 遵循标准的 MCP `progressToken`。在你的 `tools/call` 请求中带上一个,服务器就会为每次任务状态转换发出 `notifications/progress`,直到任务到达终态。示例通知:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "notifications/progress",
"params": {
"progressToken": "",
"progress": 0.6,
"message": "task running on agent_01HX..."
}
}
```
对不支持进度通知的客户端,该工具仍会阻塞到任务到达终态并返回最终任务对象 —— `timeout_seconds` 限制最长等待时间。
## 限制
* 每个凭证一次正常只有一个 MCP 会话。服务器容忍多个并行会话;它们会共享同一团队的任务列表。
* 工具输入按其 schema 校验。无效输入以 `isError: true` 而非 JSON-RPC 错误返回。
* 会话在 30 分钟空闲后超时。客户端会透明地重建。
## 另请参阅
* [AI 技能](/skill)(仅英文)—— 可安装的代理技能,教会 AI 客户端正确使用此服务器。
* [API 参考](/zh/api-reference/introduction) —— MCP 封装的底层 HTTP 接口。
* [Cloud → 生成 API 密钥](/zh/cloud/guides/api-key) —— 如何创建 `sk-…` 凭证。