MCP Server

​

Quickstart

​

Install

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

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

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

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

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

​

Hosted (remote)

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

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

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

{
  "mcp_servers": [
    {
      "type": "url",
      "name": "superserve",
      "url": "https://mcp.superserve.ai",
      "authorization_token": "ss_live_xxxxxxxxxxxxxxxx"
    }
  ]
}

​

Tools

​

Example

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

​

Configuration

​

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 or CIDRs) adds allowed destinations; deny_out (CIDRs only) 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). 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

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.

​

Not yet in the MCP surface

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

​

How it works

​

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