Runtime Cloud MCP

One command, no key to copy. Claude Code:

Terminalclaude mcp add --scope user runtime -- npx -y withruntime mcp

Codex:

Terminalcodex 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, one approval connects it. When this machine is not connected, the server offers one tool, runtime_connect:

1. The agent calls it and shows you a link and a code.
2. You approve Connect agent in your browser.
3. The agent calls it again, and every Runtime tool appears. The response carries the server's full instructions (limits, cleanup, safe retries). Before it connected, the agent had read only the short version. A client that does not refresh its tools when told shows them after the server or the client restarts. The connection is saved, so it connects immediately.

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. It needs Node 22.12 or later. It loads its one dependency, undici, only when a proxy applies. It does not create an account. For CI, RUNTIME_API_KEY from a secret manager overrides the saved connection.

Clients that speak MCP over HTTP can skip the bridge. The endpoint is https://api.withruntime.com/mcp, over MCP Streamable HTTP.

Sign in through the browser, with no key. Add the address as a custom connector or remote server, in Claude, ChatGPT, Cursor, VS Code or any client that supports MCP sign-in:

1. The client opens a Runtime page in your browser.
2. You sign in and approve Connect for that app. The page shows where the key goes, so check it is the app you are using.
3. The client receives a key of its own and every Runtime tool appears.

The key belongs to a new agent named after the app. It can manage resources and spend prepaid credit across your account until you revoke it on the API keys page, where it is listed with the app's name. A client that asks for scope runtime:read gets a read-only key.

Claude Code can do the same without the bridge:

Terminalclaude mcp add --transport http --scope user runtime https://api.withruntime.com/mcp

Then run /mcp in Claude Code and choose to authenticate.

Or send a key. A server or CI job sends Authorization: Bearer <key> with a key from https://withruntime.com/account/keys, supplied from a secret manager. Never put a key in the URL, a command line, a browser bundle or a configuration you commit.

Clients discover sign-in the standard way: a request with no key gets a 401 whose WWW-Authenticate header points at https://api.withruntime.com/.well-known/oauth-protected-resource/mcp, which names https://withruntime.com as the authorization server. It supports OAuth 2.1 with PKCE, dynamic client registration and client metadata documents.

For ChatGPT, use https://api.withruntime.com/mcp?profile=chatgpt. Its tools keep persistent credentials out of the conversation. Starting or reading a sandbox MCP server returns safe state and scoped preview links. When another client needs the server's gateway token or authorization headers, get them through the website or a local CLI. This profile also leaves out what a ChatGPT request does not need. The audit log, referrals, single sign-on settings and the price comparison are not listed. runtime_account returns usage and limits without names, internal identifiers or card details. The ordinary MCP connection keeps its usual credential behavior.

Only the docs? https://withruntime.com/mcp is a separate, public MCP server with no sign-in: it searches and reads these guides (search_runtime_docs, read_runtime_doc, list_runtime_docs) and runs nothing.

The server returns instructions in its initialize response: 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.

The tools describe the interface, but a listed tool is not a promise that its capability is enabled. Check the products page for availability.

Tool names read runtime_<product>_<verb>, or runtime_<product> for a tool that takes an action, the product spelled as the CLI spells it. The verbs an agent needs in its first session each have a tool of their own; a product's rarer verbs share one, and its action names the verb: runtime_volumes with "action": "get" reads a volume. Everything that acts on one sandbox is runtime_sandboxes_* and takes the sandbox as id (the MCP catalog needs none); runtime_sandboxes_mcp with action: "catalog" needs no id, while start, get and stop require it and name the missing field in an invalid_request error; images, volumes and snapshots are runtime_images*, runtime_volumes* and runtime_snapshots; what spans products, such as the account, usage, secrets, events, feedback and docs, names no product. Results come back as both text and structuredContent. An error is a tool result with isError, a code, a hint and a requestId.

On 26 September 2026, 52 tools became 16 that take an action, which cut the tool list's context cost for an agent by nearly a quarter. The old names now fail with not_found, before any operation runs, and the hint names the grouped tool and its action. Change any permission rule, prompt or script that names one, then refresh the tool list. runtime_sandboxes_mounts and runtime_volumes_backup keep their grouped names and require an action; an old call that omits it is refused.

On 24 September 2026 every tool took its product's name, as the CLI spells it, with no aliases: runtime_exec became runtime_sandboxes_exec, runtime_sandboxes_create became runtime_sandboxes_create, and so on. A call to one of those names fails, and its error names the call that replaces it.

1. Choose a unique idempotencyKey before creating. Call runtime_sandboxes_create with that key. Check that the returned state is running before executing anything. The free usage is spent first, then prepaid credit.
2. runtime_sandboxes_files_write, then runtime_sandboxes_exec with {"id": "<sandbox id>", "command": "python3 main.py"} (or "command": ["python3", "main.py"] to run it without a shell). Add "user": "root" to run it as root without sudo in front. 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. runtime_sandboxes_exec returns at most 64 KiB of stdout and of stderr for a command up to 60 seconds, 1 MiB for a longer one; stdoutTruncated or stderrTruncated is true when more was dropped. Over MCP, output over 16,000 characters in all keeps each stream's beginning and end within its share of the output budget; even a long first line may be shortened. Quotes, backslashes and control characters can shorten it further, because escaped output must also fit the complete serialized response budget. outputCut says how many characters of each were cut. When the result includes processId, read the existing process with runtime_sandboxes_process and "action": "read", using its output cursors. For a future command whose full output you need, save it to a file and read it in parts with runtime_sandboxes_files_read. Do not run a command again just to recover output: its changes may already have happened.
3. For a server or a long job, runtime_sandboxes_exec with "background": true, then runtime_sandboxes_process with "action": "read" to follow its output.
4. runtime_sandboxes_manage with "action": "delete" when done, even if a step failed. A stop keeps the disk, billed until it is deleted; delete unless the owner's task needs the sandbox again. Confirm it is gone before reporting cleanup complete. Export needed outputs before deleting.

Retries. 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, so 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.

Errors. Follow error codes and hints.

• Back off with a bounded deadline on no_capacity, busy or host_unavailable, keeping the original write key and input.
• Do not keep retrying fork_unavailable, previews_unavailable or unavailable: an operator has switched that capability 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.

runtime_sandboxes_manage with "action": "pause" saves files and memory, and "wake" restores them. Each sandbox keeps only its latest state, not a history of billed snapshots.

A wake never silently substitutes a fresh boot: missing memory images refuse it. A full host can also refuse a wake; the paused data remains and no compute is charged for the failed attempt. See pricing for paused storage and retention.

A paused sandbox also wakes by itself when runtime_sandboxes_exec, a file or terminal tool, or a visit to a shared port reaches it, unless it was created with autoWake: false. A sandbox pauses itself after 300 seconds with nothing happening in it. A process due on a timer also wakes a sandbox that paused for being idle, unless it has wakeOnTimers: false. "action": "update" changes autoWake, wakeOnTimers, idlePauseSeconds (60 to 86,400 seconds; 0 is never), name and labels; "persist" keeps a paid sandbox running while credit lasts. runtime_sandboxes_create with name and getOrCreate: true returns the sandbox that already has the name, woken if paused, instead of name_taken.

They need a kept top-up, and a dedicated address credit; see networking.

• runtime_domains (add, verify, list, remove): serve a sandbox's port at your own hostname.
• runtime_ports (open, list, close): a public TCP port to a sandbox.
• runtime_ips (reserve, list, release): a dedicated outbound address.
• runtime_networks_wireguard (create, get, add_peer, rotate_peer, remove_peer): the WireGuard tunnel. add_peer without publicKey generates the key pair and returns the private key once, in config.
• runtime_networks_upstream_proxy (get, set, remove): send the sandboxes' outbound connections through your own proxy.
• runtime_networks_private (get, set): with enabled: true, your sandboxes reach each other at <name>.sandbox.internal:<port> over TCP. Needs a kept top-up; free.
• runtime_networks_signed_requests (get, set): with enabled: true, your sandboxes can sign their HTTP requests as Runtime's agents with Web Bot Auth (how). Needs credit; free.