Skip to content
sandboxer
Start free trial
Guides · Integrations

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

Updated October 27, 2026 .md

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:

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:

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. Hosted, signing in with your Sandboxer account:

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:

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:

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:

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):

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. Servers go in ~/.codex/config.toml, or .codex/config.toml in a trusted project. Hosted with a key:

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:

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

The resulting config, and what codex mcp list printed:

[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"]
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.

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

Cursor#

Cursor's format is in its MCP docs. 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:

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

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

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

Local, with the CLI or with npx:

{
  "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:

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

More guides

Top AI sandbox platforms for code execution in 2026, ranked

For running AI-written code we rank Sandboxer, Freestyle and E2B first: each gives code its own VM with an API or SDK and can pause with memory. Pick Daytona for Windows or GPUs, Modal or Northflank for GPUs at scale, E2B or Northflank to run in your own cloud, and Vercel Sandbox if your app lives on Vercel.

Read the guide
Best sandboxes for running coding agents (Claude Code, Codex, Gemini CLI) in 2026, ranked

For coding agents we rank Sandboxer first: a full Ubuntu VM with Claude Code and Codex preinstalled, Docker, and stop-and-resume that keeps the agent's session in memory. Freestyle and Amp Orbs also keep memory across pauses. Pick E2B for prebuilt agent templates on open source, Docker Sandboxes for free local runs, and Codespaces if you live in GitHub.

Read the guide
Best Daytona sandbox alternatives in 2026, ranked

The best Daytona alternatives depend on why you're switching. For a full Linux microVM on every sandbox with memory-saving stop and Docker, we rank Sandboxer first. E2B suits open source and self-hosting, Modal massive short-job fleets, Northflank bring-your-own-cloud with GPUs, and Vercel Sandbox apps on Vercel.

Read the guide
Best E2B alternatives in 2026, ranked

If you're leaving E2B for longer sessions or a fuller machine, we rank Sandboxer first, then Freestyle: both give each sandbox a full Linux VM that keeps memory across pauses, with Docker and no short session cap. Pick Daytona for Windows or GPUs, Northflank for bring-your-own-cloud, and stay on E2B if you need open source.

Read the guide