Superserve Sandbox MCP

officiel

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

Voir sur superserve.ai

Que pouvez-vous faire avec Superserve Sandbox MCP ?

Créer un bac à sable isolé — demander à l’assistant de lancer une microVM Firecracker avec sandbox_create, en attachant éventuellement des secrets et des règles de trafic sortant.
Exécuter des commandes shell dans un bac à sable — exécuter des commandes via sandbox_exec et récupérer stdout, stderr et le code de sortie (reprend automatiquement les bacs à sable en pause).
Lire et écrire des fichiers dans le bac à sable — utiliser sandbox_files_read et sandbox_files_write pour inspecter ou placer des fichiers, avec création automatique des répertoires parents.
Exposer un point d’accès public depuis un bac à sable — démarrer un processus serveur et appeler sandbox_preview_url pour obtenir une URL accessible publiquement pour un port d’écoute.
Auditer le trafic réseau sortant — vérifier quels hôtes un bac à sable a contactés et s’ils ont été autorisés ou refusés avec sandbox_network_log.
Créer et gérer des modèles personnalisés — créer un modèle avec des vCPU/mémoire/disque spécifiques ou des logiciels préinstallés en utilisant sandbox_template_create, puis lancer des bacs à sable à partir de celui-ci.

Documentation

Serveur MCP

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

Le serveur MCP Superserve (@superserve/mcp) expose les primitives de bac à sable en tant qu'outils Model Context Protocol, afin que tout client compatible MCP — Claude, Cursor, VS Code, Windsurf, Codex — puisse créer des bacs à sable, exécuter des commandes, lire et écrire des fichiers, construire des modèles, gérer les 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 en utilisant le point de terminaison hébergé à https://mcp.superserve.ai sans installation locale. Les deux s'authentifient avec votre SUPERSERVE_API_KEY et ciblent un bac à sable par appel via son ID. C'est une fine couche au-dessus du SDK TypeScript, donc le jeton du plan de données par bac à sable n'atteint jamais le modèle.

Démarrage rapide

Ajoutez le serveur à votre client (voir Installation), puis demandez à l'agent de "créer un bac à sable et d'y exécuter python --version." L'agent appelle sandbox_create, puis sandbox_exec, et rapporte le résultat — sans 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

Définissez `SUPERSERVE_API_KEY` dans le `env` du serveur — les clients MCP n'en héritent pas depuis votre shell. Préférez 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` demande 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 utilise Streamable HTTP — pas de npx, pas de Node. Envoyez votre clé API Superserve en tant que jeton porteur. Le point de terminaison est sans état et limité au compte (votre clé correspond déjà à votre équipe), et le jeton du plan de données par bac à sable ne quitte jamais le serveur.

L'authentification par jeton porteur fonctionne dans tout client qui vous 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 utilisateur du connecteur personnalisé de Claude Desktop et le mode développeur ChatGPT n'offrent pas de champ pour 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](#install) 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` demande 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 en tant que 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 en tant qu'en-tête porteur au lieu d'une variable env.

Outils

Outil	Ce qu'il fait
`sandbox_create`	Crée un nouveau bac à sable ; retourne son `id`. Actif et prêt immédiatement. Accepte `secrets` et les règles de sortie.
`sandbox_update`	Modifie les métadonnées ou les règles de sortie (`allow_out`/`deny_out`) d'un bac à sable après sa création.
`sandbox_list`	Liste vos bacs à sable (actifs 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'un bac à sable. Lecture seule.
`sandbox_exec`	Exécute une commande shell ; retourne stdout, stderr, le code de sortie. Reprend automatiquement un bac à sable 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, date de modification).
`sandbox_files_download_dir`	Télécharge un répertoire sous forme de ZIP en base64 (liens symboliques ignorés). Limité à 10 Mio ; au-delà → SDK/CLI.
`sandbox_pause`	Met en pause un bac à sable ; l'état est préservé.
`sandbox_resume`	Reprend un bac à sable en pause (généralement inutile — l'exécution reprend automatiquement).
`sandbox_kill`	Supprime définitivement un bac à sable.
`sandbox_preview_url`	Construit l'URL publique pour un port d'écoute (non authentifié — tout ce qui est sur ce port est exposé à Internet).
`sandbox_network_log`	Audite les connexions sortantes d'un bac à sable (hôte, verdict, octets). Reprend automatiquement un bac à sable en pause.
`sandbox_template_list`	Liste les modèles (images de base) à partir desquels votre équipe peut lancer des instances.
`sandbox_template_create`	Construit un modèle personnalisé avec une forme spécifique de vCPU/mémoire/disque ou des logiciels préinstallés (asynchrone — interrogez pour l'état prêt).
`secret_list`	Liste les secrets d'équipe pouvant être liés (métadonnées uniquement — jamais les valeurs).
`sandbox_attach_secret`	Lie un secret stocké à un bac à sable en cours d'exécution sous une variable d'environnement.
`sandbox_detach_secret`	Supprime une liaison de secret d'un bac à sable.

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 utilisez-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_preview_url, sandbox_template_list, secret_list) sont annotés pour que les clients puissent ignorer les invites de confirmation ; sandbox_kill est annoté comme destructeur.

Exemple

Un flux d'agent typique pour "lancer un bac à sable, é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	Requis	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 fichier reprennent de manière transparente un bac à sable en pause, de sorte que les agents n'ont jamais besoin d'appeler sandbox_resume en premier. sandbox_resume existe uniquement pour réchauffer explicitement un bac à sable.
La sortie est limité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 retourne pas de contenu partiel) ; l'erreur vous indique de lire une tranche avec sandbox_exec (par exemple head -c) ou de télécharger le fichier entier avec le SDK/CLI. Le contenu en ligne de sandbox_files_write est limité à 8 Mio.
Le délai d'expiration par défaut des commandes est de 60 s, avec un maximum de 10 minutes. Remplacez-le par appel avec timeout_ms.
La sortie est contrôlable. allow_out (modèles de domaine ou CIDR) ajoute des destinations autorisées ; deny_out (CIDR uniquement) les bloque. allow_out seul ne verrouille pas un bac à sable — pour une liste d'autorisation stricte, combinez-le avec deny_out: ["0.0.0.0/0"] (refuser tout, puis autoriser les destinations listées). Définissez-les sur sandbox_create ou sandbox_update, et auditez ce qu'un bac à sable a réellement atteint avec sandbox_network_log.
Les erreurs sont exploitables. Un appel d'outil échoué retourne un message court indiquant à l'agent quoi faire ensuite — par exemple "Quota de bac à sable atteint. Mettez en pause ou supprimez un bac à sable, 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 tant que env_vars en texte brut. À la place :

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 pouvant être liés 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.

Le bac à sable 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. Un bac à sable hérite de ses 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 exemple, un bac à sable à 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 en tant que from_template.

Ports. Démarrez un serveur dans le bac à sable (sandbox_exec, par exemple python3 -m http.server 8000), puis appelez sandbox_preview_url pour obtenir son URL publique. Tout processus lié à un port est accessible à https://{port}-{id}.sandbox.superserve.ai avec aucune authentification — n'exposez que les ports que vous souhaitez rendre publics.

Pas encore dans la surface MCP

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

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

Ceux-ci sont suivis en tant que développements futurs.

Comment ça fonctionne

Le serveur encapsule le SDK TypeScript et ne conserve que votre SUPERSERVE_API_KEY de 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 renouvelle 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 garantit un comportement prévisible lors d'appels d'outils 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 en 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 pas de prérequis d'exécution local.)
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 en tant que Authorization: Bearer ss_live_… (voir Hébergé).

Voir aussi

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