Superserve Sandbox MCP

MCP-Server

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

Möchten Sie, dass ein Agent selbst Sandboxes erstellt? Dieser MCP-Server übernimmt 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, Vorlagen erstellen, 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 über 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 ab. 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 den Agenten dann, „eine Sandbox zu erstellen und python --version darin auszuführen.“ Der Agent ruft sandbox_create, dann sandbox_exec auf 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 ihn 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 Verhalten wie der lokale Server – der einzige Unterschied ist der Transport und dass der Schlüssel als Bearer-Header statt als env-Variable reist.

Tools

Tool	Was es tut
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 den Status, die 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). 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	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_computer	Steuert eine GUI-Desktop-Sandbox: Screenshot, Maus, Tastatur, Scrollen, Größenänderung, Viewer-URL. Eine Aktion pro Aufruf.
sandbox_template_list	Listet die Vorlagen (Basis-Images) auf, die Ihr Team starten kann.
sandbox_template_create	Erstellt eine benutzerdefinierte Vorlage 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 akzeptieren 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 führen Sie sie dann in spätere Aufrufe ein. 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 angefragten 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); der Fehler sagt Ihnen, 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-Timeout für Befehle ist 60 s, begrenzt auf 10 Minuten. Überschreiben Sie es pro Aufruf mit timeout_ms.
• Egress ist steuerbar. allow_out (Domain-Muster, IPs oder CIDRs) fügt erlaubte Ziele hinzu; deny_out (IPs oder CIDRs, keine Domains) blockiert sie. allow_out allein sperrt eine Sandbox nicht vollständig – für eine strikte Allowlist kombinieren Sie es mit deny_out: ["0.0.0.0/0"] (alles verweigern, dann die gelisteten Ziele erlauben). Wenn die Allowlist Domain-Regeln hat oder die Workload Hostnamen auflöst, erlauben Sie auch die DNS-Resolver der Sandbox, 1.1.1.1/32 und 8.8.8.8/32, da „alles verweigern“ auch DNS blockiert; lassen Sie sie aus einer reinen IP-Allowlist heraus, wo ein erlaubter Resolver nur ein zusätzlicher ausgehender Kanal ist. 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 umsetzbar. Ein fehlgeschlagener Tool-Aufruf gibt eine kurze Nachricht 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, sodass der Agent sich selbst korrigieren kann.

Secrets, Vorlagen und Ports

Secrets. Übergeben Sie Anmeldeinformationen 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 Anmeldeinformation nur für ausgehende Anfragen an die erlaubten Hosts des Secrets ein.

Vorlagen. Eine Sandbox erbt ihre vCPU-/Speicher-/Festplattenkonfiguration von ihrer Vorlage 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 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. 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 diesen einen Port idempotent 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; setzen Sie expires_in_seconds auf einen Wert von 1 bis 604800 Sekunden. Siehe Vorschau-URLs.

Computernutzung

sandbox_computer steuert einen GUI-Desktop in einer Sandbox, die aus einer Desktop- Vorlage wie superserve/desktop erstellt wurde. Es nimmt eine action pro Aufruf im Vokabular, das Computernutzungsmodelle ausgeben: screenshot, left_click, right_click, middle_click, double_click, triple_click, left_click_drag, left_mouse_down, left_mouse_up, mouse_move, key, type, scroll, wait, resize und stream_url. Zeigeraktionen nehmen coordinate: [x, y] in Bildschirmpixeln (Ursprung oben links); key und type nehmen text; scroll nimmt scroll_direction und ein optionales scroll_amount.

sandbox_create    { name: "browser", from_template: "superserve/desktop" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "left_click", coordinate: [640, 32] }
                    → text "left_click done (1280x800)" + image/png
sandbox_computer  { sandbox_id: "a1b2c3…", action: "type", text: "https://example.com" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "key", text: "Return" }

Eingabeaktionen geben einen frischen Screenshot des Ergebnisses zurück, sodass die Aktion-dann-Schauen-Runde des Modells ein Tool-Aufruf ist; übergeben Sie screenshot_after: false, wenn Sie mehrere Aktionen hintereinander senden. wait pausiert für duration_ms (begrenzt auf 10 Sekunden) ohne eine Anfrage an die Sandbox. stream_url gibt einen Live- Browser-Viewer für den Desktop unter der Vorschau-Richtlinie der Sandbox zurück.

Wenn eine Eingabeaktion fehlschlägt, wurde die Eingabe möglicherweise bereits zugestellt. Das Tool sagt dies und bittet den Agenten, vor der Wiederholung einen Screenshot zu machen. Siehe den Desktop-Leitfaden für die zugrunde liegende SDK-Oberfläche.

Noch nicht in der MCP-Oberfläche

Der MCP-Server deckt den üblichen Agenten-Loop ab; die Tabelle oben ist der vollständige v1-Toolsatz. Einige SDK-Funktionen sind noch nicht verfügbar – greifen Sie direkt auf das TypeScript SDK zu für:

• Geheimniserstellung – 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 – 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 die 1-MiB-Lese- / 8-MiB-Inline-Schreibgrenzen hinaus) verwenden Sie das SDK/CLI (files.downloadDir, Streaming-Upload).
• Abrechnung und Provider-Erkennung – Nutzungsdaten und Provider.list() für die Einrichtung von Secret-Providern.

Diese sind als Folgeaufgaben erfasst.

So funktioniert es

Der Server umschließt das TypeScript SDK und hält nur Ihr Control-Plane-SUPERSERVE_API_KEY. Jeder Tool-Aufruf verbindet sich per 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 API-Schlüssel-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 ü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).

Verwandt

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 umschließt.

Diese Dokumentation wird auf Mintlify erstellt und gehostet, einer Plattform für Entwicklerdokumentation.