# Runtime Cloud MCP Runtime's MCP server gives an agent every Runtime product as tools, with instructions on first contact, so it needs no wrapper code. MCP and the HTTPS API share authentication, ownership, spending checks and idempotency. ## Add it to your agent One command, no key to copy. Claude Code: ```bash no-run claude mcp add --scope user runtime -- npx -y withruntime mcp ``` Codex: ```bash no-run codex mcp add runtime -- npx -y withruntime mcp ``` or, in `~/.codex/config.toml`: ```toml [mcp_servers.runtime] command = "npx" args = ["-y", "withruntime", "mcp"] ``` Cursor, in `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project), and any other client that takes the same shape: ```json { "mcpServers": { "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] } } } ``` The first time, when this machine is not connected, the server offers one tool, `runtime_connect`. The agent calls it and shows you a link and a code; you approve **Connect agent** in your browser, the agent calls it again, and every Runtime tool appears. Nothing to restart. A machine already connected by the CLI (`npx withruntime login`) skips this step. Approve only a connection you started and whose code matches. It can manage resources and spend prepaid credit across your account until you revoke it with `npx withruntime logout` or on the API keys page. The command is a bridge: it forwards MCP messages as they are to the remote server over the saved connection, so no key sits in the agent's configuration, and it adds no dependencies. For CI, `RUNTIME_API_KEY` from a secret manager overrides the saved connection. It needs Node 22 or later, and it does not create an account. ## Remote connection Clients that speak MCP over HTTP can skip the bridge. The endpoint is `https://api.withruntime.com/mcp`, over MCP Streamable HTTP, with an `Authorization: Bearer ` header. Create a key at https://withruntime.com/account/keys and supply it from a secret manager. Never put it in the URL, a command line, a browser bundle or a configuration you commit. ## Tools The server answers `initialize` with instructions: the quick start, safe retries, and how to report problems. Read them, then inspect tool results rather than assuming a completed tool call means the workload succeeded. Forking and creating catalog snapshots are currently unavailable (`fork_unavailable`); pause and wake remain supported. The tools describe the interface, but a listed tool is not a promise that its capability is enabled. Check the [products page](./products) for availability. | Tool | What it does | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | `runtime_sandboxes_create` | Create a sandbox and wait for readiness; inspect its returned state. | | `runtime_sandboxes_list` | List by state, name or label, or read one by id | | `runtime_sandboxes_manage` | Stop, pause, wake, extend; retention, persist, restart | | `runtime_sandboxes_inspect` | A sandbox's storage, paused storage, lifetime or recovery point | | `runtime_exec` | Run a command and get its exit code and output, or start it in the background | | `runtime_process` | Read, feed, signal or list background processes | | `runtime_files_read`, `runtime_files_write` | Read (whole or by line range) and write files | | `runtime_files_list`, `runtime_files_manage` | List and glob; stat, make, move and remove | | `runtime_interpreter_run`, `runtime_interpreter_contexts` | A notebook-style Python or JavaScript session; charts as images | | `runtime_images_build`, `_get`, `_delete` | Custom images from a recipe, a public image or a Dockerfile | | `runtime_volumes_create`, `_get`, `_delete` | Persistent disks to attach at create | | `runtime_sandboxes_fork` | Currently unavailable; returns `fork_unavailable` | | `runtime_snapshots_create` | Currently unavailable; returns `fork_unavailable` | | `runtime_snapshots_get`, `_delete` | Read, list or delete existing snapshot records | | `runtime_previews_create`, `_list`, `_delete` | Share a port at an HTTPS address at `runtimehost.com`, private with a token by default | | `runtime_network_policies_get`, `_set` | Read or replace a sandbox's network rules | | `runtime_desktops_act`, `runtime_desktops_screenshot` | Drive a desktop in the sandbox | | `runtime_account_get` | The account, its trial time and its credit | | `runtime_referrals_get` | Your referral link and the credit it has earned (you both get up to $500) | | `runtime_limits_get` | Whether this key is read-only, and its daily spending limit with what is left | | `runtime_feedback_submit`, `runtime_feedback_list` | Report a problem or a missing feature; see what happened to it | | `runtime_support_message`, `runtime_support_read` | Ask Runtime support | | `runtime_notices`, `runtime_secrets`, `runtime_jobs`, `runtime_services` | Account notices, secrets, scheduled jobs and managed data services; each takes an `action` | | `runtime_docs_read` | Read any page of these docs | Tool names read `runtime__`, or `runtime_` with an `action`. Results come back as both text and `structuredContent`. An error is a tool result with `isError`, a code, a hint and a `requestId`. ## A typical session 1. Choose a unique `idempotencyKey` before creating. Call `runtime_sandboxes_create` with `funding: "trial"` and that key. Check that the returned state is `running` before executing anything. Trial funding never falls back to paid credit. 2. `runtime_files_write`, then `runtime_exec` with `{"id": "", "command": "python3 main.py"}`. Give each write that accepts `idempotencyKey` its own key; do not add unsupported fields to other tools. Check `exitCode`, `timedOut`, output and truncation flags; tool or HTTP success alone does not prove program success. 3. For a server or a long job, `runtime_exec` with `"background": true`, then `runtime_process` with `"action": "read"` to follow its output. 4. `runtime_sandboxes_manage` with `"action": "stop"` when done, even if a step failed. Confirm `stopped` before reporting cleanup complete. Export needed outputs before stopping. When a tool accepts `idempotencyKey`, choose and record a unique key **before the first call** and pass it explicitly. After a lost reply, reuse that key with identical input. A key the server generated for an omitted field cannot be recovered from a lost reply; do not repeat that write blindly. Read the original resource first. The SDKs keep their own retry key during a call; this guidance is for direct MCP calls. Follow error codes and hints. Back off with a bounded deadline on `no_capacity`, `busy`, or `host_unavailable`; keep the original write key and input. Do not keep retrying `fork_unavailable`, `previews_unavailable`, or `unavailable`: those capabilities are switched off. If a create stops before becoming ready, read that sandbox's `stopReason` and report the failure; do not call it running or loop over new creates. For support or feedback, send a sanitized summary and request ID, never credentials or private code and file contents. ## Pause and wake `runtime_sandboxes_manage` with `"action": "pause"` saves files and memory, and `"wake"` restores them on the same host. Missing memory images refuse wake; a fresh boot is never silently substituted. Each sandbox keeps only its latest state, not a history of billed snapshots. A full host can refuse a wake; the paused data remains and no compute is charged for the failed attempt. See [pricing](./pricing) for paused storage and retention.