Superserve Sandbox MCP

officiel

Machines virtuelles sécurisées pour agents hébergés par Superserve

Voir sur superserve.aiEssayer ce MCPSponsorisé

Que pouvez-vous faire avec Superserve Sandbox MCP ?

Créer et exécuter des sandboxes — Demandez à votre assistant de lancer un sandbox avec sandbox_create et d'exécuter des commandes comme python --version via sandbox_exec.
Gérer les fichiers dans les sandboxes — Utilisez sandbox_files_write, sandbox_files_read et sandbox_files_list pour créer, consulter ou organiser des fichiers dans un sandbox.
Contrôler le cycle de vie des sandboxes — Mettez en pause, reprenez ou supprimez définitivement des sandboxes avec sandbox_pause, sandbox_resume et sandbox_kill pour gérer les ressources.
Publier des URL d'aperçu — Exposez un service en cours d'exécution en appelant sandbox_preview_url pour obtenir un lien public ou un lien privé à expiration.
Lier des secrets en toute sécurité — Attachez ou détachez des secrets d'équipe stockés aux sandboxes via sandbox_attach_secret et sandbox_detach_secret sans exposer les valeurs brutes.
Créer des modèles personnalisés — Créez des modèles de sandbox réutilisables avec des formes spécifiques de CPU/mémoire/disque en utilisant sandbox_template_create et listez-les avec sandbox_template_list.

Documentation

Serveur MCP

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

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

Le serveur MCP Superserve (@superserve/mcp) expose les primitives de sandbox comme 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.

Exécutez-le de deux manières : 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 ID. C'est une surcouche légère du SDK TypeScript, 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 — aucun code de votre part.

Vous avez besoin d'une clé API Superserve — créez-en une sur la page clé API. Il n'y a pas d'installation globale ; npx récupère le serveur lors de la première utilisation.

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 prend en charge (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 inter-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-porteur 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 là-bas.

```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 comme 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_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 ID, 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 "démarrer 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: "" }

Quand c'est 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 n'existe que 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 dit 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 ou CIDR) ajoute des destinations autorisées ; deny_out (CIDR uniquement) 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). 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 comme env_vars en texte brut. Au lieu de cela :

Créez le secret une fois avec le SDK TypeScript (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 intentionnellement pas un outil MCP.
Découvrez les secrets liables avec secret_list (métadonnées uniquement — les valeurs ne quittent jamais la plateforme).
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 sa forme vCPU/mémoire/disque de son modèle et ne peut pas la remplacer au moment de sandbox_create. Pour obtenir une forme spécifique (disons, 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 la valeur par 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 retourner soit une URL publique propre, soit une URL privée signée à expiration. Les liens privés sont par défaut d'une heure ; définissez expires_in_seconds à une valeur de 1 à 604800 secondes. Voir URLs d'aperçu.

Pas encore dans la surface MCP

Le serveur MCP couvre la boucle d'agent courante ; le tableau ci-dessus est l'ensemble complet des outils v1. Quelques 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 streaming et interactives — streaming run() callbacks 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 lecture de 1 Mio / écriture en ligne de 8 Mio), 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.

Ceux-ci sont suivis comme sujets à venir.

Comment cela fonctionne

Le serveur encapsule le SDK TypeScript et ne détient jamais que votre SUPERSERVE_API_KEY du plan de contrôle. Chaque appel d'outil se connecte au sandbox cible par 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 de l'outil. Les outils sont sans état — il n'y a pas de « sandbox courant » caché — ce qui maintient un comportement prévisible lors d'appels multi-tours et parallèles.

Dépannage

Les outils n'apparaissent pas, ou le serveur ne démarre pas. La clé API 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 ultérieurs sont rapides.
Nécessite Node 18+. Le serveur local fonctionne sur Node via npx. (Le point de terminaison hébergé n'a aucune exigence d'exécution locale.)
401 Unauthorized depuis le 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 sandbox. Exécution, streaming, cwd, env et délais d'attente. Gérer les clés de fournisseurs sans les exposer au sandbox. La bibliothèque que le serveur MCP encapsule.