Superserve Sandbox MCP

Servidor MCP

Crea, ejecuta y gestiona sandboxes de Superserve desde cualquier cliente MCP.

¿Buscas que un agente pueda crear sandboxes por sí mismo? Este servidor MCP lo hace.

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

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

Inicio rápido

Añade el servidor a tu cliente (consulta Instalación) y luego pide 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 código por tu parte.

Necesitas una clave de API de Superserve: créala en la página de clave de API. No hay instalación global; npx descarga el servidor en el primer uso.

Instalación

Nota

Establece SUPERSERVE_API_KEY en el env del servidor — los clientes MCP no lo heredan de tu shell. Prefiere un prompt de entrada secreta en lugar de pegar la clave en texto plano donde tu cliente lo admita (consulta VS Code a continuación).

```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ñádelo 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ñádelo 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ñádelo 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ñádelo 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ñádelo a `~/.codex/config.toml`. `env_vars` reenvía `SUPERSERVE_API_KEY` desde tu entorno, por lo que la clave en texto plano no se almacena en el archivo de configuración (expórtala en tu shell primero). 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), usa `url = "https://mcp.superserve.ai"` con `bearer_token_env_var = "SUPERSERVE_API_KEY"`.

Alojado (remoto)

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

Nota

La autenticación de portador funciona en cualquier cliente que te permita establecer un encabezado de solicitud — Claude Code, Cursor, VS Code y el conector de la API de Mensajes de Anthropic. Claude.ai, la interfaz 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 — usa la instalación local 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ñádelo 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ñádelo 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ásalo como conector en una solicitud de [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 encabezado de portador en lugar de una variable env.

Herramientas

Herramienta	Qué hace
sandbox_create	Crea un nuevo sandbox; devuelve su id. Acepta secrets, reglas de salida y preview_access.
sandbox_update	Cambia metadatos, reglas de salida, ventanas de ciclo de vida o preview_access.
sandbox_list	Lista tus sandboxes (activos y en pausa), filtrables por metadatos.
sandbox_info	Obtiene el estado, los recursos, los metadatos, las reglas de red y los enlaces de secretos de un sandbox. Solo lectura.
sandbox_exec	Ejecuta un comando de shell; devuelve stdout, stderr y código de salida. Reanuda automáticamente un sandbox en pausa.
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 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 en pausa (generalmente innecesario — exec reanuda automáticamente).
sandbox_kill	Elimina permanentemente un sandbox.
sandbox_preview_url	Publica un puerto y devuelve una URL pública limpia o una URL privada firmada con caducidad.
sandbox_network_log	Audita las conexiones salientes de un sandbox (host, veredicto, bytes) sin reanudarlo.
sandbox_computer	Controla un sandbox de escritorio GUI: captura de pantalla, ratón, teclado, desplazamiento, redimensionamiento, URL de visor. Una acción por llamada.
sandbox_template_list	Lista las plantillas (imágenes base) desde las que tu equipo puede lanzar.
sandbox_template_create	Construye una plantilla personalizada con una forma específica de vCPU/memoria/disco o software preinstalado (asíncrono — consulta 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 un enlace 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. Comienza con una de esas para obtener un ID y luego pásalo a llamadas posteriores. Las herramientas de solo lectura (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_network_log, sandbox_template_list, secret_list) están anotadas para que los clientes omitan los prompts de confirmación; sandbox_preview_url es una escritura idempotente porque publica el puerto solicitado, y sandbox_kill está anotada como destructiva.

Ejemplo

Un flujo típico de agente para "levanta un sandbox, escribe un script de Python que imprima los primeros primos y ejecútalo":

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 conservado, más barato de mantener) o sandbox_kill (permanente).

Configuración

Variable	Requerida	Descripción
SUPERSERVE_API_KEY	Sí	Tu clave de API de Superserve (comienza con ss_live_).
SUPERSERVE_BASE_URL	No	Sobrescribe 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 archivos reanudan de forma transparente un sandbox en pausa, por lo que los agentes nunca necesitan llamar a sandbox_resume primero. 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 mayores de 1 MiB (no devuelve contenido parcial); el error te dice que leas un fragmento con sandbox_exec (por ejemplo, head -c) o que descargues 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. Sobrescríbelo por llamada con timeout_ms.
• La salida es controlable. allow_out (patrones de dominio, IPs o CIDRs) añade destinos permitidos; deny_out (IPs o CIDRs, sin dominios) los bloquea. allow_out por sí solo no bloquea un sandbox — para una lista de permitidos estricta, combínalo con deny_out: ["0.0.0.0/0"] (denegar todo, luego permitir los destinos listados). Si la lista de permitidos tiene reglas de dominio o la carga de trabajo resuelve nombres de host, también permite los resolutores DNS del sandbox, 1.1.1.1/32 y 8.8.8.8/32, ya que denegar todo también bloquea DNS; déjalos fuera de una lista de permitidos solo de IPs, donde un resolutor permitido es solo un canal de salida adicional. Establece estos en sandbox_create o sandbox_update, y audita lo que un sandbox realmente alcanzó con sandbox_network_log.
• Los errores son accionables. Una llamada de herramienta fallida devuelve un mensaje corto que le dice al agente qué hacer a continuación — por ejemplo, "Cuota de sandbox alcanzada. Pausa o elimina un sandbox, o reintenta más tarde." — en lugar de un traceback crudo, para que el agente pueda autocorregirse.

Secretos, plantillas y puertos

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

1. Crea el secreto una vez con el SDK de TypeScript (Secret.create()) o la consola — el valor en texto plano nunca viaja a través del agente ni del servidor MCP, por lo que la creación de secretos intencionalmente no es una herramienta MCP.
2. Descubre secretos vinculables con secret_list (solo metadatos — los valores nunca salen de la plataforma).
3. Vincula 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 sobrescribirlos en el momento de sandbox_create. Para obtener una forma específica (por ejemplo, un sandbox de 4 vCPU) o software preinstalado, construye una plantilla con sandbox_template_create, luego consulta sandbox_template_list hasta que su status sea ready antes de pasarla como from_template.

Puertos. Los nuevos sandboxes MCP usan public como acceso predeterminado para puertos recién publicados; solo los puertos publicados explícitamente son alcanzables. Pasa preview_access: "private" a sandbox_create (o sandbox_update) para cambiar el predeterminado para puertos futuros. Los puertos existentes conservan su propio modo. Inicia el servidor con sandbox_exec, luego llama a sandbox_preview_url; la herramienta publica idempotentemente ese único puerto y usa el modo de puerto devuelto para devolver una URL pública limpia o una URL privada firmada con caducidad. Los enlaces privados predeterminan a una hora; establece expires_in_seconds a un valor de 1 a 604800 segundos. Consulta URLs de vista previa.

Uso de computadora

sandbox_computer controla un escritorio GUI en un sandbox creado desde una plantilla de escritorio como superserve/desktop. Toma una action por llamada en el vocabulario que emiten los modelos de uso de computadora: 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 y stream_url. Las acciones de puntero toman coordinate: [x, y] en píxeles de pantalla (origen arriba a la izquierda); key y type toman text; scroll toma scroll_direction y un scroll_amount opcional.

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

Las acciones de entrada devuelven una captura de pantalla fresca del resultado, por lo que el turno de actuar-luego-mirar del modelo es una sola llamada de herramienta; pasa screenshot_after: false cuando envíes varias acciones seguidas. wait pausa durante duration_ms (máximo 10 segundos) sin una solicitud al sandbox. stream_url devuelve un visor de navegador en vivo para el escritorio bajo la política de vista previa del sandbox.

Si una acción de entrada falla, la entrada puede ya haberse entregado. La herramienta lo dice y pide al agente tomar una captura de pantalla antes de repetirla. Consulta la Guía de escritorio para la superficie del SDK subyacente.

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 al SDK de TypeScript directamente para:

• Creación de secretos — Secret.create() (el servidor MCP solo vincula secretos existentes).
• Comandos interactivos y de streaming — callbacks de streaming run() y commands.spawn (stdin, señales, procesos de larga duración).
• Transferencias grandes o de streaming — la descarga de directorios es compatible hasta 10 MiB mediante sandbox_files_download_dir; más allá de eso (y para cargas de archivos/streaming 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 streaming).
• Facturación y descubrimiento de proveedores — datos de uso y Provider.list() para la configuración del proveedor de secretos.

Estos se registran como seguimientos.

Cómo funciona

El servidor envuelve el SDK de TypeScript y solo conserva su SUPERSERVE_API_KEY del plano de control. Cada llamada de herramienta se conecta al sandbox de destino por ID; el SDK gestiona internamente el token de acceso del plano de datos por sandbox 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 un comportamiento predecible en llamadas de herramientas multiturno y paralelas.

Solución de problemas

• Las herramientas no aparecen, o el servidor no se inicia. La clave de API es casi siempre la causa — los clientes MCP no heredan variables de entorno de su shell. Establezca SUPERSERVE_API_KEY en el bloque env del servidor (consulte Instalación), 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 de 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 mediante npx. (El endpoint alojado no tiene requisito de runtime 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. Intermediar claves de proveedor sin exponerlas al sandbox. La biblioteca que envuelve el servidor MCP.

Esta documentación está construida y alojada en Mintlify, una plataforma de documentación para desarrolladores.