DocumentationAccount

MCP

Your agent. Runtime’s tools.

Connect once. Let your agent discover the tools it needs.

Your agentRuntime MCPSandbox

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.

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 <key> 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.

Add it to your agent

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

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 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_<product>_<verb>, or runtime_<product> 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": "<sandbox 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 for paused storage and retention.

Was this page right?