Cloud MCP - Cyberun

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 中签发:

在 app.cyberun.cloud 登录。
打开访问 → 集成。
点击创建集成密钥并复制其值 —— 只显示一次。
存入密钥管理工具(1Password、macOS 钥匙串、环境变量等)。

团队范围在签发时绑定到凭证。MCP 请求不需要 X-Team-ID 请求头。

连接

把 $CYBERUN_API_KEY 替换为你的 sk-… 凭证,或从环境读取。

claude mcp add --transport http cyberun \
  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 传输即可发现并调用:

list_container_services → 找到 service_status 为 running 的 slug。
用该 slug 调用 get_container_service → 读取 usage_prompt(供 AI 代理的自由格式说明 —— 例如「POST /api/generate,带 {model, prompt}。可用模型:llama3、qwen2。」)以及已设置时的 openapi_url。
用 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 字段:

{
  "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,直到任务到达终态。示例通知:

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "<your-token>",
    "progress": 0.6,
    "message": "task running on agent_01HX..."
  }
}

对不支持进度通知的客户端,该工具仍会阻塞到任务到达终态并返回最终任务对象 —— timeout_seconds 限制最长等待时间。

限制

每个凭证一次正常只有一个 MCP 会话。服务器容忍多个并行会话;它们会共享同一团队的任务列表。
工具输入按其 schema 校验。无效输入以 isError: true 而非 JSON-RPC 错误返回。
会话在 30 分钟空闲后超时。客户端会透明地重建。

另请参阅

AI 技能(仅英文)—— 可安装的代理技能,教会 AI 客户端正确使用此服务器。
API 参考 —— MCP 封装的底层 HTTP 接口。
Cloud → 生成 API 密钥 —— 如何创建 sk-… 凭证。

Documentation Index

​服务器信息

​获取凭证

​连接

​工具

​工作流

​任务

​代理与容器服务

​调用容器服务

​任务生命周期

​错误

​流式进度

​限制

​另请参阅