Superserve Sandbox MCP

MCP-Server

Erstellen, ausführen und verwalten Sie Superserve-Sandboxes über jeden MCP-Client.

Möchten Sie einem Agenten erlauben, selbst Sandboxes zu erstellen? Dieser MCP-Server macht genau das.

Der Superserve MCP-Server (@superserve/mcp) stellt Sandbox-Primitive als Model Context Protocol-Tools bereit, sodass jeder MCP-fähige Client – Claude, Cursor, VS Code, Windsurf, Codex – Sandboxes erstellen, Befehle ausführen, Dateien lesen und schreiben, Templates bauen, Secrets verwalten und den Netzwerkzugriff in einer isolierten Firecracker-MicroVM steuern kann.

Sie können ihn auf zwei Arten ausführen: lokal über stdio via npx oder gegen den gehosteten Endpunkt unter https://mcp.superserve.ai ohne lokale Installation. Beide authentifizieren sich mit Ihrem SUPERSERVE_API_KEY und zielen pro Aufruf über die ID auf eine Sandbox. Es handelt sich um einen schlanken Wrapper um das TypeScript SDK, sodass das Data-Plane-Token pro Sandbox niemals das Modell erreicht.

Schnellstart

Fügen Sie den Server zu Ihrem Client hinzu (siehe Installation) und bitten Sie dann den Agenten, „eine Sandbox zu erstellen und python --version darin auszuführen." Der Agent ruft sandbox_create auf, dann sandbox_exec, und meldet das Ergebnis – ganz ohne Code von Ihnen.

Sie benötigen einen Superserve-API-Schlüssel – erstellen Sie einen auf der Seite API-Schlüssel. Es gibt keine globale Installation; npx lädt den Server bei der ersten Verwendung herunter.

Installation

Hinweis

Setzen Sie SUPERSERVE_API_KEY in der env des Servers – MCP-Clients erben diese nicht aus Ihrer Shell. Bevorzugen Sie eine Secret-Input-Eingabeaufforderung gegenüber dem Einfügen des rohen Schlüssels, wo Ihr Client dies unterstützt (siehe VS Code unten).

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` Fügen Sie zu `claude_desktop_config.json` hinzu (macOS: `~/Library/Application Support/Claude/`):

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

Fügen Sie zu `.cursor/mcp.json` (Projekt) oder `~/.cursor/mcp.json` (global) hinzu:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

Fügen Sie zu `.vscode/mcp.json` hinzu. Der `inputs`-Block fordert zur Eingabe des Schlüssels auf, anstatt ihn im Klartext zu speichern:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "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}" }
    }
  }
}
```

Fügen Sie zu `~/.codeium/windsurf/mcp_config.json` hinzu:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

Fügen Sie zu `~/.codex/config.toml` hinzu. `env_vars` leitet `SUPERSERVE_API_KEY` aus Ihrer Umgebung weiter, sodass der rohe Schlüssel nicht in der Konfigurationsdatei gespeichert wird (exportieren Sie ihn zuerst in Ihrer Shell). Codex liest auch die `instructions` des Servers für werkzeugübergreifende Workflow-Anleitungen.

```toml theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]
```

Verwenden Sie für den [gehosteten](#hosted-remote) Endpunkt `url = "https://mcp.superserve.ai"` mit `bearer_token_env_var = "SUPERSERVE_API_KEY"`.

Gehostet (remote)

Möchten Sie nichts lokal ausführen? Der gehostete Endpunkt unter https://mcp.superserve.ai spricht Streamable HTTP – kein npx, kein Node. Senden Sie Ihren Superserve-API-Schlüssel als Bearer-Token. Der Endpunkt ist zustandslos und kontobezogen (Ihr Schlüssel ist bereits Ihrem Team zugeordnet), und das Data-Plane-Token pro Sandbox verlässt den Server nie.

Hinweis

Die Bearer-Authentifizierung funktioniert in jedem Client, der das Setzen eines Request-Headers erlaubt – Claude Code, Cursor, VS Code und der Anthropic Messages API Connector. Claude.ai, die Custom-Connector-Oberfläche von Claude Desktop und der ChatGPT-Entwicklermodus bieten kein statisches Bearer-/benutzerdefiniertes Header-Feld (sie erwarten OAuth), was der gehostete Endpunkt noch nicht unterstützt – verwenden Sie dort die lokale Installation.

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add --transport http superserve https://mcp.superserve.ai \ --header "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx" ``` Fügen Sie zu `.cursor/mcp.json` (Projekt) oder `~/.cursor/mcp.json` (global) hinzu:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

Fügen Sie zu `.vscode/mcp.json` hinzu. Der `inputs`-Block fordert zur Eingabe des Schlüssels auf, anstatt ihn im Klartext zu speichern:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "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}" }
    }
  }
}
```

Übergeben Sie ihn als Connector in einer [Anthropic Messages API](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector)-Anfrage:

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcp_servers": [
    {
      "type": "url",
      "name": "superserve",
      "url": "https://mcp.superserve.ai",
      "authorization_token": "ss_live_xxxxxxxxxxxxxxxx"
    }
  ]
}
```

Gleiche Tools und gleiches Verhalten wie beim lokalen Server – der einzige Unterschied ist der Transport und dass der Schlüssel als Bearer-Header statt als env-Variable reist.

Tools

Tool	Funktion
sandbox_create	Erstellt eine neue Sandbox; gibt deren id zurück. Akzeptiert secrets, Egress-Regeln und preview_access.
sandbox_update	Ändert Metadaten, Egress-Regeln, Lebenszyklusfenster oder preview_access.
sandbox_list	Listet Ihre Sandboxes (aktiv und pausiert) auf, filterbar nach Metadaten.
sandbox_info	Ruft Status, Ressourcen, Metadaten, Netzwerkregeln und Secret-Bindungen einer Sandbox ab. Schreibgeschützt.
sandbox_exec	Führt einen Shell-Befehl aus; gibt stdout, stderr und Exit-Code zurück. Setzt eine pausierte Sandbox automatisch fort.
sandbox_files_read	Liest eine Datei (UTF-8-Text oder base64 für Binärdaten).
sandbox_files_write	Erstellt oder überschreibt eine Datei. Übergeordnete Verzeichnisse werden automatisch erstellt.
sandbox_files_list	Listet die Einträge eines Verzeichnisses auf (Name, Typ, Größe, Änderungszeit).
sandbox_files_download_dir	Lädt ein Verzeichnis als base64-ZIP herunter (Symlinks werden übersprungen). Auf 10 MiB begrenzt; größer → SDK/CLI.
sandbox_pause	Pausiert eine Sandbox; der Zustand bleibt erhalten.
sandbox_resume	Setzt eine pausierte Sandbox fort (normalerweise unnötig – exec setzt automatisch fort).
sandbox_kill	Löscht eine Sandbox dauerhaft.
sandbox_preview_url	Veröffentlicht einen Port und gibt eine saubere öffentliche URL oder eine ablaufende private signierte URL zurück.
sandbox_network_log	Prüft die ausgehenden Verbindungen einer Sandbox (Host, Urteil, Bytes), ohne sie fortzusetzen.
sandbox_template_list	Listet die Templates (Basis-Images) auf, die Ihr Team starten kann.
sandbox_template_create	Erstellt ein benutzerdefiniertes Template mit einer bestimmten vCPU-/Speicher-/Festplattenform oder vorinstallierter Software (asynchron – auf Bereitschaft abfragen).
secret_list	Listet bindbare Team-Secrets auf (nur Metadaten – niemals Werte).
sandbox_attach_secret	Bindet ein gespeichertes Secret an eine laufende Sandbox unter einer Umgebungsvariable.
sandbox_detach_secret	Entfernt eine Secret-Bindung von einer Sandbox.

Die meisten Tools benötigen eine sandbox_id; die Ausnahmen sind sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create und secret_list. Beginnen Sie mit einem davon, um eine ID zu erhalten, und reichen Sie sie dann in spätere Aufrufe weiter. Schreibgeschützte Tools (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_network_log, sandbox_template_list, secret_list) sind annotiert, sodass Clients Bestätigungsaufforderungen überspringen können; sandbox_preview_url ist ein idempotenter Schreibvorgang, da es den angeforderten Port veröffentlicht, und sandbox_kill ist als destruktiv annotiert.

Beispiel

Ein typischer Agentenablauf für „eine Sandbox hochfahren, ein Python-Skript schreiben, das die ersten Primzahlen ausgibt, und es ausführen":

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

Wenn es fertig ist, kann der Agent sandbox_pause (Zustand bleibt erhalten, günstiger zu behalten) oder sandbox_kill (dauerhaft) ausführen.

Konfiguration

Variable	Erforderlich	Beschreibung
SUPERSERVE_API_KEY	Ja	Ihr Superserve-API-Schlüssel (beginnt mit ss_live_).
SUPERSERVE_BASE_URL	Nein	Überschreibt die Control-Plane-URL (Standard: https://api.superserve.ai).

Verhalten und Grenzen

• Automatische Fortsetzung. sandbox_exec und die Datei-Tools setzen eine pausierte Sandbox transparent fort, sodass Agenten nie zuerst sandbox_resume aufrufen müssen. sandbox_resume existiert nur, um eine Sandbox explizit aufzuwärmen.
• Ausgabe ist für den Kontext begrenzt. sandbox_exec kürzt stdout und stderr auf jeweils 32 KiB – ein gekürztes Ergebnis setzt truncated: true und meldet die ursprüngliche Bytelänge. sandbox_files_read lehnt Dateien größer als 1 MiB ab (es gibt keine Teilinhalte zurück); die Fehlermeldung weist Sie an, einen Ausschnitt mit sandbox_exec zu lesen (z. B. head -c) oder die gesamte Datei mit dem SDK/CLI herunterzuladen. sandbox_files_write Inline-Inhalte sind auf 8 MiB begrenzt.
• Das Standard-Timeout für Befehle beträgt 60 s, maximal 10 Minuten. Überschreiben Sie es pro Aufruf mit timeout_ms.
• Egress ist steuerbar. allow_out (Domain-Muster oder CIDRs) fügt erlaubte Ziele hinzu; deny_out (nur CIDRs) blockiert sie. allow_out allein sperrt eine Sandbox nicht ab – für eine strikte Allowlist kombinieren Sie es mit deny_out: ["0.0.0.0/0"] (alles verweigern, dann die gelisteten Ziele erlauben). Setzen Sie diese bei sandbox_create oder sandbox_update und prüfen Sie mit sandbox_network_log, was eine Sandbox tatsächlich erreicht hat.
• Fehler sind handlungsorientiert. Ein fehlgeschlagener Tool-Aufruf gibt eine kurze Meldung zurück, die dem Agenten sagt, was als Nächstes zu tun ist – z. B. „Sandbox-Kontingent erreicht. Pausieren oder beenden Sie eine Sandbox oder versuchen Sie es später erneut." – statt eines rohen Stack-Traces, damit der Agent sich selbst korrigieren kann.

Secrets, Templates und Ports

Secrets. Übergeben Sie Anmeldedaten nicht als Klartext-env_vars. Stattdessen:

1. Erstellen Sie das Secret einmal mit dem TypeScript SDK (Secret.create()) oder der Konsole – der rohe Wert reist nie durch den Agenten oder den MCP-Server, daher ist die Secret-Erstellung bewusst kein MCP-Tool.
2. Entdecken Sie bindbare Secrets mit secret_list (nur Metadaten – Werte verlassen nie die Plattform).
3. Binden Sie bei der Erstellung – secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } bei sandbox_create – oder später mit sandbox_attach_secret / sandbox_detach_secret.

Die Sandbox sieht ein Proxy-Token; die Plattform tauscht die echte Anmeldedaten nur für ausgehende Anfragen an die erlaubten Hosts des Secrets ein.

Templates. Eine Sandbox erbt ihre vCPU-/Speicher-/Festplattenkonfiguration von ihrem Template und kann sie zum Zeitpunkt von sandbox_create nicht überschreiben. Um eine bestimmte Form (z. B. eine 4-vCPU-Sandbox) oder vorinstallierte Software zu erhalten, erstellen Sie ein Template mit sandbox_template_create und fragen Sie dann sandbox_template_list ab, bis dessen status ready ist, bevor Sie es als from_template übergeben.

Ports. Neue MCP-Sandboxes verwenden public als Standardzugriff für neu veröffentlichte Ports; nur explizit veröffentlichte Ports sind erreichbar. Übergeben Sie preview_access: "private" an sandbox_create (oder sandbox_update), um den Standard für zukünftige Ports zu ändern. Bestehende Ports behalten ihren eigenen Modus. Starten Sie den Server mit sandbox_exec und rufen Sie dann sandbox_preview_url auf; das Tool veröffentlicht idempotent diesen einen Port und verwendet den zurückgegebenen Portmodus, um entweder eine saubere öffentliche URL oder eine ablaufende private signierte URL zurückzugeben. Private Links standardmäßig eine Stunde gültig; setzen Sie expires_in_seconds auf einen Wert von 1 bis 604800 Sekunden. Siehe Vorschau-URLs.

Noch nicht in der MCP-Oberfläche

Der MCP-Server deckt die übliche Agentenschleife ab; die obige Tabelle ist der vollständige v1-Toolsatz. Einige SDK-Funktionen sind noch nicht verfügbar – greifen Sie für diese direkt zum TypeScript SDK:

• Geheimerstellung — Secret.create() (der MCP-Server bindet nur vorhandene Geheimnisse).
• Streaming- und interaktive Befehle — Streaming-run()-Callbacks und commands.spawn (stdin, Signale, langlebige Prozesse).
• Große oder Streaming-Übertragungen — Der Verzeichnis-Download wird bis zu 10 MiB über sandbox_files_download_dir unterstützt; darüber hinaus (und für Archiv-/Streaming-Uploads oder einzelne Dateien über den 1-MiB-Lese- bzw. 8-MiB-Inline-Schreibgrenzen) verwenden Sie das SDK/CLI (files.downloadDir, Streaming-Upload).
• Abrechnung und Provider-Erkennung — Nutzungsdaten und Provider.list() für die Einrichtung des Secret-Providers.

Diese werden als Folgeaufgaben erfasst.

So funktioniert es

Der Server kapselt das TypeScript-SDK und hält nur Ihr Control-Plane-SUPERSERVE_API_KEY. Jeder Tool-Aufruf verbindet sich über die ID mit der Ziel-Sandbox; das SDK verwaltet das Data-Plane-Zugriffstoken pro Sandbox intern und rotiert es bei Wiederaufnahme, sodass es niemals dem Modell ausgesetzt oder in der Tool-Ausgabe zurückgegeben wird. Tools sind zustandslos — es gibt keine versteckte „aktuelle Sandbox" —, was das Verhalten über mehrstufige und parallele Tool-Aufrufe hinweg vorhersehbar hält.

Fehlerbehebung

• Tools erscheinen nicht, oder der Server startet nicht. Der API-Schlüssel ist fast immer die Ursache — MCP-Clients erben keine Umgebungsvariablen von Ihrer Shell. Setzen Sie SUPERSERVE_API_KEY im env-Block des Servers (siehe Installation), nicht nur in Ihrem Terminal.
• Authentication failed. Der Schlüssel fehlt oder ist ungültig. Produktionsschlüssel beginnen mit ss_live_; erstellen Sie einen auf der Seite API-Schlüssel.
• Der erste Aufruf ist langsam. npx lädt das Paket bei der ersten Verwendung herunter und speichert es zwischen; spätere Starts sind schnell.
• Erfordert Node 18+. Der lokale Server läuft auf Node über npx. (Der gehostete Endpunkt hat keine lokale Laufzeit-Anforderung.)
• 401 Unauthorized vom gehosteten Endpunkt. Das Bearer-Token fehlt oder ist kein gültiger ss_live_-Schlüssel. Senden Sie es als Authorization: Bearer ss_live_… (siehe Gehostet).

Verwandtes

Sandboxes pausieren, fortsetzen und löschen. Exec, Streaming, cwd, env und Timeouts. Broker-Provider-Schlüssel, ohne sie der Sandbox auszusetzen. Die Bibliothek, die der MCP-Server kapselt.