Skip to main content

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.

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

FieldValue
Endpointhttps://core.cyberun.cloud/api/v1/mcp
TransportStreamable HTTP (single endpoint, POST + GET + DELETE)
AuthAuthorization: Bearer sk-… (integration credential)
Server namecyberun-cloud
Server titleCyberun Cloud
Capabilitiestools.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.
  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. 
claude mcp add --transport http cyberun \
  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

ToolInputsDescription
list_workflowscurrent_page (int, optional), per_page (int, optional)List workflow templates the team has access to, paginated.
get_workflowworkflow_id (UUID, required)Fetch a workflow’s full schema, including parameters and defaults.
get_workflow_by_slugworkflow_slug (string, required — slug or slug@version)Same as get_workflow, but addressed by human-readable slug.
presign_file_uploadbody (object — file metadata)Get a presigned S3 PUT URL for uploading a file that a workflow will consume as input.

​
Tasks

ToolInputsDescription
run_workflowworkflow_id (UUID, required), body (object, optional — workflow parameters)Submit a workflow for execution. Returns { task_id }.
run_workflow_by_slugworkflow_slug (string, required), body (object, optional)Submit by slug instead of UUID.
list_taskscurrent_page (int, optional), per_page (int, optional), status (enum, optional — pending · waiting · queued · running · completed · failed · cancelled)List the team’s recent tasks.
get_tasktask_id (UUID, required)Read current task state. Poll while non-terminal.
get_task_resulttask_id (UUID, required)Fetch the output (or error) of a finished task. Call after status is completed or failed.
cancel_tasktask_id (UUID, required)Cancel a non-terminal task. No-op on already-finished tasks.
stream_task_eventstask_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

ToolInputsDescription
list_agentscurrent_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_serviceservice_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_serviceservice_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: 
{
  "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.

​
See also