Superserve

@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.

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 -p @superserve/mcp superserve-mcp

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

{

"mcpServers": { "superserve": { "command": "npx", "args": ["-y", "-p", "@superserve/mcp", "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", "-p", "@superserve/mcp", "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", "-p", "@superserve/mcp", "superserve-mcp"] env_vars = ["SUPERSERVE_API_KEY"]

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.

The hosted endpoint limits each request body to about 4.5 MB, so keep sandbox_files_write inline content under about 4 MiB of text or 3 MiB of binary data sent as base64; larger requests fail with HTTP 413 Request Entity Too Large. The local server accepts up to 8 MiB.

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

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.

Configuration

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