Superserve Sandbox MCP

Serveur MCP

Créez, exécutez et gérez des sandboxes Superserve depuis n'importe quel client MCP.

Vous cherchez à laisser un agent créer lui-même des sandboxes ? Ce serveur MCP le permet.

Le serveur MCP Superserve (@superserve/mcp) expose les primitives de sandbox sous forme d'outils Model Context Protocol, afin que tout client compatible MCP — Claude, Cursor, VS Code, Windsurf, Codex — puisse créer des sandboxes, exécuter des commandes, lire et écrire des fichiers, construire des modèles, gérer des secrets et contrôler l'accès réseau dans une microVM Firecracker isolée.

Deux modes d'exécution : localement via stdio avec npx, ou via le point de terminaison hébergé à https://mcp.superserve.ai sans installation locale. Les deux s'authentifient avec votre SUPERSERVE_API_KEY et ciblent une sandbox par appel via son identifiant. C'est une surcouche légère du TypeScript SDK, donc le jeton de plan de données par sandbox n'atteint jamais le modèle.

Démarrage rapide

Ajoutez le serveur à votre client (voir Installation), puis demandez à l'agent de « créer une sandbox et exécuter python --version dedans ». L'agent appelle sandbox_create, puis sandbox_exec, et rapporte le résultat — sans aucun code de votre part.

Vous avez besoin d'une clé API Superserve — créez-en une sur la page clé API. Aucune installation globale n'est requise ; npx récupère le serveur au premier usage.

Installation

Remarque

Définissez SUPERSERVE_API_KEY dans le env du serveur — les clients MCP ne l'héritent pas de votre shell. Privilégiez une invite de saisie secrète plutôt que de coller la clé brute là où votre client le permet (voir VS Code ci-dessous).

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` Ajoutez à `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" }
    }
  }
}
```

Ajoutez à `.cursor/mcp.json` (projet) ou `~/.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" }
    }
  }
}
```

Ajoutez à `.vscode/mcp.json`. Le bloc `inputs` invite à saisir la clé au lieu de la stocker en texte brut :

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

Ajoutez à `~/.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" }
    }
  }
}
```

Ajoutez à `~/.codex/config.toml`. `env_vars` transmet `SUPERSERVE_API_KEY` depuis votre environnement, donc la clé brute n'est pas stockée dans le fichier de configuration (exportez-la d'abord dans votre shell). Codex lit également le `instructions` du serveur pour des conseils de flux de travail entre outils.

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

Pour le point de terminaison [hébergé](#hosted-remote), utilisez `url = "https://mcp.superserve.ai"` avec `bearer_token_env_var = "SUPERSERVE_API_KEY"`.

Hébergé (distant)

Vous ne voulez rien exécuter localement ? Le point de terminaison hébergé à https://mcp.superserve.ai parle Streamable HTTP — pas de npx, pas de Node. Envoyez votre clé API Superserve comme jeton porteur. Le point de terminaison est sans état et limité au compte (votre clé correspond déjà à votre équipe), et le jeton de plan de données par sandbox ne quitte jamais le serveur.

Remarque

L'authentification par jeton porteur fonctionne dans tout client qui permet de définir un en-tête de requête — Claude Code, Cursor, VS Code et le connecteur Anthropic Messages API. Claude.ai, l'interface Custom Connector de Claude Desktop et le mode développeur ChatGPT n'offrent pas de champ jeton statique / en-tête personnalisé (ils attendent OAuth), ce que le point de terminaison hébergé ne prend pas encore en charge — utilisez l'installation locale dans ce cas.

```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" ``` Ajoutez à `.cursor/mcp.json` (projet) ou `~/.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" }
    }
  }
}
```

Ajoutez à `.vscode/mcp.json`. Le bloc `inputs` invite à saisir la clé au lieu de la stocker en texte brut :

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

Passez-le comme connecteur dans une requête [Anthropic Messages API](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector) :

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

Mêmes outils et comportement que le serveur local — la seule différence est le transport et le fait que la clé voyage comme en-tête porteur au lieu d'une variable env.

Outils

Outil	Ce qu'il fait
sandbox_create	Crée une nouvelle sandbox ; renvoie son id. Accepte secrets, des règles de sortie et preview_access.
sandbox_update	Modifie les métadonnées, les règles de sortie, les fenêtres de cycle de vie ou preview_access.
sandbox_list	Liste vos sandboxes (actives et en pause), filtrables par métadonnées.
sandbox_info	Obtient le statut, les ressources, les métadonnées, les règles réseau et les liaisons de secrets d'une sandbox. Lecture seule.
sandbox_exec	Exécute une commande shell ; renvoie stdout, stderr, code de sortie. Reprend automatiquement une sandbox en pause.
sandbox_files_read	Lit un fichier (texte UTF-8, ou base64 pour les binaires).
sandbox_files_write	Crée ou écrase un fichier. Les répertoires parents sont créés automatiquement.
sandbox_files_list	Liste les entrées d'un répertoire (nom, type, taille, heure de modification).
sandbox_files_download_dir	Télécharge un répertoire sous forme de ZIP base64 (liens symboliques ignorés). Limité à 10 Mio ; plus grand → SDK/CLI.
sandbox_pause	Met une sandbox en pause ; l'état est préservé.
sandbox_resume	Reprend une sandbox en pause (généralement inutile — exec reprend automatiquement).
sandbox_kill	Supprime définitivement une sandbox.
sandbox_preview_url	Publie un port et renvoie une URL publique propre ou une URL privée signée à expiration.
sandbox_network_log	Audite les connexions sortantes d'une sandbox (hôte, verdict, octets) sans la reprendre.
sandbox_computer	Pilote une sandbox de bureau GUI : capture d'écran, souris, clavier, défilement, redimensionnement, URL de visionneuse. Une action par appel.
sandbox_template_list	Liste les modèles (images de base) que votre équipe peut lancer.
sandbox_template_create	Construit un modèle personnalisé avec une forme vCPU/mémoire/disque spécifique ou des logiciels préinstallés (asynchrone — interrogez jusqu'à prêt).
secret_list	Liste les secrets d'équipe liables (métadonnées uniquement — jamais les valeurs).
sandbox_attach_secret	Lie un secret stocké à une sandbox en cours d'exécution sous une variable d'environnement.
sandbox_detach_secret	Supprime une liaison de secret d'une sandbox.

La plupart des outils prennent un sandbox_id ; les exceptions sont sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create et secret_list. Commencez par l'un de ceux-ci pour obtenir un identifiant, puis transmettez-le dans les appels suivants. Les outils en lecture seule (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_network_log, sandbox_template_list, secret_list) sont annotés pour que les clients puissent ignorer les invites de confirmation ; sandbox_preview_url est une écriture idempotente car elle publie le port demandé, et sandbox_kill est annoté destructif.

Exemple

Un flux d'agent typique pour « lancer une sandbox, écrire un script Python qui affiche les premiers nombres premiers, et l'exécuter » :

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

Une fois terminé, l'agent peut sandbox_pause (état préservé, moins cher à conserver) ou sandbox_kill (permanent).

Configuration

Variable	Requise	Description
SUPERSERVE_API_KEY	Oui	Votre clé API Superserve (commence par ss_live_).
SUPERSERVE_BASE_URL	Non	Remplace l'URL du plan de contrôle (par défaut https://api.superserve.ai).

Comportement et limites

• Reprise automatique. sandbox_exec et les outils de fichiers reprennent de manière transparente une sandbox en pause, donc les agents n'ont jamais besoin d'appeler sandbox_resume d'abord. sandbox_resume existe uniquement pour réchauffer explicitement une sandbox.
• La sortie est plafonnée pour le contexte. sandbox_exec tronque stdout et stderr à 32 Kio chacun — un résultat tronqué définit truncated: true et rapporte la longueur originale en octets. sandbox_files_read rejette les fichiers de plus de 1 Mio (il ne renvoie pas de contenu partiel) ; l'erreur vous indique de lire une tranche avec sandbox_exec (par ex. head -c) ou de télécharger le fichier entier avec le SDK/CLI. Le contenu en ligne de sandbox_files_write est plafonné à 8 Mio.
• Le délai d'expiration par défaut des commandes est de 60 s, plafonné à 10 minutes. Remplacez-le par appel avec timeout_ms.
• La sortie est contrôlable. allow_out (motifs de domaine, IP ou CIDR) ajoute des destinations autorisées ; deny_out (IP ou CIDR, pas de domaines) les bloque. allow_out seul ne verrouille pas une sandbox — pour une liste blanche stricte, combinez-le avec deny_out: ["0.0.0.0/0"] (tout refuser, puis autoriser les destinations listées). Si la liste blanche contient des règles de domaine ou si la charge de travail résout des noms d'hôte, autorisez aussi les résolveurs DNS de la sandbox, 1.1.1.1/32 et 8.8.8.8/32, car tout-refuser bloque aussi le DNS ; laissez-les hors d'une liste blanche IP uniquement, où un résolveur autorisé n'est qu'un canal sortant supplémentaire. Définissez-les sur sandbox_create ou sandbox_update, et auditez ce qu'une sandbox a réellement atteint avec sandbox_network_log.
• Les erreurs sont exploitables. Un appel d'outil échoué renvoie un message court indiquant à l'agent quoi faire ensuite — par ex. « Quota de sandbox atteint. Mettez en pause ou tuez une sandbox, ou réessayez plus tard. » — plutôt qu'une trace de pile brute, afin que l'agent puisse s'auto-corriger.

Secrets, modèles et ports

Secrets. Ne transmettez pas d'identifiants en clair via env_vars. À la place :

1. Créez le secret une fois avec le TypeScript SDK (Secret.create()) ou la console — la valeur brute ne transite jamais par l'agent ou le serveur MCP, donc la création de secret n'est volontairement pas un outil MCP.
2. Découvrez les secrets liables avec secret_list (métadonnées uniquement — les valeurs ne quittent jamais la plateforme).
3. Liez à la création — secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } sur sandbox_create — ou plus tard avec sandbox_attach_secret / sandbox_detach_secret.

La sandbox voit un jeton proxy ; la plateforme échange le véritable identifiant uniquement pour les requêtes sortantes vers les hôtes autorisés du secret.

Modèles. Une sandbox hérite de son vCPU/mémoire/disque de son modèle et ne peut pas les remplacer au moment de sandbox_create. Pour obtenir une forme spécifique (par ex. une sandbox 4 vCPU) ou des logiciels préinstallés, construisez un modèle avec sandbox_template_create, puis interrogez sandbox_template_list jusqu'à ce que son status soit ready avant de le passer comme from_template.

Ports. Les nouvelles sandboxes MCP utilisent public comme accès par défaut pour les ports nouvellement publiés ; seuls les ports explicitement publiés sont accessibles. Passez preview_access: "private" à sandbox_create (ou sandbox_update) pour changer le défaut pour les futurs ports. Les ports existants conservent leur propre mode. Démarrez le serveur avec sandbox_exec, puis appelez sandbox_preview_url ; l'outil publie de manière idempotente ce seul port et utilise le mode de port renvoyé pour renvoyer soit une URL publique propre, soit une URL privée signée à expiration. Les liens privés par défaut durent une heure ; définissez expires_in_seconds sur une valeur de 1 à 604800 secondes. Voir URLs d'aperçu.

Utilisation informatique

sandbox_computer pilote un bureau GUI dans une sandbox créée à partir d'un modèle de bureau tel que superserve/desktop. Il prend une action par appel dans le vocabulaire que les modèles d'utilisation informatique émettent : 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 et stream_url. Les actions de pointeur prennent coordinate: [x, y] en pixels d'écran (origine en haut à gauche) ; key et type prennent text ; scroll prend scroll_direction et un scroll_amount optionnel.

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

Les actions d'entrée renvoient une nouvelle capture d'écran du résultat, donc le tour agir-puis-regarder du modèle est un seul appel d'outil ; passez screenshot_after: false lors de l'envoi de plusieurs actions à la suite. wait fait une pause de duration_ms (plafonné à 10 secondes) sans requête à la sandbox. stream_url renvoie une visionneuse navigateur en direct pour le bureau sous la politique d'aperçu de la sandbox.

Si une action d'entrée échoue, l'entrée a peut-être déjà été délivrée. L'outil le dit et demande à l'agent de prendre une capture d'écran avant de la répéter. Voir le Guide de bureau pour la surface SDK sous-jacente.

Pas encore dans la surface MCP

Le serveur MCP couvre la boucle d'agent courante ; le tableau ci-dessus constitue l'ensemble complet des outils v1. Certaines capacités du SDK ne sont pas encore exposées — utilisez directement le SDK TypeScript pour :

• Création de secrets — Secret.create() (le serveur MCP ne fait que lier des secrets existants).
• Commandes interactives et en streaming — streaming des callbacks run() et commands.spawn (stdin, signaux, processus de longue durée).
• Transferts volumineux ou en streaming — le téléchargement de répertoires est pris en charge jusqu'à 10 Mio via sandbox_files_download_dir ; au-delà (et pour les téléversements d'archives/streaming ou les fichiers individuels dépassant les limites de 1 Mio en lecture / 8 Mio en écriture en ligne), utilisez le SDK/CLI (files.downloadDir, téléversement en streaming).
• Facturation et découverte de fournisseurs — données d'utilisation et Provider.list() pour la configuration des fournisseurs de secrets.

Ces points sont suivis comme améliorations futures.

Fonctionnement

Le serveur encapsule le SDK TypeScript et ne conserve jamais que votre SUPERSERVE_API_KEY du plan de contrôle. Chaque appel d'outil se connecte au sandbox cible par son ID ; le SDK gère le jeton d'accès au plan de données propre à chaque sandbox en interne et le fait tourner lors de la reprise, de sorte qu'il n'est jamais exposé au modèle ni renvoyé dans la sortie des outils. Les outils sont sans état — il n'y a pas de « sandbox courant » caché — ce qui maintient un comportement prévisible lors des appels multi-tours et parallèles.

Dépannage

• Les outils n'apparaissent pas, ou le serveur ne démarre pas. La clé API en est presque toujours la cause — les clients MCP n'héritent pas des variables d'environnement de votre shell. Définissez SUPERSERVE_API_KEY dans le bloc env du serveur (voir Installation), pas seulement dans votre terminal.
• Authentication failed. La clé est manquante ou invalide. Les clés de production commencent par ss_live_ ; créez-en une sur la page Clé API.
• Le premier appel est lent. npx télécharge le paquet lors de la première utilisation et le met en cache ; les démarrages suivants sont rapides.
• Nécessite Node 18+. Le serveur local s'exécute sur Node via npx. (Le point de terminaison hébergé n'a aucune exigence d'exécution locale.)
• 401 Unauthorized du point de terminaison hébergé. Le jeton porteur est manquant ou n'est pas une clé ss_live_ valide. Envoyez-le comme Authorization: Bearer ss_live_… (voir Hébergé).

Liens connexes

Mettre en pause, reprendre et supprimer des sandboxes. Exécution, streaming, cwd, env et délais d'attente. Gérer les clés de fournisseur sans les exposer au sandbox. La bibliothèque que le serveur MCP encapsule.

Cette documentation est construite et hébergée sur Mintlify, une plateforme de documentation pour développeurs.