Superserve Sandbox MCP

What can you do with Superserve Sandbox MCP?

-

Create and run sandboxes— Ask your assistant to spin up an isolated Firecracker microVM withsandbox_create, then execute commands inside it viasandbox_execand get stdout, stderr, and exit codes.

Manage files in sandboxes— Have your AI read, write, or list files withsandbox_files_read,sandbox_files_write, andsandbox_files_list, or download an entire directory as a ZIP usingsandbox_files_download_dir.

Control sandbox lifecycle— Pause a sandbox to preserve its state withsandbox_pause, resume it withsandbox_resume, or permanently delete it usingsandbox_killwhen you're done.

Publish preview URLs— Ask your assistant to expose a running service by callingsandbox_preview_urlto get a clean public URL or an expiring private signed link for a specific port.

Manage secrets and templates— List available team secrets withsecret_list, bind them to sandboxes viasandbox_attach_secret, or create custom base images withsandbox_template_createfor specific CPU/memory/disk shapes.

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

The SuperserveMCP server(@superserve/mcp) exposes sandbox primitives asModel Context Protocoltools, 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.

Add the server to your client (seeInstall), then ask the agent to"create a sandbox and runpython --versionin it."The agent callssandbox_create, thensandbox_exec, and reports the result — no code from you.

Don't want to run anything locally? The hosted endpoint athttps://mcp.superserve.aispeaksStreamable HTTP— nonpx, no Node. Send your Superserve API key as abearer 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.
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 thelocalinstall there.

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

Most tools take asandbox_id; the exceptions aresandbox_create,sandbox_list,sandbox_template_list,sandbox_template_create, andsecret_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_urlis an idempotent write because it publishes the requested port, andsandbox_killis annotated destructive.

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 cansandbox_pause(state preserved, cheaper to keep around) orsandbox_kill(permanent).

- Auto-resume.sandbox_execand the file tools transparently resume a paused sandbox, so agents never need to callsandbox_resumefirst.sandbox_resumeexists only to warm a sandbox explicitly.
- Output is capped for context.sandbox_exectruncates stdout and stderr to 32 KiB each — a truncated result setstruncated: trueand reports the original byte length.sandbox_files_readrejectsfiles larger than 1 MiB (it does not return partial content); the error tells you to read a slice withsandbox_exec(e.g.head -c) or download the whole file with the SDK/CLI.sandbox_files_writeinline content is capped at 8 MiB.
- Default command timeout is 60s, capped at 10 minutes. Override it per call withtimeout_ms.
- Egress is controllable.allow_out(domain patterns or CIDRs) adds allowed destinations;deny_out(CIDRs only) blocks them.allow_outalone doesnotlock a sandbox down — for a strict allowlist, combine it withdeny_out: ["0.0.0.0/0"](deny all, then allow the listed destinations). Set these onsandbox_createorsandbox_update, and audit what a sandbox actually reached withsandbox_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.Don't pass credentials as plaintextenv_vars. Instead:
- Create the secret once with theTypeScript SDK(Secret.create()) or theconsole— the raw value never travels through the agent or the MCP server, sosecret creation is intentionally not an MCP tool.
- Discover bindable secrets withsecret_list(metadata only — values never leave the platform).
- Bind at creation —secrets: { ANTHROPIC_API_KEY: "anthropic-prod" }onsandbox_create— or later withsandbox_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 atsandbox_createtime. To get a specific shape (say, a 4 vCPU sandbox) or preinstalled software, build a template withsandbox_template_create, then pollsandbox_template_listuntil itsstatusisreadybefore passing it asfrom_template.

Ports.New MCP sandboxes usepublicas the default access for newly published ports; only explicitly published ports are reachable. Passpreview_access: "private"tosandbox_create(orsandbox_update) to change the default for future ports. Existing ports retain their own mode. Start the server withsandbox_exec, then callsandbox_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; setexpires_in_secondsto a value from 1 through 604800 seconds. SeePreview URLs.

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 theTypeScript SDKdirectly for:

- Secret creation—Secret.create()(the MCP server onlybindsexisting secrets).
- Streaming and interactive commands— streamingrun()callbacks andcommands.spawn(stdin, signals, long-running processes).
- Large or streaming transfers— directory download is supported up to 10 MiB viasandbox_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 andProvider.list()for secret-provider setup.

The server wraps theTypeScript SDKand only ever holds your control-planeSUPERSERVE_API_KEY. Each tool call connects to the target sandbox by ID; the SDK manages the per-sandboxdata-plane access tokeninternally 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.

- Tools don't appear, or the server fails to start.The API key is almost always the cause — MCP clients donotinherit environment variables from your shell. SetSUPERSERVE_API_KEYin the server'senvblock (seeInstall), not just in your terminal.
- Authentication failed.The key is missing or invalid. Production keys start withss_live_; create one on theAPI keypage.
- First call is slow.npxdownloads the package on first use and caches it; later starts are fast.
- Requires Node 18+.The local server runs on Node vianpx. (Thehostedendpoint has no local runtime requirement.)
- 401 Unauthorizedfrom the hosted endpoint.The bearer token is missing or isn't a validss_live_key. Send it asAuthorization: Bearer ss_live_…(seeHosted).

Manage secrets and environment variables with Infisical's official MCP server.