Superserve Sandbox

The Superserve MCP server lets any MCP client create and control isolated cloud sandboxes

Model Context Protocolserver forSuperservesandboxes. Create, run commands in, and manage isolated Firecracker microVMs from any MCP client — Claude, Cursor, VS Code, Windsurf, Codex.

Add to your MCP client and setSUPERSERVE_API_KEYin itsenv(clients do not inherit it from your shell). Create a key atconsole.superserve.ai.

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

{ "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_varsforwards 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"]

A hosted instance runs athttps://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 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" } } } }

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 anyfetchruntime (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 aGET /healthliveness probe. Config:PORT(default8080),SUPERSERVE_BASE_URL(optional). The API key is read per request from the bearer header and never logged.

All tools take asandbox_idexceptsandbox_create,sandbox_list,sandbox_template_list,sandbox_template_create, andsecret_list. Secretcreationis intentionally not exposed (the raw value belongs on the SDK/console, not an agent transcript); the server only binds existing secrets.

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.

Provides an offline AWS CDK API reference.