Superserve Sandbox MCP

MCP Server

Create, run, and manage Superserve sandboxes from any MCP client.

Looking to let an agent create sandboxes itself? This MCP server does that.

The Superserve MCP server (@superserve/mcp) exposes sandbox primitives as Model Context Protocol tools, so any MCP-capable client — Claude, Cursor, VS Code, Windsurf, Codex — can create sandboxes, run commands, read and write files, build templates, broker secrets, and control network access in an isolated Firecracker microVM.

Run it two ways: locally over stdio via npx, or against the hosted endpoint at https://mcp.superserve.ai with no local install. Both authenticate with your SUPERSERVE_API_KEY and target a sandbox per call by ID. It's a thin wrapper over the TypeScript SDK, so the per-sandbox data-plane token never reaches the model.

Quickstart

Add the server to your client (see Install), then ask the agent to "create a sandbox and run python --version in it." The agent calls sandbox_create, then sandbox_exec, and reports the result — no code from you.

You need a Superserve API key — create one on the API key page. There's no global install; npx fetches the server on first use.

Install

Note

Set SUPERSERVE_API_KEY in the server's env — MCP clients do not inherit it from your shell. Prefer a secret-input prompt over pasting the raw key where your client supports it (see VS Code below).

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`):

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

Add to `.vscode/mcp.json`. The `inputs` block prompts for the key instead of storing it in plain text:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "inputs": [
    {
      "id": "superserve-key",
      "type": "promptString",
      "description": "Superserve API key",
      "password": true
    }
  ],
  "servers": {
    "superserve": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "${input:superserve-key}" }
    }
  }
}
```

Add to `~/.codeium/windsurf/mcp_config.json`:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

Add to `~/.codex/config.toml`. `env_vars` forwards `SUPERSERVE_API_KEY` from your environment, so the raw key isn't stored in the config file (export it in your shell first). Codex also reads the server's `instructions` for cross-tool workflow guidance.

```toml theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]
```

For the [hosted](#hosted-remote) endpoint, use `url = "https://mcp.superserve.ai"` with `bearer_token_env_var = "SUPERSERVE_API_KEY"`.

Hosted (remote)

Don't want to run anything locally? The hosted endpoint at https://mcp.superserve.ai speaks Streamable HTTP — no npx, no Node. Send your Superserve API key as a bearer token. The endpoint is stateless and account-scoped (your key already maps to your team), and the per-sandbox data-plane token never leaves the server.

Note

Bearer auth works in any client that lets you set a request header — Claude Code, Cursor, VS Code, and the Anthropic Messages API connector. Claude.ai, Claude Desktop's Custom Connector UI, and ChatGPT developer mode don't offer a static-bearer / custom-header field (they expect OAuth), which the hosted endpoint doesn't support yet — use the local install there.

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add --transport http superserve https://mcp.superserve.ai \ --header "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx" ``` Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

Add to `.vscode/mcp.json`. The `inputs` block prompts for the key instead of storing it in plain text:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "inputs": [
    {
      "id": "superserve-key",
      "type": "promptString",
      "description": "Superserve API key",
      "password": true
    }
  ],
  "servers": {
    "superserve": {
      "type": "http",
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ${input:superserve-key}" }
    }
  }
}
```

Pass it as a connector in an [Anthropic Messages API](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector) request:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcp_servers": [
    {
      "type": "url",
      "name": "superserve",
      "url": "https://mcp.superserve.ai",
      "authorization_token": "ss_live_xxxxxxxxxxxxxxxx"
    }
  ]
}
```

Same tools and behavior as the local server — the only difference is transport and that the key travels as a bearer header instead of an env var.

Tools

Tool	What it does
sandbox_create	Create a new sandbox; returns its id. Accepts secrets, egress rules, and preview_access.
sandbox_update	Change metadata, egress rules, lifecycle windows, or preview_access.
sandbox_list	List your sandboxes (active and paused), filterable by metadata.
sandbox_info	Get one sandbox's status, resources, metadata, network rules, and secret bindings. Read-only.
sandbox_exec	Run a shell command; returns stdout, stderr, exit code. Auto-resumes a paused sandbox.
sandbox_files_read	Read a file (UTF-8 text, or base64 for binary).
sandbox_files_write	Create or overwrite a file. Parent directories are created automatically.
sandbox_files_list	List a directory's entries (name, type, size, modification time).
sandbox_files_download_dir	Download a directory as a base64 ZIP (symlinks skipped). Capped at 10 MiB; larger → SDK/CLI.
sandbox_pause	Pause a sandbox; state is preserved.
sandbox_resume	Resume a paused sandbox (usually unnecessary — exec auto-resumes).
sandbox_kill	Permanently delete a sandbox.
sandbox_preview_url	Publish a port and return a clean public URL or an expiring private signed URL.
sandbox_network_log	Audit a sandbox's outbound connections (host, verdict, bytes) without resuming it.
sandbox_computer	Drive a GUI desktop sandbox: screenshot, mouse, keyboard, scroll, resize, viewer URL. One action per call.
sandbox_template_list	List the templates (base images) your team can launch from.
sandbox_template_create	Build a custom template with a specific vCPU/memory/disk shape or preinstalled software (async — poll for ready).
secret_list	List bindable team secrets (metadata only — never values).
sandbox_attach_secret	Bind a stored secret to a running sandbox under an env var.
sandbox_detach_secret	Remove a secret binding from a sandbox.

Most tools take a sandbox_id; the exceptions are sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create, and secret_list. Start with one of those to get an ID, then thread it into later calls. Read-only tools (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_network_log, sandbox_template_list, secret_list) are annotated so clients can skip confirmation prompts; sandbox_preview_url is an idempotent write because it publishes the requested port, and sandbox_kill is annotated destructive.

Example

A typical agent flow for "spin up a sandbox, write a Python script that prints the first primes, and run it":

sandbox_create       { name: "primes" }
                       → { id: "a1b2c3…", name: "primes", status: "active" }

sandbox_files_write  { sandbox_id: "a1b2c3…", path: "/app/primes.py", content: "…" }
                       → { path: "/app/primes.py", bytes: 142 }

sandbox_exec         { sandbox_id: "a1b2c3…", command: "python /app/primes.py" }
                       → { exit_code: 0, stdout: "2 3 5 7 11 13 17 19 23 29", stderr: "" }

When it's done, the agent can sandbox_pause (state preserved, cheaper to keep around) or sandbox_kill (permanent).

Configuration

Variable	Required	Description
SUPERSERVE_API_KEY	Yes	Your Superserve API key (starts with ss_live_).
SUPERSERVE_BASE_URL	No	Override the control-plane URL (defaults to https://api.superserve.ai).

Behavior and limits

• Auto-resume. sandbox_exec and the file tools transparently resume a paused sandbox, so agents never need to call sandbox_resume first. sandbox_resume exists only to warm a sandbox explicitly.
• Output is capped for context. sandbox_exec truncates stdout and stderr to 32 KiB each — a truncated result sets truncated: true and reports the original byte length. sandbox_files_read rejects files larger than 1 MiB (it does not return partial content); the error tells you to read a slice with sandbox_exec (e.g. head -c) or download the whole file with the SDK/CLI. sandbox_files_write inline content is capped at 8 MiB.
• Default command timeout is 60s, capped at 10 minutes. Override it per call with timeout_ms.
• Egress is controllable. allow_out (domain patterns, IPs, or CIDRs) adds allowed destinations; deny_out (IPs or CIDRs, no domains) blocks them. allow_out alone does not lock a sandbox down — for a strict allowlist, combine it with deny_out: ["0.0.0.0/0"] (deny all, then allow the listed destinations). If the allowlist has domain rules or the workload resolves hostnames, also allow the sandbox's DNS resolvers, 1.1.1.1/32 and 8.8.8.8/32, since deny-all blocks DNS too; leave them out of an IP-only allowlist, where an allowed resolver is only an extra outbound channel. Set these on sandbox_create or sandbox_update, and audit what a sandbox actually reached with sandbox_network_log.
• Errors are actionable. A failed tool call returns a short message telling the agent what to do next — e.g. "Sandbox quota reached. Pause or kill a sandbox, or retry later." — rather than a raw stack trace, so the agent can self-correct.

Secrets, templates, and ports

Secrets. Don't pass credentials as plaintext env_vars. Instead:

1. Create the secret once with the TypeScript SDK (Secret.create()) or the console — the raw value never travels through the agent or the MCP server, so secret creation is intentionally not an MCP tool.
2. Discover bindable secrets with secret_list (metadata only — values never leave the platform).
3. Bind at creation — secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } on sandbox_create — or later with sandbox_attach_secret / sandbox_detach_secret.

The sandbox sees a proxy token; the platform swaps in the real credential only for outbound requests to the secret's allowed hosts.

Templates. A sandbox inherits its vCPU/memory/disk from its template and can't override them at sandbox_create time. To get a specific shape (say, a 4 vCPU sandbox) or preinstalled software, build a template with sandbox_template_create, then poll sandbox_template_list until its status is ready before passing it as from_template.

Ports. New MCP sandboxes use public as the default access for newly published ports; only explicitly published ports are reachable. Pass preview_access: "private" to sandbox_create (or sandbox_update) to change the default for future ports. Existing ports retain their own mode. Start the server with sandbox_exec, then call sandbox_preview_url; the tool idempotently publishes that one port and uses the returned port mode to return either a clean public URL or an expiring private signed URL. Private links default to one hour; set expires_in_seconds to a value from 1 through 604800 seconds. See Preview URLs.

Computer use

sandbox_computer drives a GUI desktop in a sandbox created from a desktop template such as superserve/desktop. It takes one action per call in the vocabulary computer-use models emit: screenshot, left_click, right_click, middle_click, double_click, triple_click, left_click_drag, left_mouse_down, left_mouse_up, mouse_move, key, type, scroll, wait, resize, and stream_url. Pointer actions take coordinate: [x, y] in screen pixels (origin top-left); key and type take text; scroll takes scroll_direction and an optional scroll_amount.

sandbox_create    { name: "browser", from_template: "superserve/desktop" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "left_click", coordinate: [640, 32] }
                    → text "left_click done (1280x800)" + image/png
sandbox_computer  { sandbox_id: "a1b2c3…", action: "type", text: "https://example.com" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "key", text: "Return" }

Input actions return a fresh screenshot of the result, so the model's act-then-look turn is one tool call; pass screenshot_after: false when sending several actions back to back. wait pauses for duration_ms (capped at 10 seconds) without a request to the sandbox. stream_url returns a live browser viewer for the desktop under the sandbox's preview policy.

If an input action fails, the input may already have been delivered. The tool says so and asks the agent to take a screenshot before repeating it. See the Desktop guide for the underlying SDK surface.

Not yet in the MCP surface

The MCP server covers the common agent loop; the table above is the complete v1 tool set. A few SDK capabilities aren't exposed yet — reach for the TypeScript SDK directly for:

• Secret creation — Secret.create() (the MCP server only binds existing secrets).
• Streaming and interactive commands — streaming run() callbacks and commands.spawn (stdin, signals, long-running processes).
• Large or streaming transfers — directory download is supported up to 10 MiB via sandbox_files_download_dir; beyond that (and for archive/streaming uploads or single files past the 1 MiB read / 8 MiB inline-write caps), use the SDK/CLI (files.downloadDir, streaming upload).
• Billing and provider discovery — usage data and Provider.list() for secret-provider setup.

These are tracked as follow-ups.

How it works

The server wraps the TypeScript SDK and only ever holds your control-plane SUPERSERVE_API_KEY. Each tool call connects to the target sandbox by ID; the SDK manages the per-sandbox data-plane access token internally and rotates it on resume, so it's never exposed to the model or returned in tool output. Tools are stateless — there's no hidden "current sandbox" — which keeps behavior predictable across multi-turn and parallel tool calls.

Troubleshooting

• Tools don't appear, or the server fails to start. The API key is almost always the cause — MCP clients do not inherit environment variables from your shell. Set SUPERSERVE_API_KEY in the server's env block (see Install), not just in your terminal.
• Authentication failed. The key is missing or invalid. Production keys start with ss_live_; create one on the API key page.
• First call is slow. npx downloads the package on first use and caches it; later starts are fast.
• Requires Node 18+. The local server runs on Node via npx. (The hosted endpoint has no local runtime requirement.)
• 401 Unauthorized from the hosted endpoint. The bearer token is missing or isn't a valid ss_live_ key. Send it as Authorization: Bearer ss_live_… (see Hosted).

Related

Pause, resume, and delete sandboxes. Exec, streaming, cwd, env, and timeouts. Broker provider keys without exposing them to the sandbox. The library the MCP server wraps.

This documentation is built and hosted on Mintlify, a developer documentation platform.