Cloud MCP

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:

Sign in at app.cyberun.cloud.
Open Access → Integration.
Click Create integration key and copy the value — it is shown once.
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.

claude mcp add --transport http cyberun \
  https://core.cyberun.cloud/api/v1/mcp \
  --header "Authorization: Bearer $CYBERUN_API_KEY"

{
  "mcpServers": {
    "cyberun": {
      "url": "https://core.cyberun.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${CYBERUN_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "cyberun": {
      "url": "https://core.cyberun.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${CYBERUN_API_KEY}"
      }
    }
  }
}

{
  "servers": {
    "cyberun": {
      "type": "http",
      "url": "https://core.cyberun.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${CYBERUN_API_KEY}"
      }
    }
  }
}

codex mcp add cyberun \
  --url https://core.cyberun.cloud/api/v1/mcp \
  --bearer-token-env-var CYBERUN_API_KEY

[mcp_servers.cyberun]
url = "https://core.cyberun.cloud/api/v1/mcp"
bearer_token_env_var = "CYBERUN_API_KEY"

{
  "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:

list_container_services → find a slug whose service_status is running.
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.
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:

{
  "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:

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "<your-token>",
    "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.

Overview

Servers

Skill

Server info

Get a credential

Connect

Tools

Workflows

Tasks

Agents and container services

Calling container services

Task lifecycle

Errors

Streaming progress

Limits

See also

​Server info

​Get a credential

​Connect

​Tools

​Workflows

​Tasks

​Agents and container services

​Calling container services

​Task lifecycle

​Errors

​Streaming progress

​Limits

​See also

Server info

Get a credential

Connect

Tools

Workflows

Tasks

Agents and container services

Calling container services

Task lifecycle

Errors

Streaming progress

Limits

See also