# 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](/docs/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](https://withruntime.com/account/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.

## Related

- [How to add Runtime to Claude.ai](/how-to/add-runtime-to-claude-ai)
- [Codex in a sandbox](/integrations/codex) and
  [Claude Code in a sandbox](/integrations/claude-code)
- [A coding agent sandbox](/use-cases/coding-agent-sandbox)
- [Frameworks: coding agents](/docs/frameworks#coding-agents)

## Sources

Checked 25 September 2026.

- [Cursor: Model Context Protocol](https://cursor.com/docs/context/mcp)

Facts on this page were checked on 25 September 2026.