# MCP server

> Connect Claude, ChatGPT, Claude Code, Codex, Cursor or any MCP client to https://sandboxer.com/mcp and your agent can create cloud sandboxes, run code, move files, publish ports, save snapshots and clean up, with no CLI to install.

Sandboxer's [Model Context Protocol](https://modelcontextprotocol.io) server gives an agent its own cloud computers. With it, the agent can:

- create Linux sandboxes;
- run commands in them, in the foreground or the background;
- read and write files;
- put a port on a public HTTPS URL;
- save and reuse snapshots;
- stop or delete sandboxes when it is done.

Everything runs in Sandboxer microVMs, not on your computer.

There are two ways to connect:

- **Hosted** at `https://sandboxer.com/mcp` (Streamable HTTP). Nothing to install. Apps like Claude and ChatGPT sign in with your Sandboxer account (OAuth). Headless clients send an API key.
- **Local** with `sbx mcp` (or `npx sandboxer-mcp`), a stdio server that ships with the CLI. It has the same 20 tools plus `handoff_session`, which only works locally.

## If you are an agent setting this up

1. Add the MCP server `https://sandboxer.com/mcp` (transport: Streamable HTTP, sometimes labelled "HTTP") to the client you run in. The exact command or config for each client is below.
2. Authenticate:
   - In an app that can open a browser (Claude, ChatGPT, Claude Code, Codex, Cursor), leave out any key. The client will ask your user to sign in to Sandboxer and click **Allow**.
   - In a headless run, you need an API key, and you can't create one yourself. Ask your user to create a key at [sandboxer.com/app/api-keys](https://sandboxer.com/app/api-keys) (a scoped key, such as the `ci` preset, is enough) and to put it in the `SANDBOXER_API_KEY` environment variable of the process you run in. Don't ask them to paste it into the conversation. The config then sends it as `Authorization: Bearer <key>`, read from that variable, so the key never sits in a file you commit.
3. Most clients load a new MCP server only after a restart or reconnect. Then check the connection by calling `list_sandboxes`. An empty list means it works.
4. Clean up after yourself. `stop_sandbox` stops billing and keeps everything. `delete_sandbox` removes the sandbox for good.

## Claude (claude.ai and Claude Desktop)

1. Open **Customize > Connectors** ([claude.ai/customize/connectors](https://claude.ai/customize/connectors)) and click **Add custom connector**.
2. Enter the URL `https://sandboxer.com/mcp` and click **Add**. If the dialog asks about authentication, choose a sign-in option ("Sign in now" or "Sign in when needed").
3. Click **Connect**, sign in to Sandboxer and click **Allow**.
4. In a chat, turn the connector on from **+ > Connectors**.

On Team and Enterprise plans, an Owner adds the connector once under **Organization settings > Connectors** (Add, then Custom), and each member then clicks **Connect**. If Claude asks how it should identify itself, keep the default (Claude's published identity); **Register automatically** also works. The free plan allows one custom connector.

## ChatGPT

1. Open [chatgpt.com/plugins](https://chatgpt.com/plugins), click **+** and choose **Add custom MCP server**.
2. Name it Sandboxer and enter the URL `https://sandboxer.com/mcp`.
3. Choose OAuth for authentication, review the warning, select **I understand and want to continue**, then **Create as a plugin**.
4. Sign in to Sandboxer and click **Allow**.
5. In a new conversation, type `@` and pick Sandboxer.

Your account's or workspace's policies decide whether you can add custom MCP servers. ChatGPT signs in with OAuth rather than taking an API key.

## Claude Code

```bash title="Sign in (opens a browser)"
claude mcp add --transport http --scope user sandboxer https://sandboxer.com/mcp
# then, inside Claude Code: /mcp, choose sandboxer, and sign in
```

```json title=".mcp.json (API key, shared with a project)"
{
  "mcpServers": {
    "sandboxer": {
      "type": "http",
      "url": "https://sandboxer.com/mcp",
      "headers": { "Authorization": "Bearer ${SANDBOXER_API_KEY}" }
    }
  }
}
```

Notes:

- **Keys stay out of the file.** Claude Code fills `${SANDBOXER_API_KEY}` in from the environment, so the key never lands in `.mcp.json` or git. Don't pass a key with `--header` together with `--scope project`: the shell expands it first, and the literal key would be written to the shared file.
- **A rejected key doesn't fall back to sign-in.** Remove the header to sign in instead.
- **Headless runs** (`claude -p`) can't open a browser. Sign in beforehand with `claude mcp login sandboxer` (add `--no-browser` over SSH), or use a key.

## Codex

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

Codex sends the key in that environment variable as the bearer token. To sign in instead, add the server without `bearer_token_env_var` and run `codex mcp login sandboxer`.

## Cursor

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

Use `.cursor/mcp.json` in a project to add it there only. Cursor fills in `${env:…}` from your environment, so the key stays out of the file. To sign in with your Sandboxer account instead, leave out `headers`, and Cursor opens the sign-in page when it connects.

## Any other client

Point it at `https://sandboxer.com/mcp` with the Streamable HTTP transport. It authenticates in one of two ways:

- **OAuth 2.1**, with PKCE and dynamic client registration or a Client ID Metadata Document. A client discovers it from the `401` and `/.well-known/oauth-protected-resource`.
- **An API key**, sent on every request as `Authorization: Bearer <key>`.

Sandboxer's MCP server is also listed in the official [MCP Registry](https://registry.modelcontextprotocol.io) as `com.sandboxer/mcp`, with both the hosted endpoint (`https://sandboxer.com/mcp`) and the npm package (`npx -y sandboxer-mcp`). Clients that read the registry can install it from there.

## When sbx is out of date

If `sbx mcp` (the local server) is older than the current release, every tool result ends with a note such as "Note: sbx 5750b620 is out of date; run `sbx update` (9eff74cd). This MCP server's tools may lack newer options until then." Run `sbx update` and restart your MCP client. The hosted server (`https://sandboxer.com/mcp`) is always current.

## Keys, scopes and access

- **Any API key works**, including a [scoped key](/docs/api-keys). Its scopes apply tool by tool: a key without `sandbox.delete` can't delete sandboxes (with `sandbox.delete-own`, as in the `ci` preset, only the ones it created), and a key limited to certain sandboxes only sees those. Plan limits and rate limits are the same as on the API.
- **Signing in grants the app full access** to your account through MCP. The sandboxes it runs bill to your active wallet, as with the CLI.
- **Each connected app is listed** under [API keys](/app/api-keys) as "Claude (MCP)", "ChatGPT (MCP)" and so on. **Disconnect** there to end its access at once.
- **A connector's token only works on `/mcp`**, not on the REST API.

## Tools

How `sandboxId` defaults work:

- **It defaults to the sandbox this connection (MCP session) created or used last**, so an agent that creates one sandbox never has to repeat its id. The server remembers that for an hour of inactivity.
- **A fresh connection never picks one of your other sandboxes on its own.** If a call says `sandboxId` is required, pass it explicitly.
- **`delete_sandbox` always needs an explicit `sandboxId`.**

Sandboxes created through MCP stop automatically after an hour unless `ttlSeconds` says otherwise. `extend_sandbox` changes that. A stopped sandbox bills no running time.

`(destructive)` marks tools that can change or remove data in a sandbox; `(read-only)` tools change nothing.

<!-- mcp-tools:start (generated from docs/mcp-tools.json by scripts/sync-mcp-tools.mjs; don't edit) -->

| Tool | What it does | Arguments |
| - | - | - |
| `create_sandbox` | Create a cloud sandbox (an Ubuntu microVM with root, Docker, git, Node and Python) and wait until it is ready. Returns its id and URL; later calls use it by default. Start from a named snapshot with from (a name, or a versioned name for its newest version) or fromLabels (the newest snapshot with all those labels). | optional `type`, `ttlSeconds`, `name`, `region`, `from`, `fromLabels`, `labels`, `env`, `noEnv`, `idleStopMinutes` |
| `create_task` (destructive) | Run a coding agent on a GitHub repo in its own sandbox and end in a pull request: it clones the repo onto branch sandboxer/\<task-id\>, runs the agent on the prompt, commits, opens a PR against the base branch, then pauses. The repo must be connected (the Sandboxer GitHub App installed on it). Follow it with task_status. | requires `repo`, `prompt`; optional `agent`, `baseBranch` |
| `task_status` (read-only) | Show an agent task: its status (queued, starting, running, committing, opening_pr, paused, failed, cancelled), the pull request once opened, cost so far and any error. | requires `taskId` |
| `list_sandboxes` (read-only) | List your sandboxes with their state, URL and labels. | optional `state`, `labels` |
| `get_sandbox` (read-only) | Show one sandbox: state, URL, when it stops automatically, labels and stored bytes. | optional `sandboxId` |
| `exec` (destructive) | Run a shell command (bash -c) in the sandbox. By default it waits and returns stdout, stderr and the exit code (timeoutSeconds, default 120, max 600). With detached: true it starts the command in the background and returns its processId at once: read its output and exit code with command_status, stop it with kill_command. Use detached for anything long (builds, test suites, servers). | requires `command`; optional `sandboxId`, `cwd`, `timeoutSeconds`, `env`, `detached` |
| `command_status` (read-only) | Status of a detached command: running or its exit code, and its output. Pass the stdoutOffset/stderrOffset from the previous call to get only new output. | requires `processId`; optional `sandboxId`, `stdoutOffset`, `stderrOffset` |
| `kill_command` (destructive) | Stop a detached command. | requires `processId`; optional `sandboxId` |
| `read_file` (read-only) | Read a file from the sandbox (up to 5 MiB). | requires `path`; optional `sandboxId`, `encoding` |
| `write_file` (destructive) | Create or overwrite a file in the sandbox (up to 5 MiB). Parent directories are created. | requires `path`, `content`; optional `sandboxId`, `encoding` |
| `host_port` | Serve a port of the sandbox on a stable public HTTPS URL. The URL carries an access token unless public is true. Start the service first, listening on 0.0.0.0 (or set localhost). | requires `port`; optional `sandboxId`, `public`, `localhost`, `title` |
| `stop_sandbox` | Snapshot the sandbox (memory included) and stop billing. Files, installed packages and running processes are kept; resume_sandbox brings it back. | optional `sandboxId` |
| `resume_sandbox` | Resume a stopped sandbox from its snapshot and wait until it is ready. Its memory (running processes) is restored when a machine of its CPU type is free within 2 minutes; otherwise it boots from disk (files intact) and the result says so. requireMemory: true waits up to 30 minutes for its memory instead and fails rather than boot from disk. | optional `sandboxId`, `requireMemory` |
| `extend_sandbox` | Set when the sandbox stops: ttlSeconds from now (0 never), and/or idleStopMinutes (pause after that long without activity, waking on use; 0 never). | optional `sandboxId`, `ttlSeconds`, `idleStopMinutes` |
| `rename_sandbox` | Change the sandbox's display name. | requires `name`; optional `sandboxId` |
| `label_sandbox` | Replace the sandbox's labels ({} clears them). | requires `labels`; optional `sandboxId` |
| `delete_sandbox` (destructive) | Delete a sandbox permanently: its disk, memory and automatic snapshots go (named snapshots saved from it stay). sandboxId is required: there is no default and no wildcard. | requires `sandboxId` |
| `save_snapshot` | Save the sandbox as a named snapshot to create new sandboxes from, and wait until it is saved. With versioned: true each save is a new version (\<name\>-v\<N\>); ifLatest saves only if the newest version is still that number (safe concurrent saves); keep deletes all but the newest N versions. | requires `name`; optional `sandboxId`, `labels`, `versioned`, `ifLatest`, `keep` |
| `list_snapshots` (read-only) | List your named snapshots: name, version, labels, created time, stored bytes (what counts toward your storage) and disk size (logical). | optional `labels`, `name` |
| `delete_snapshot` (destructive) | Delete one named snapshot (one version, e.g. ci-base-v3). name is required: there is no wildcard. | requires `name` |
| `handoff_session` (destructive) | Move this machine's Claude Code or Codex session and its repo into a new sandbox and resume the agent there, headless ("close my laptop"). Checkpoints every change (untracked files too) on a temporary branch without touching the user's branch, pushes it into the sandbox over SSH (never to a remote), moves the session file and resumes it with the account's API key (never a subscription login). .env files always stay behind (copy them with `sbx handoff --include-env` yourself). Only in the local `sbx mcp` server. Bring it back with `sbx handoff --back`. | requires `cwd`; optional `agent`, `session`, `prompt`, `model`, `sandboxId` |

<!-- mcp-tools:end -->

How results come back:

- **Text and data.** Every tool returns a short text summary, and the same data as `structuredContent`.
- **A non-zero exit code is a normal result**, not a tool error, so the agent sees the output and can fix the problem.
- **API failures are tool errors** carrying the API's message: an unknown sandbox, a stopped one, a plan or start limit.

## Long-running commands and servers

`exec` waits up to `timeoutSeconds` (default 120, at most 600). For longer work, pass `detached: true`:

- `exec` then returns a `processId` at once.
- `command_status` returns new output since the offsets you pass, and the exit code when the command ends.
- `kill_command` stops it.

To serve an app, start it detached, listening on `0.0.0.0`, then publish its port:

```text
exec       { "command": "npm run dev -- --host 0.0.0.0 --port 3000", "detached": true }
host_port  { "port": 3000 }
```

The URL carries an access token unless you pass `public: true`. See [Hosting](/docs/hosting).

## Snapshots, labels and versions

- **Labels:** `create_sandbox` and `label_sandbox` set them, and `list_sandboxes` filters by them.
- **Saving:** `save_snapshot` saves the sandbox as a named snapshot. With `versioned: true` each save is a new version under one name. `ifLatest` makes concurrent saves safe, and `keep` keeps only the newest N versions.
- **Starting from a snapshot:** `create_sandbox` takes `from` (a name, or a versioned name for its newest version) or `fromLabels` (the newest snapshot carrying all those labels).
- **Listing:** `list_snapshots` shows each snapshot's stored bytes (what counts toward your plan's storage) next to its logical disk size.

## Local server (`sbx mcp`)

The same tools run as a local stdio server inside the CLI. Install the CLI and sign in once. On Windows, install with `irm https://sandboxer.com/install.ps1 | iex`.

```bash
curl -fsSL https://sandboxer.com/install | sh
sbx login
```

Then add it to your client:

```bash title="Claude Code"
claude mcp add sandboxer -- sbx mcp
```

```bash title="Codex"
codex mcp add sandboxer -- sbx mcp
```

```json title="Cursor / Claude Desktop"
{
  "mcpServers": {
    "sandboxer": { "command": "sbx", "args": ["mcp"] }
  }
}
```

Notes:

- **Without installing the CLI first:** `npx sandboxer-mcp` fetches and starts it. There's no `sbx login` that way, so set `SANDBOXER_API_KEY` in its environment. Codex doesn't pass your shell's environment to stdio servers, so list the variable in `~/.codex/config.toml`:

  ```toml
  [mcp_servers.sandboxer]
  command = "npx"
  args = ["-y", "sandboxer-mcp"]
  env_vars = ["SANDBOXER_API_KEY"]
  ``` If an older `sbx` on your `PATH` is missing tools, run `sbx self-update`.
- **On a server or in CI:** skip `sbx login` and set `SANDBOXER_API_KEY` in the server's environment.
- **Claude Desktop** reads `claude_desktop_config.json` (Settings > Developer > Edit Config). Desktop apps don't always inherit your shell's `PATH`, so use the full path from `which sbx` if the client can't find it.
- **Defaults for the sandboxes the agent creates:** `sbx mcp --type small --ttl 1800` sets their size and auto-stop in seconds (default 3600; `0` never stops them). The agent can still pass its own values.
- **Organizations:** `sbx --org acme mcp` bills them to the `acme` wallet. `--api-key` overrides the signed-in key.

## Frameworks

The same server plugs into agent frameworks that speak MCP:

- [Claude Agent SDK](/docs/claude-agent-sdk)
- [OpenAI Agents SDK](/docs/openai-agents)
- [LangChain & LangGraph](/docs/langchain)

Each of those pages also shows how to write a code-execution tool directly with the `sandboxer-sdk` package, for when you don't want an MCP server.
