> ## 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
> Connect any MCP client to Cyberun Cloud and drive the team’s workflows, tasks, agents, and container services.
The Cloud MCP server is hosted at:
```
https://core.cyberun.cloud/api/v1/mcp
```
It speaks **Streamable HTTP** as defined in the MCP spec
(`2025-06-18` and later). It wraps Cyberun's runtime API, so any
MCP-aware client — Claude Code, Cursor, Windsurf, Codex CLI,
VS Code 1.101+, Claude Desktop — can list workflows, submit
tasks, stream progress, fetch results, and cancel runs without
hitting REST directly.
## Server info
| Field | Value |
| ------------ | ------------------------------------------------------ |
| Endpoint | `https://core.cyberun.cloud/api/v1/mcp` |
| Transport | Streamable HTTP (single endpoint, POST + GET + DELETE) |
| Auth | `Authorization: Bearer sk-…` (integration credential) |
| Server name | `cyberun-cloud` |
| Server title | Cyberun Cloud |
| Capabilities | `tools.listChanged` |
## Get a credential
The server accepts **integration credentials** only — keys with
the `sk-` prefix. Device (`dk-`) and agent (`ak-`) credentials
are rejected.
Issue one in Cyberun Cloud:
1. Sign in at [app.cyberun.cloud](https://app.cyberun.cloud).
2. Open **Access → Integration**.
3. Click **Create integration key** and copy the value — it is
shown once.
4. Store it in your secret manager (1Password, macOS Keychain,
environment variable, etc.).
The team scope is bound to the credential at issue time. MCP
requests do not need an `X-Team-ID` header.
## Connect
Replace `$CYBERUN_API_KEY` with your `sk-…` credential or read
it from the environment.
```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}"
]
}
}
}
```
The `mcp-remote` shim is only needed for clients that don't yet
support native Streamable HTTP MCP. Recent Windsurf, Cursor, and
VS Code releases all support the native form above.
After registering the server, restart the client. Cyberun tools
appear in the tool picker.
## Tools
Fifteen tools are exposed. All operations are scoped to the team
bound to the integration credential.
### Workflows
| Tool | Inputs | Description |
| ---------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `list_workflows` | `current_page` (int, optional), `per_page` (int, optional) | List workflow templates the team has access to, paginated. |
| `get_workflow` | `workflow_id` (UUID, required) | Fetch a workflow's full schema, including parameters and defaults. |
| `get_workflow_by_slug` | `workflow_slug` (string, required — `slug` or `slug@version`) | Same as `get_workflow`, but addressed by human-readable slug. |
| `presign_file_upload` | `body` (object — file metadata) | Get a presigned S3 PUT URL for uploading a file that a workflow will consume as input. |
### Tasks
| Tool | Inputs | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `run_workflow` | `workflow_id` (UUID, required), `body` (object, optional — workflow parameters) | Submit a workflow for execution. Returns `{ task_id }`. |
| `run_workflow_by_slug` | `workflow_slug` (string, required), `body` (object, optional) | Submit by slug instead of UUID. |
| `list_tasks` | `current_page` (int, optional), `per_page` (int, optional), `status` (enum, optional — `pending` · `waiting` · `queued` · `running` · `completed` · `failed` · `cancelled`) | List the team's recent tasks. |
| `get_task` | `task_id` (UUID, required) | Read current task state. Poll while non-terminal. |
| `get_task_result` | `task_id` (UUID, required) | Fetch the output (or error) of a finished task. Call after status is `completed` or `failed`. |
| `cancel_task` | `task_id` (UUID, required) | Cancel a non-terminal task. No-op on already-finished tasks. |
| `stream_task_events` | `task_id` (UUID, required), `timeout_seconds` (int, optional — default 300, max 3600) | Subscribe to a task and receive MCP `notifications/progress` events as it advances. Returns the terminal `task` object when complete. |
### Agents and container services
| Tool | Inputs | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list_agents` | `current_page` (int, optional), `per_page` (int, optional) | List connected agents and their health. |
| `list_container_services` | (none) | List container services deployed to the team's agents. |
| `get_container_service` | `service_slug` (string, required) | Get a single container service's URL, status, and exposed ports. Includes `usage_prompt` (AI-facing description written by the service author) and `openapi_url` (path on the container that serves an OpenAPI spec) when set. |
| `call_container_service` | `service_slug` (string, required), `method` (`GET` · `POST` · `PUT` · `PATCH` · `DELETE` · `HEAD` · `OPTIONS`), `path` (string, required), `body_base64` (string, optional), `headers` (object, optional) | Send an HTTP request through the gateway tunnel to a running container service. Returns the container's response with `status_code`, `headers`, and `body_base64`. |
#### Calling container services
A team can deploy any HTTP service (Ollama, vLLM, a custom Flask
app, etc.) as a **container service**. Once running, MCP agents
discover and call it without leaving the MCP transport:
1. `list_container_services` → find a slug whose `service_status`
is `running`.
2. `get_container_service` with that slug → read `usage_prompt`
(free-form instructions for AI agents — e.g. "POST `/api/generate`
with `{model, prompt}`. Models available: llama3, qwen2.") and
`openapi_url` if set.
3. `call_container_service` with `service_slug`, `method`, `path`,
and `body_base64` for the body (base64 so binary payloads survive
JSON transport — use an empty string for `GET`/`DELETE`).
The response's `body_base64` is also base64-encoded; decode it
before passing JSON back to the model.
Calling a container service requires the **invoke** permission on
the team's container-service resource. Viewer-role members can
list and read services but cannot invoke them. Members and above
can invoke.
## Task lifecycle
Tasks move through these states:
```
pending → waiting → queued → running → completed
↘ failed
↘ cancelled
```
A task in `pending`, `waiting`, `queued`, or `running` can be
cancelled with `cancel_task`. Tools that block on completion
(`stream_task_events`) return when the task reaches `completed`,
`failed`, or `cancelled`.
## Errors
Tool errors are surfaced inside the result envelope (not as
JSON-RPC errors), following the MCP spec. When the underlying
request fails with status `>= 400`, the tool result has
`isError: true`, and the upstream error body is returned both as
a text content block and as `structuredContent`. The body is a
flat object with a single `error_message` field:
```json theme={null}
{
"isError": true,
"content": [
{ "type": "text", "text": "{\"error_message\":\"human-readable error\"}" }
],
"structuredContent": {
"error_message": "human-readable error"
}
}
```
A `401` from the server means the credential is invalid, revoked,
or expired — don't retry; the user needs to issue a fresh key.
A `403` means the credential is valid but lacks permission for
the operation (e.g. only team admins can run some tools). A `429`
means you're being rate-limited — back off.
## Streaming progress
`stream_task_events` honours the standard MCP `progressToken`.
Include one in your `tools/call` request and the server will
emit `notifications/progress` for each task status transition
until the task reaches a terminal state. Sample notification:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "notifications/progress",
"params": {
"progressToken": "",
"progress": 0.6,
"message": "task running on agent_01HX..."
}
}
```
For clients that don't support progress notifications, the tool
still blocks until the task reaches a terminal state and returns
the final task object — `timeout_seconds` caps how long it will
wait.
## Limits
* One MCP session per credential at a time is the normal case.
The server tolerates multiple parallel sessions; expect them
to share the same team's task list.
* Tool inputs are validated against their schemas. Invalid input
comes back as `isError: true` rather than a JSON-RPC error.
* Sessions time out after 30 minutes of inactivity. Clients
re-establish transparently.
## See also
* [AI skill](/skill) — installable agent skill that teaches AI
clients to use this server correctly.
* [API reference](/api-reference/introduction) — the underlying
HTTP surface MCP wraps.
* [Cloud → Generate an API key](/cloud/guides/api-key) — how to
create the `sk-…` credential.