Superserve Sandbox MCP

oficial

Máquinas virtuales seguras para agentes alojados por Superserve

Ver en superserve.ai

¿Qué puedes hacer con Superserve Sandbox MCP?

Crear un sandbox aislado — solicita al asistente que inicie una microVM Firecracker con sandbox_create, adjuntando opcionalmente secretos y reglas de salida.
Ejecutar comandos de shell dentro de un sandbox — ejecuta comandos mediante sandbox_exec y obtén stdout, stderr y el código de salida (reanuda automáticamente los sandboxes en pausa).
Leer y escribir archivos en el sandbox — usa sandbox_files_read y sandbox_files_write para inspeccionar o colocar archivos, con creación automática de directorios padre.
Exponer un endpoint público desde un sandbox — inicia un proceso de servidor y llama a sandbox_preview_url para obtener una URL accesible públicamente para un puerto en escucha.
Auditar el tráfico de red saliente — verifica qué hosts contactó un sandbox y si fueron permitidos o denegados con sandbox_network_log.
Crear y gestionar plantillas personalizadas — crea una plantilla con vCPU/memoria/disco específicos o software preinstalado usando sandbox_template_create, y luego lanza sandboxes a partir de ella.

Documentación

Servidor MCP

Cree, ejecute y administre sandboxes de Superserve desde cualquier cliente MCP.

El servidor MCP de Superserve (@superserve/mcp) expone las primitivas de sandbox como herramientas del Protocolo de Contexto de Modelo, para que cualquier cliente compatible con MCP — Claude, Cursor, VS Code, Windsurf, Codex — pueda crear sandboxes, ejecutar comandos, leer y escribir archivos, construir plantillas, intermediar secretos y controlar el acceso a la red en una microVM aislada de Firecracker.

Ejecútelo de dos maneras: localmente a través de stdio mediante npx, o contra el endpoint alojado en https://mcp.superserve.ai sin instalación local. Ambos se autentican con su SUPERSERVE_API_KEY y apuntan a un sandbox por llamada mediante ID. Es un envoltorio ligero sobre el SDK de TypeScript, por lo que el token del plano de datos por sandbox nunca llega al modelo.

Inicio rápido

Añada el servidor a su cliente (consulte Instalar), luego pida al agente que "cree un sandbox y ejecute python --version en él." El agente llama a sandbox_create, luego a sandbox_exec, e informa del resultado — sin necesidad de código por su parte.

Necesita una clave API de Superserve — cree una en la página de clave API. No hay instalación global; npx obtiene el servidor en el primer uso.

Instalar

Establezca `SUPERSERVE_API_KEY` en el `env` del servidor — los clientes MCP no lo heredan de su shell. Prefiera una solicitud de entrada secreta en lugar de pegar la clave sin procesar donde su cliente lo admita (consulte VS Code más abajo). ```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` Añadir a `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" }
    }
  }
}
```

Añadir a `.cursor/mcp.json` (proyecto) o `~/.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" }
    }
  }
}
```

Añadir a `.vscode/mcp.json`. El bloque `inputs` solicita la clave en lugar de almacenarla en texto plano:

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

Añadir a `~/.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" }
    }
  }
}
```

Añadir a `~/.codex/config.toml`. `env_vars` reenvía `SUPERSERVE_API_KEY` desde su entorno, por lo que la clave sin procesar no se almacena en el archivo de configuración (expórtela primero en su shell). Codex también lee el `instructions` del servidor para obtener orientación sobre el flujo de trabajo entre herramientas.

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

Para el endpoint [alojado](#hosted-remote), use `url = "https://mcp.superserve.ai"` con `bearer_token_env_var = "SUPERSERVE_API_KEY"`.

Alojado (remoto)

¿No quiere ejecutar nada localmente? El endpoint alojado en https://mcp.superserve.ai habla HTTP Transmisible — sin npx, sin Node. Envíe su clave API de Superserve como un token de portador. El endpoint no tiene estado y está limitado a la cuenta (su clave ya se asigna a su equipo), y el token del plano de datos por sandbox nunca sale del servidor.

La autenticación de portador funciona en cualquier cliente que le permita establecer un encabezado de solicitud — Claude Code, Cursor, VS Code y el conector de la API de Mensajes de Anthropic. Claude.ai, la IU de Conector Personalizado de Claude Desktop y el modo desarrollador de ChatGPT no ofrecen un campo de portador estático / encabezado personalizado (esperan OAuth), que el endpoint alojado aún no admite — use la instalación [local](#install) allí. ```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" ``` Añadir a `.cursor/mcp.json` (proyecto) o `~/.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" }
    }
  }
}
```

Añadir a `.vscode/mcp.json`. El bloque `inputs` solicita la clave en lugar de almacenarla en texto plano:

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

Páselo como conector en una solicitud de la [API de Mensajes de Anthropic](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"
    }
  ]
}
```

Mismas herramientas y comportamiento que el servidor local — la única diferencia es el transporte y que la clave viaja como un encabezado de portador en lugar de una variable env.

Herramientas

Herramienta	Qué hace
`sandbox_create`	Crea un nuevo sandbox; devuelve su `id`. Activo y listo de inmediato. Acepta `secrets` y reglas de salida.
`sandbox_update`	Cambia los metadatos o las reglas de salida (`allow_out`/`deny_out`) de un sandbox después de la creación.
`sandbox_list`	Lista sus sandboxes (activos y pausados), filtrables por metadatos.
`sandbox_info`	Obtiene el estado, recursos, metadatos, reglas de red y vinculaciones de secretos de un sandbox. Solo lectura.
`sandbox_exec`	Ejecuta un comando de shell; devuelve stdout, stderr, código de salida. Reanuda automáticamente un sandbox pausado.
`sandbox_files_read`	Lee un archivo (texto UTF-8, o base64 para binarios).
`sandbox_files_write`	Crea o sobrescribe un archivo. Los directorios padre se crean automáticamente.
`sandbox_files_list`	Lista las entradas de un directorio (nombre, tipo, tamaño, hora de modificación).
`sandbox_files_download_dir`	Descarga un directorio como un ZIP en base64 (se omiten los enlaces simbólicos). Limitado a 10 MiB; más grande → SDK/CLI.
`sandbox_pause`	Pausa un sandbox; el estado se conserva.
`sandbox_resume`	Reanuda un sandbox pausado (generalmente innecesario — exec reanuda automáticamente).
`sandbox_kill`	Elimina permanentemente un sandbox.
`sandbox_preview_url`	Construye la URL pública para un puerto de escucha (sin autenticación — cualquier cosa en ese puerto está expuesta a internet).
`sandbox_network_log`	Audita las conexiones salientes de un sandbox (host, veredicto, bytes). Reanuda automáticamente un sandbox pausado.
`sandbox_template_list`	Lista las plantillas (imágenes base) desde las que su equipo puede lanzar.
`sandbox_template_create`	Construye una plantilla personalizada con una forma específica de vCPU/memoria/disco o software preinstalado (asíncrono — sondeo hasta que esté lista).
`secret_list`	Lista los secretos de equipo vinculables (solo metadatos — nunca valores).
`sandbox_attach_secret`	Vincula un secreto almacenado a un sandbox en ejecución bajo una variable de entorno.
`sandbox_detach_secret`	Elimina una vinculación de secreto de un sandbox.

La mayoría de las herramientas toman un sandbox_id; las excepciones son sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create y secret_list. Comience con una de ellas para obtener un ID, luego páselo a llamadas posteriores. Las herramientas de solo lectura (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_preview_url, sandbox_template_list, secret_list) están anotadas para que los clientes puedan omitir las solicitudes de confirmación; sandbox_kill está anotada como destructiva.

Ejemplo

Un flujo de agente típico para "iniciar un sandbox, escribir un script de Python que imprima los primeros números primos y ejecutarlo":

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

Cuando termine, el agente puede sandbox_pause (estado preservado, más barato de mantener) o sandbox_kill (permanente).

Configuración

Variable	Requerido	Descripción
`SUPERSERVE_API_KEY`	Sí	Su clave API de Superserve (comienza con `ss_live_`).
`SUPERSERVE_BASE_URL`	No	Anula la URL del plano de control (por defecto `https://api.superserve.ai`).

Comportamiento y límites

Reanudación automática. sandbox_exec y las herramientas de archivo reanudan de forma transparente un sandbox pausado, por lo que los agentes nunca necesitan llamar primero a sandbox_resume. sandbox_resume existe solo para calentar un sandbox explícitamente.
La salida está limitada para el contexto. sandbox_exec trunca stdout y stderr a 32 KiB cada uno — un resultado truncado establece truncated: true e informa la longitud original en bytes. sandbox_files_read rechaza archivos de más de 1 MiB (no devuelve contenido parcial); el error le indica que lea un fragmento con sandbox_exec (ej. head -c) o descargue el archivo completo con el SDK/CLI. El contenido en línea de sandbox_files_write está limitado a 8 MiB.
El tiempo de espera predeterminado del comando es de 60 s, con un máximo de 10 minutos. Anúlelo por llamada con timeout_ms.
La salida es controlable. allow_out (patrones de dominio o CIDRs) añade destinos permitidos; deny_out (solo CIDRs) los bloquea. allow_out por sí solo no bloquea un sandbox — para una lista de permitidos estricta, combínelo con deny_out: ["0.0.0.0/0"] (denegar todo, luego permitir los destinos listados). Establezca estos en sandbox_create o sandbox_update, y audite lo que un sandbox realmente alcanzó con sandbox_network_log.
Los errores son procesables. Una llamada de herramienta fallida devuelve un mensaje corto que le dice al agente qué hacer a continuación — ej. "Cuota de sandbox alcanzada. Pause o elimine un sandbox, o reintente más tarde." — en lugar de un seguimiento de pila sin procesar, para que el agente pueda autocorregirse.

Secretos, plantillas y puertos

Secretos. No pase credenciales como env_vars en texto plano. En su lugar:

Cree el secreto una vez con el SDK de TypeScript (Secret.create()) o la consola — el valor sin procesar nunca viaja a través del agente o del servidor MCP, por lo que la creación de secretos no es intencionalmente una herramienta MCP.
Descubra secretos vinculables con secret_list (solo metadatos — los valores nunca salen de la plataforma).
Vincule en la creación — secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } en sandbox_create — o más tarde con sandbox_attach_secret / sandbox_detach_secret.

El sandbox ve un token proxy; la plataforma intercambia la credencial real solo para solicitudes salientes a los hosts permitidos del secreto.

Plantillas. Un sandbox hereda su vCPU/memoria/disco de su plantilla y no puede anularlos en el momento de sandbox_create. Para obtener una forma específica (por ejemplo, un sandbox de 4 vCPU) o software preinstalado, construya una plantilla con sandbox_template_create, luego sondee sandbox_template_list hasta que su status sea ready antes de pasarlo como from_template.

Puertos. Inicie un servidor en el sandbox (sandbox_exec, ej. python3 -m http.server 8000), luego llame a sandbox_preview_url para obtener su URL pública. Cualquier proceso vinculado a un puerto es accesible en https://{port}-{id}.sandbox.superserve.ai sin autenticación — solo exponga los puertos que pretenda que sean públicos.

Aún no en la superficie MCP

El servidor MCP cubre el bucle de agente común; la tabla anterior es el conjunto completo de herramientas v1. Algunas capacidades del SDK aún no están expuestas — recurra directamente al SDK de TypeScript para:

Creación de secretos — Secret.create() (el servidor MCP solo vincula secretos existentes).
Comandos de transmisión e interactivos — devoluciones de llamada de transmisión run() y commands.spawn (stdin, señales, procesos de larga duración).
Transferencias grandes o de transmisión — la descarga de directorios se admite hasta 10 MiB a través de sandbox_files_download_dir; más allá de eso (y para cargas de archivo/transmisión o archivos individuales que superen los límites de 1 MiB de lectura / 8 MiB de escritura en línea), use el SDK/CLI (files.downloadDir, carga de transmisión).
Facturación y descubrimiento de proveedores — datos de uso y Provider.list() para la configuración del proveedor de secretos.

Estos se rastrean como seguimientos.

Cómo funciona

El servidor envuelve el SDK de TypeScript y solo almacena su SUPERSERVE_API_KEY del plano de control. Cada llamada de herramienta se conecta al sandbox de destino por ID; el SDK gestiona el token de acceso del plano de datos por sandbox internamente y lo rota al reanudar, por lo que nunca se expone al modelo ni se devuelve en la salida de la herramienta. Las herramientas no tienen estado — no hay un "sandbox actual" oculto — lo que mantiene el comportamiento predecible en llamadas de herramientas de múltiples turnos y en paralelo.

Solución de problemas

Las herramientas no aparecen o el servidor no inicia. La clave API casi siempre es la causa — los clientes MCP no heredan las variables de entorno de su shell. Establezca SUPERSERVE_API_KEY en el bloque env del servidor (consulte Instalar), no solo en su terminal.
Authentication failed. La clave falta o no es válida. Las claves de producción comienzan con ss_live_; cree una en la página de clave API.
La primera llamada es lenta. npx descarga el paquete en el primer uso y lo almacena en caché; los inicios posteriores son rápidos.
Requiere Node 18+. El servidor local se ejecuta en Node a través de npx. (El endpoint alojado no tiene requisitos de tiempo de ejecución local.)
401 Unauthorized desde el endpoint alojado. El token de portador falta o no es una clave ss_live_ válida. Envíelo como Authorization: Bearer ss_live_… (consulte Alojado).

Relacionado

Pausar, reanudar y eliminar sandboxes. Exec, streaming, cwd, env y timeouts. Claves de proveedor intermediario sin exponerlas al sandbox. La biblioteca que envuelve el servidor MCP.