Superserve Sandbox

@superserve/mcp

Model Context Protocol server for Superserve sandboxes. Create, run commands in, and manage isolated Firecracker microVMs from any MCP client — Claude, Cursor, VS Code, Windsurf, Codex.

Runs locally over stdio via npx. Authenticates with your Superserve API key. Targets a sandbox per call by id.

Hosted (remote)

A hosted instance runs at https://mcp.superserve.ai (Streamable HTTP) — no local install. Send your Superserve API key as a bearer token; the server is stateless and account-scoped (the key already maps to your team).

Bearer auth works in Claude Code, Cursor, VS Code, and the Anthropic Messages API connector. Claude.ai, Claude Desktop's Custom Connector UI, and ChatGPT developer mode expect OAuth (no static-bearer field), which the hosted endpoint does not support yet.

Claude Code:

claude mcp add --transport http superserve https://mcp.superserve.ai \
 --header "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx"

Cursor / VS Code (.cursor/mcp.json, .vscode/mcp.json):

{
 "servers": {
 "superserve": {
 "type": "http",
 "url": "https://mcp.superserve.ai",
 "headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
 }
 }
}

Running the hosted server

The same package ships the hosted server. Run it standalone (self-host / staging):

PORT=8080 SUPERSERVE_BASE_URL=https://api.superserve.ai \
 npx -y -p @superserve/mcp superserve-mcp-http

Or mount the Web-standard handler in any fetch runtime (e.g. a Next.js route handler):

import { handleMcpRequest } from "@superserve/mcp/http"

export const POST = (req: Request) => handleMcpRequest(req)

It serves the MCP endpoint at / (POST) and a GET /health liveness probe. Config: PORT (default 8080), SUPERSERVE_BASE_URL (optional). The API key is read per request from the bearer header and never logged.

Tools

Tool Description sandbox_create Create a sandbox; returns its id. Accepts secrets bindings and egress rules. sandbox_update Change a sandbox's metadata or egress (allow_out/deny_out) rules after creation. sandbox_list List sandboxes (active and paused), filterable by metadata. sandbox_info Get a sandbox's status, resources, metadata, network rules, and secret bindings. 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). Rejects files over 1 MiB. sandbox_files_write Create or overwrite a file (inline content capped at 8 MiB). sandbox_files_list List a directory. sandbox_files_download_dir Download a directory as a base64 ZIP (symlinks skipped). Capped at 10 MiB. sandbox_pause Pause a sandbox (state preserved). sandbox_resume Resume a paused sandbox (usually unnecessary — exec auto-resumes). sandbox_kill Delete a sandbox. sandbox_preview_url Build the public URL for a listening port (unauthenticated). sandbox_network_log Audit a sandbox's outbound connections. sandbox_template_list List the templates (prebuilt base images) your team can create sandboxes from. sandbox_template_create Build a custom template (vCPU/memory/disk shape, preinstalled software). Async. secret_list List bindable team secrets (metadata only — never values). sandbox_attach_secret Bind a stored secret to a sandbox under an env var. sandbox_detach_secret Remove a secret binding from a sandbox.

All tools take a sandbox_id except sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create, and secret_list. Secret creation is intentionally not exposed (the raw value belongs on the SDK/console, not an agent transcript); the server only binds existing secrets.

Development

bun install
bunx turbo run build --filter=@superserve/mcp
bunx turbo run typecheck --filter=@superserve/mcp
bunx turbo run test --filter=@superserve/mcp # unit + in-memory integration (no credentials)
SUPERSERVE_API_KEY=ss_live_... bunx turbo run e2e --filter=@superserve/mcp # live round-trip

The server is a thin adapter over @superserve/sdk; the per-sandbox data-plane access token is managed by the SDK and never exposed to the model.

License

Apache-2.0

Install

Add to your MCP client and set SUPERSERVE_API_KEY in its env (clients do not inherit it from your shell). Create a key at console.superserve.ai.

Claude Code:

claude mcp add superserve \
 --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \
 -- npx -y @superserve/mcp

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, .cursor/mcp.json, mcp_config.json):

{
 "mcpServers": {
 "superserve": {
 "command": "npx",
 "args": ["-y", "@superserve/mcp"],
 "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
 }
 }
}

VS Code (.vscode/mcp.json, prompts for the key):

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

Codex (~/.codex/config.toml) — env_vars forwards the key from your environment instead of storing it in the file:

[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]

Configuration

Variable Required Default SUPERSERVE_API_KEY Yes — SUPERSERVE_BASE_URL No https://api.superserve.ai