Runtime

How to add Runtime to Cursor with MCP

Add a runtime server running npx -y withruntime mcp to ~/.cursor/mcp.json, then approve the link Cursor's agent shows you.

With Runtime in Cursor, the agent runs builds, tests and servers in a Firecracker microVM with its own kernel instead of on your laptop, and no API key goes into the config. The first tool call prints a link and a code; one browser approval connects it. A 2 vCPU, 4 GiB sandbox waiting on the model costs $0.03125 an hour, and new accounts get 50 free hours, as of 25 September 2026 (pricing).

Option 1: the local bridge

Put this in ~/.cursor/mcp.json for every project, or .cursor/mcp.json in one project's root:

JSON{  "mcpServers": {    "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] }  }}

The command is a bridge. It forwards MCP messages to Runtime's remote server over this machine's saved connection, so the file holds no secret and is safe to commit in a project. It needs Node 22 or later.

The first time:

  1. Cursor's agent sees one tool, runtime_connect, and calls it.
  2. It shows you a link and a code. Open the link, check the code matches and approve Connect agent.
  3. The agent calls it again and every Runtime tool appears, with no restart.

A machine already connected with npx withruntime login skips this step.

Option 2: the remote server

Cursor also takes a URL. Runtime's endpoint speaks MCP Streamable HTTP and signs in through the browser:

JSON{  "mcpServers": {    "runtime": { "url": "https://api.withruntime.com/mcp" }  }}

Cursor opens a Runtime page; sign in and approve Connect for Cursor. The key it receives belongs to a new agent named after the app and is listed on API keys. Choose this when you would rather not run Node locally.

Which one to choose

You want Use
One connection shared with the CLI and Claude Code on this machine The bridge
A config file checked into a team repository The bridge (no secret in it)
No local Node process The remote server

Ask for work

Enable the server from Customize in Cursor's sidebar, then ask in the chat:

Start a Runtime sandbox, clone this repo into it over HTTPS, run the test suite and tell me which tests fail. Stop the sandbox afterwards.

Cursor asks before it runs each MCP tool by default, showing the arguments. The tools the agent reaches for:

Tool Use in a coding session
runtime_sandbox_create A fresh machine per task; getOrCreate with a name reuses one
runtime_sandbox_exec Build and test; "background": true for a dev server
runtime_sandbox_process Follow a background server's output
runtime_sandbox_files_write, _read Move code and results in and out
runtime_sandbox_previews_create An HTTPS address to open the running app
runtime_sandbox_manage Pause between tasks, wake, stop
runtime_sandbox_fork Up to 10 running copies to try fixes side by side

Mistakes and how Runtime handles them

  • Putting a key in mcp.json. Not needed, and a committed key leaks. The bridge uses the saved connection; for CI, RUNTIME_API_KEY from a secret manager overrides it.
  • An old Node. The bridge needs Node 22 or later. Check node --version, or use the remote server, which needs no Node.
  • Approving a link you did not request. Match the code the agent showed you. A connection can spend prepaid credit across the account until you revoke it with npx withruntime logout or on the API keys page.
  • Unbounded agent spend. Set a daily spending limit on the connection's row at API keys; past it, requests fail with spending_limit_reached and charge nothing.
  • Tool names in rules from before 24 September 2026. Tools were renamed to runtime_<product>_<verb>. Restart the agent so Cursor lists them again, and update any rule that names an old one.
  • Trial sandboxes and SSH clones. A trial sandbox reaches ports 80 and 443 only, so tell the agent to clone over HTTPS.

Sources

Checked 25 September 2026.

Facts on this page were checked on 25 September 2026.

Claim 50 hours free