# How to add Runtime to Cursor with MCP

Add a `runtime` server that runs `npx -y withruntime mcp` to `~/.cursor/mcp.json`.
Then approve the link that Cursor's agent shows you.

**With Runtime in Cursor, the agent runs builds, tests and servers in a
Firecracker microVM with its own kernel, not on your laptop. 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 that is waiting on the model
costs $0.03125 an hour. A new account gets 100 free hours of a 1 GB machine in its first 30 days, as of 25 October 2026 ([pricing](/docs/pricing)).

## Option 1: the local bridge

Put this in `~/.cursor/mcp.json` to use it in every project. To use it in one
project only, put it in `.cursor/mcp.json` at that 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. The file holds no secret, so it is safe
to commit in a project. The bridge needs Node 22.12 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 that the code matches,
   and approve **Connect agent**.
3. The agent calls the tool again, and every Runtime tool appears. No restart
   is needed.

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. The key is listed
on [API keys](https://withruntime.com/account/keys). Choose this option 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.

By default, Cursor asks before it runs each MCP tool, and it shows the
arguments. The tools that the agent uses most:

| Tool                                     | Use in a coding session                                        |
| ---------------------------------------- | -------------------------------------------------------------- |
| `runtime_sandboxes_create`               | A fresh machine per task; `getOrCreate` with a name reuses one |
| `runtime_sandboxes_exec`                 | Build and test; `"background": true` for a dev server          |
| `runtime_sandboxes_process`              | Follow a background server's output                            |
| `runtime_sandboxes_files_write`, `_read` | Move code and results in and out                               |
| `runtime_sandboxes_previews`             | An HTTPS address to open the running app                       |
| `runtime_sandboxes_manage`               | Pause between tasks, wake, stop                                |
| `runtime_sandboxes_fork`                 | Up to 100 running copies to try fixes side by side |

## Mistakes and how Runtime handles them

- **Putting a key in `mcp.json`.** A key is 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 version.** The bridge needs Node 22.12 or later. Check with
  `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 the limit, 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 tool.
- **Sandboxes without credit and SSH clones.** A sandbox without credit reaches
  ports 80 and 443 only. 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 October 2026.

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

Facts on this page were checked on 25 October 2026.