# Local or Hosted MCP for Cursor, Claude Code and Codex?

> Use the hosted server at https://sandboxer.com/mcp if you want nothing to install, browser sign-in, or web clients like claude.ai and ChatGPT. Use the local stdio server (sbx mcp or npx -y sandboxer-mcp) if you want default sizes and auto-stop for every sandbox, or the handoff_session tool. Both create the same cloud microVMs.

Source: https://sandboxer.com/guides/local-or-hosted-mcp-for-cursor-claude-code-codex. Updated 2026-10-27.

**Short answer:** Use the hosted server at https://sandboxer.com/mcp if you want nothing to install, browser sign-in, or web clients like claude.ai and ChatGPT. Use the local stdio server (sbx mcp or npx -y sandboxer-mcp) if you want default sizes and auto-stop for every sandbox, or the handoff_session tool. Both create the same cloud microVMs.

## The decision

Both servers call the same Sandboxer API, so the sandboxes are the same: Ubuntu microVMs that run in Sandboxer's cloud, never on your laptop. The difference is where the MCP process runs and how it signs in.

| | Hosted (`https://sandboxer.com/mcp`) | Local stdio (`sbx mcp` / `npx -y sandboxer-mcp`) |
| - | - | - |
| Transport | Streamable HTTP | stdio (the client starts it as a subprocess) |
| Install | Nothing | The `sbx` CLI, or Node for `npx` |
| Auth | Browser sign-in (OAuth), or `Authorization: Bearer <key>` | `sbx login`, or `SANDBOXER_API_KEY` in the server's environment |
| Works in claude.ai and ChatGPT | Yes | No (web clients can't start a local process) |
| Tools | 18 | 19: the same 18 plus `handoff_session` |
| Defaults for new sandboxes | Set by the agent per call | `--type` and `--ttl` flags apply to every create |
| Connect (our runs, 2026-10-27) | `initialize` 92–98 ms | `sbx mcp`: 2 ms. `npx`: 330–345 ms warm, 5.4–6.5 s on the first run (it downloads `sbx`) |
| Each tool call (our runs, 2026-10-27) | `list_sandboxes` 29–31 ms | First call 96–101 ms, then 28–29 ms |

Pick hosted when you switch between machines, use a web client, or don't want a binary on your `PATH`. Pick local when the CLI is already installed and signed in, when you want `sbx mcp --type small --ttl 1800` to cap what the agent creates, or when you want the agent to move its own Claude Code or Codex session into a sandbox with `handoff_session`.

## What we measured

We drove both servers with raw JSON-RPC from a laptop in Miami against production on 2026-10-27 (a few runs each, so treat the numbers as single measurements, not benchmarks), with an API key in `SANDBOXER_API_KEY`. The local server, through `npx`:

```text
sandboxer-mcp: downloading sbx-linux-amd64 (72eab2e) from https://sandboxer.com/dl
initialize: 5368 ms (including process start) {"name":"sandboxer","title":"Sandboxer","version":"72eab2e"} protocol 2025-06-18
tools/list: 0 ms 19 tools: create_sandbox, list_sandboxes, get_sandbox, exec, … delete_snapshot, handoff_session
list_sandboxes: 98 ms
list_sandboxes: 29 ms
list_sandboxes: 29 ms
create_sandbox: 6148 ms Sandbox sb_rv6rdw14df is ready. URL: https://slick-pacific-pelican.box.sandboxer.com. …
exec: 142 ms "Exit code 0.\n\nstdout:\nLinux 6.18.56-sandboxer\n2"
delete_sandbox: 30 ms Deleting sb_rv6rdw14df: its disk, memory and automatic snapshots are removed.
```

The hosted server, with the key sent as a bearer token:

```text
no key: 401 WWW-Authenticate: Bearer resource_metadata="https://sandboxer.com/.well-known/oauth-protected-resource/mcp", scope="sandboxer"
initialize: 95 ms 200 application/json {"name":"sandboxer","title":"Sandboxer","version":"72eab2e"} protocol 2025-06-18 session: yes
tools/list: 31 ms 18 tools: create_sandbox, list_sandboxes, get_sandbox, exec, … list_snapshots, delete_snapshot
list_sandboxes: 31 ms
create_sandbox: 3040 ms Sandbox sb_0wy9k097ht is ready. URL: https://witty-orange-saffron.box.sandboxer.com. …
exec: 150 ms "Exit code 0.\n\nstdout:\nLinux 6.18.56-sandboxer\n2"
delete_sandbox: 31 ms Deleting sb_0wy9k097ht: its disk, memory and automatic snapshots are removed.
```

What this means in practice:

- **Per-call speed is the same.** After the first call, both took about 30 ms. The local server's first call is slower because it opens a TLS connection to the API.
- **`npx` costs startup time.** Each launch spends about a third of a second resolving the package, and the first launch downloads `sbx`. The client pays this once per session.
- **Sandbox creation dominates.** `create_sandbox` took 3 to 6 seconds in the runs shown, either way, and depends on the machine, not the transport. One earlier hosted create, while the shared test account was under heavy load, took 63 seconds.
- **The unauthenticated `401` is how OAuth starts.** Clients read `resource_metadata` and open the sign-in page.

## Claude Code

Claude Code's syntax is in [its MCP docs](https://code.claude.com/docs/en/mcp). Hosted, signing in with your Sandboxer account:

```bash
claude mcp add --transport http --scope user sandboxer https://sandboxer.com/mcp
# then, inside Claude Code: /mcp, choose sandboxer, and sign in
```

Local, using your `sbx login`, with defaults for every sandbox the agent creates:

```bash
claude mcp add --scope user sandboxer -- sbx mcp --type small --ttl 1800
```

Local without the CLI. Claude Code passes its own environment to stdio servers (we checked), so export `SANDBOXER_API_KEY` in the shell that starts `claude`:

```bash
claude mcp add --scope user sandboxer -- npx -y sandboxer-mcp
```

Hosted with a key, shared with a project in `.mcp.json`. The single quotes keep `${SANDBOXER_API_KEY}` literal, and Claude Code fills it in from the environment, so the key never lands in the file:

```bash
claude mcp add-json --scope project sandboxer '{"type":"http","url":"https://sandboxer.com/mcp","headers":{"Authorization":"Bearer ${SANDBOXER_API_KEY}"}}'
```

What `claude mcp list` showed in a scratch config with all four (each under its own name):

```text
sandboxer: https://sandboxer.com/mcp (HTTP) - ! Needs authentication
sandboxer-local: sbx mcp --type small --ttl 1800 - ✔ Connected
sandboxer-npx: npx -y sandboxer-mcp - ✔ Connected
sandboxer-key: https://sandboxer.com/mcp (HTTP) - ⏸ Pending approval (run `claude` to approve)
```

`Needs authentication` is expected for the OAuth entry until you run `/mcp`. A project `.mcp.json` server waits for you to approve it the first time `claude` starts in that directory. `✔ Connected` only means the process started; a local server with no credentials still connects and prints `not signed in` to stderr.

## Codex

Codex's syntax is in [its MCP docs](https://developers.openai.com/codex/mcp). Servers go in `~/.codex/config.toml`, or `.codex/config.toml` in a trusted project. Hosted with a key:

```bash
codex mcp add sandboxer --url https://sandboxer.com/mcp --bearer-token-env-var SANDBOXER_API_KEY
```

Leave out `--bearer-token-env-var` and run `codex mcp login sandboxer` to sign in instead. Local, using your `sbx login`:

```bash
codex mcp add sandboxer -- sbx mcp --type small --ttl 1800
```

The resulting config, and what `codex mcp list` printed:

```toml
[mcp_servers.sandboxer]
url = "https://sandboxer.com/mcp"
bearer_token_env_var = "SANDBOXER_API_KEY"

[mcp_servers.sandboxer-local]
command = "sbx"
args = ["mcp", "--type", "small", "--ttl", "1800"]
```

```text
Name             Command  Args                         Env  Cwd  Status   Auth
sandboxer-local  sbx      mcp --type small --ttl 1800  -    -    enabled  Unsupported

Name       Url                        Bearer Token Env Var  Status   Auth
sandboxer  https://sandboxer.com/mcp  SANDBOXER_API_KEY     enabled  Bearer token
```

**With `npx`, forward the key explicitly.** Codex doesn't pass your whole environment to stdio servers. In our test, a server started by Codex saw `HOME` but not `SANDBOXER_API_KEY` until we listed it in `env_vars`. Don't use `--env SANDBOXER_API_KEY=...` on the command line: that writes the key itself into `config.toml`.

```toml
[mcp_servers.sandboxer]
command = "npx"
args = ["-y", "sandboxer-mcp"]
env_vars = ["SANDBOXER_API_KEY"]
```

## Cursor

Cursor's format is in [its MCP docs](https://cursor.com/docs/context/mcp). Use `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one. Hosted, with Cursor opening the Sandboxer sign-in page when it connects:

```json
{
  "mcpServers": {
    "sandboxer": { "url": "https://sandboxer.com/mcp" }
  }
}
```

Hosted with a key. Cursor fills in `${env:…}` from your environment:

```json
{
  "mcpServers": {
    "sandboxer": {
      "url": "https://sandboxer.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SANDBOXER_API_KEY}" }
    }
  }
}
```

Local, with the CLI or with `npx`:

```json
{
  "mcpServers": {
    "sandboxer": { "command": "sbx", "args": ["mcp", "--type", "small", "--ttl", "1800"] },
    "sandboxer-npx": {
      "command": "npx",
      "args": ["-y", "sandboxer-mcp"],
      "env": { "SANDBOXER_API_KEY": "${env:SANDBOXER_API_KEY}" }
    }
  }
}
```

Cursor needs the `command` on its `PATH` or as a full path. A desktop app doesn't always inherit your shell's `PATH`, so use the output of `which sbx` if Cursor can't find it. We didn't have Cursor on the test machine; these files follow Cursor's documented format.

## Check it works

Restart or reconnect the client, then ask the agent:

```text
Create a small Sandboxer sandbox, run `uname -sr && nproc` in it, show me the output, then delete it.
```

The agent calls `create_sandbox`, `exec` and `delete_sandbox`, the same three calls timed above. `delete_sandbox` always needs the explicit sandbox id, so the agent can't delete one by accident with a default.

## FAQ

### Do the local and hosted servers create different sandboxes?

No. Both call the same API with your account, and the sandboxes bill to the same wallet. `list_sandboxes` in either one shows sandboxes created by the other.

### Which one should a CI job or headless agent use?

Either, with an API key in `SANDBOXER_API_KEY`, because neither can open a browser there. A [scoped key](/docs/api-keys) such as the `ci` preset limits what the agent can do, tool by tool.

### Why does the local server have one more tool?

`handoff_session` moves the Claude Code or Codex session on your machine into a new sandbox. It needs your local files and session, so it only exists in `sbx mcp`.

### How long do sandboxes created through MCP run?

They stop after an hour unless `ttlSeconds` says otherwise. With the local server, `--ttl` changes that default for every create. A stopped sandbox bills no running time.

### Will my key end up in a config file?

Not with the configs above. Each one reads the key from an environment variable at run time. The risky forms are Claude Code's `--header` with a shell-expanded key and `--env KEY=value` in Claude Code or Codex, which write the value itself.

## Related

- [MCP server docs](/docs/mcp)
- [API keys and scopes](/docs/api-keys)
- [Run Claude Code in a cloud VM](/guides/run-claude-code-in-a-cloud-vm)
- [Run Codex CLI on a remote machine](/guides/run-codex-cli-on-a-remote-machine)