Superserve Sandbox MCP

MCP-Server

Erstellen, ausführen und verwalten Sie Superserve-Sandboxen von jedem MCP-Client aus.

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

Führen Sie ihn auf zwei Arten aus: lokal über stdio mittels 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 anhand der 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 und dann sandbox_exec auf und meldet das Ergebnis – kein 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 ruft den Server bei der ersten Verwendung ab.

Installation

Setzen Sie `SUPERSERVE_API_KEY` in der `env` des Servers – MCP-Clients erben ihn nicht von Ihrer Shell. Bevorzugen Sie eine Eingabeaufforderung für Geheimnisse gegenüber dem Einfügen des Rohschlü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 ``` Hinzufügen zu `claude_desktop_config.json` (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" }
    }
  }
}
```

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

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

Hinzufügen zu `.vscode/mcp.json`. Der `inputs`-Block fragt nach dem Schlüssel, 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}" }
    }
  }
}
```

Hinzufügen zu `~/.codeium/windsurf/mcp_config.json`:

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

Hinzufügen zu `~/.codex/config.toml`. `env_vars` leitet `SUPERSERVE_API_KEY` aus Ihrer Umgebung weiter, sodass der Rohschlüssel nicht in der Konfigurationsdatei gespeichert wird (exportieren Sie ihn zuerst in Ihrer Shell). Codex liest auch die `instructions` des Servers für die Anleitung zu toolübergreifenden Workflows.

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

Für den [gehosteten](#hosted-remote) Endpunkt verwenden Sie `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.

Die Bearer-Authentifizierung funktioniert in jedem Client, der das Setzen eines Anfrage-Headers erlaubt – Claude Code, Cursor, VS Code und der Anthropic Messages API-Connector. Claude.ai, die Custom Connector-Benutzeroberfläche von Claude Desktop und der ChatGPT-Entwicklermodus bieten kein Feld für statische Bearer-/benutzerdefinierte Header (sie erwarten OAuth), was der gehostete Endpunkt noch nicht unterstützt – verwenden Sie dort die [lokale](#install) 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" ``` Hinzufügen zu `.cursor/mcp.json` (Projekt) oder `~/.cursor/mcp.json` (global):

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

Hinzufügen zu `.vscode/mcp.json`. Der `inputs`-Block fragt nach dem Schlüssel, 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"
    }
  ]
}
```

Dieselben Werkzeuge und dasselbe Verhalten wie beim lokalen Server – der einzige Unterschied ist der Transport und dass der Schlüssel als Bearer-Header anstelle einer env-Variable übertragen wird.

Werkzeuge

Werkzeug	Was es tut
sandbox_create	Erstellt eine neue Sandbox; gibt deren id zurück. Sofort aktiv und bereit. Akzeptiert secrets und Egress-Regeln.
sandbox_update	Ändert die Metadaten oder Egress-Regeln (allow_out/deny_out) einer Sandbox nach der Erstellung.
sandbox_list	Listet Ihre Sandboxen auf (aktiv und pausiert), filterbar nach Metadaten.
sandbox_info	Ruft Status, Ressourcen, Metadaten, Netzwerkregeln und Geheimnisbindungen einer Sandbox ab. Schreibgeschützt.
sandbox_exec	Führt einen Shell-Befehl aus; gibt stdout, stderr, Exit-Code zurück. Setzt eine pausierte Sandbox automatisch fort.
sandbox_files_read	Liest eine Datei (UTF-8-Text oder base64 für Binärdateien).
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 (symbolische Links werden übersprungen). Begrenzt auf 10 MiB; 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	Erstellt die öffentliche URL für einen lauschenden Port (unauthentifiziert – alles auf diesem Port ist dem Internet ausgesetzt).
sandbox_network_log	Überprüft die ausgehenden Verbindungen einer Sandbox (Host, Urteil, Bytes). Setzt eine pausierte Sandbox automatisch fort.
sandbox_template_list	Listet die Vorlagen (Basis-Images) auf, von denen Ihr Team starten kann.
sandbox_template_create	Erstellt eine benutzerdefinierte Vorlage mit einer bestimmten vCPU-/Speicher-/Festplattenform oder vorinstallierter Software (asynchron – Abfrage bis bereit).
secret_list	Listet bindbare Team-Geheimnisse auf (nur Metadaten – niemals Werte).
sandbox_attach_secret	Bindet ein gespeichertes Geheimnis unter einer Umgebungsvariable an eine laufende Sandbox.
sandbox_detach_secret	Entfernt eine Geheimnisbindung aus einer Sandbox.

Die meisten Werkzeuge benötigen eine sandbox_id; 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 verwenden Sie diese dann in späteren Aufrufen. Schreibgeschützte Werkzeuge (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_preview_url, sandbox_template_list, secret_list) sind so gekennzeichnet, dass Clients Bestätigungsaufforderungen überspringen können; sandbox_kill ist als destruktiv gekennzeichnet.

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 erhalten, günstiger aufzubewahren) oder sandbox_kill (dauerhaft).

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 ist https://api.superserve.ai).

Verhalten und Grenzen

• Automatische Fortsetzung. sandbox_exec und die Dateiwerkzeuge setzen eine pausierte Sandbox transparent fort, sodass Agenten niemals 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 Byte-Länge. sandbox_files_read lehnt Dateien ab, die größer als 1 MiB sind (es wird kein Teilinhalt zurückgegeben); der Fehler 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.
• Standard-Befehls-Timeout 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 Zulassungsliste kombinieren Sie es mit deny_out: ["0.0.0.0/0"] (alles verweigern, dann die aufgelisteten Ziele erlauben). Legen Sie diese bei sandbox_create oder sandbox_update fest und überprüfen Sie mit sandbox_network_log, was eine Sandbox tatsächlich erreicht hat.
• Fehler sind handlungsrelevant. Ein fehlgeschlagener Werkzeugaufruf gibt eine kurze Nachricht zurück, die dem Agenten mitteilt, 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." – anstelle eines rohen Stack-Trace, sodass der Agent sich selbst korrigieren kann.

Geheimnisse, Vorlagen und Ports

Geheimnisse. Übergeben Sie Anmeldeinformationen nicht als Klartext-env_vars. Stattdessen:

1. Erstellen Sie das Geheimnis einmal mit dem TypeScript SDK (Secret.create()) oder der Konsole – der Rohwert gelangt niemals durch den Agenten oder den MCP-Server, daher ist die Geheimniserstellung absichtlich kein MCP-Werkzeug.
2. Entdecken Sie bindbare Geheimnisse mit secret_list (nur Metadaten – Werte verlassen die Plattform nie).
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 echten Anmeldeinformationen nur für ausgehende Anfragen an die erlaubten Hosts des Geheimnisses ein.

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

Ports. Starten Sie einen Server in der Sandbox (sandbox_exec, z. B. python3 -m http.server 8000) und rufen Sie dann sandbox_preview_url auf, um dessen öffentliche URL zu erhalten. Jeder an einen Port gebundene Prozess ist unter https://{port}-{id}.sandbox.superserve.ai ohne Authentifizierung erreichbar – machen Sie nur Ports zugänglich, die öffentlich sein sollen.

Noch nicht in der MCP-Oberfläche

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

• Geheimniserstellung – Secret.create() (der MCP-Server bindet nur vorhandene Geheimnisse).
• Streaming und interaktive Befehle – Streaming von run()-Callbacks und commands.spawn (stdin, Signale, lang laufende Prozesse).
• Große oder Streaming-Übertragungen – Verzeichnisdownload wird bis zu 10 MiB über sandbox_files_download_dir unterstützt; darüber hinaus (und für Archiv-/Streaming-Uploads oder einzelne Dateien, die die 1-MiB-Lese- / 8-MiB-Inline-Schreibgrenzen überschreiten) verwenden Sie das SDK/CLI (files.downloadDir, Streaming-Upload).
• Abrechnung und Anbietererkennung – Nutzungsdaten und Provider.list() für die Einrichtung von Geheimnisanbietern.

Diese sind als Folgemaßnahmen vorgemerkt.

Wie es funktioniert

Der Server umschließt das TypeScript SDK und hält ausschließlich Ihren Control-Plane SUPERSERVE_API_KEY. Jeder Tool-Aufruf verbindet sich anhand der ID mit der Ziel-Sandbox; das SDK verwaltet das Data-Plane Access Token pro Sandbox intern und rotiert es beim Wiederaufnehmen, sodass es niemals dem Modell preisgegeben oder in der Tool-Ausgabe zurückgegeben wird. Tools sind zustandslos – es gibt keine versteckte „aktuelle Sandbox“ – was das Verhalten über mehrere Runden und parallele Tool-Aufrufe hinweg vorhersagbar hält.

Fehlerbehebung

• Tools erscheinen nicht oder der Server startet nicht. Der API-Schlüssel ist fast immer die Ursache – MCP-Clients übernehmen keine Umgebungsvariablen aus 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 API-Key-Seite.
• Erster 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 via npx. (Der gehostete Endpunkt hat keine lokale Laufzeitanforderung.)
• 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).

Verwandte Themen

Sandboxen pausieren, fortsetzen und löschen. Ausführung, Streaming, Arbeitsverzeichnis, Umgebungsvariablen und Timeouts. Broker-Provider-Schlüssel, ohne sie der Sandbox preiszugeben. Die Bibliothek, die der MCP-Server umschließt.