Superserve Sandbox

@superserve/mcp

Servidor de Model Context Protocol para sandboxes de Superserve. Crea, ejecuta comandos y gestiona microVMs Firecracker aisladas desde cualquier cliente MCP: Claude, Cursor, VS Code, Windsurf, Codex.

Se ejecuta localmente sobre stdio mediante npx. Se autentica con tu clave de API de Superserve. Apunta a un sandbox por llamada mediante su id.

Instalación

Añádelo a tu cliente MCP y establece SUPERSERVE_API_KEY en su env (los clientes no lo heredan de tu shell). Crea una clave en console.superserve.ai.

Claude Code:

claude mcp add superserve \
  --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \
  -- npx -y @superserve/mcp

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, .cursor/mcp.json, mcp_config.json):

{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

VS Code (.vscode/mcp.json, solicita la clave):

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

Codex (~/.codex/config.toml) — env_vars reenvía la clave desde tu entorno en lugar de almacenarla en el archivo:

[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]

Alojado (remoto)

Una instancia alojada se ejecuta en https://mcp.superserve.ai (Streamable HTTP): no requiere instalación local. Envía tu clave de API de Superserve como token bearer; el servidor es sin estado y está limitado a tu cuenta (la clave ya se asigna a tu equipo).

La autenticación Bearer funciona en 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 esperan OAuth (sin campo de bearer estático), que el endpoint alojado aún no admite.

Claude Code:

claude mcp add --transport http superserve https://mcp.superserve.ai \
  --header "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx"

Cursor / VS Code (.cursor/mcp.json, .vscode/mcp.json):

{
  "servers": {
    "superserve": {
      "type": "http",
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

Ejecutar el servidor alojado

El mismo paquete incluye el servidor alojado. Ejecútalo de forma independiente (autoalojado / staging):

PORT=8080 SUPERSERVE_BASE_URL=https://api.superserve.ai \
  npx -y -p @superserve/mcp superserve-mcp-http

O monta el manejador estándar Web en cualquier runtime fetch (p. ej., un manejador de ruta de Next.js):

import { handleMcpRequest } from "@superserve/mcp/http"

export const POST = (req: Request) => handleMcpRequest(req)

Sirve el endpoint MCP en / (POST) y una sonda de actividad GET /health. Configuración: PORT (por defecto 8080), SUPERSERVE_BASE_URL (opcional). La clave de API se lee en cada solicitud desde el encabezado bearer y nunca se registra.

Herramientas

Herramienta	Descripción
sandbox_create	Crea un sandbox; devuelve su id. Acepta enlaces 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 su creación.
sandbox_list	Lista 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.
sandbox_exec	Ejecuta un comando de shell; devuelve stdout, stderr y el código de salida. Reanuda automáticamente un sandbox en pausa.
sandbox_files_read	Lee un archivo (texto UTF-8 o base64). Rechaza archivos de más de 1 MiB.
sandbox_files_write	Crea o sobrescribe un archivo (contenido en línea limitado a 8 MiB).
sandbox_files_list	Lista un directorio.
sandbox_files_download_dir	Descarga un directorio como ZIP en base64 (se omiten los enlaces simbólicos). Limitado a 10 MiB.
sandbox_pause	Pausa un sandbox (se conserva el estado).
sandbox_resume	Reanuda un sandbox en pausa (normalmente innecesario: exec lo reanuda automáticamente).
sandbox_kill	Elimina un sandbox.
sandbox_preview_url	Publica un puerto y devuelve una URL de vista previa firmada pública o privada.
sandbox_network_log	Audita las conexiones salientes de un sandbox.
sandbox_template_list	Lista las plantillas (imágenes base preconstruidas) a partir de las cuales tu equipo puede crear sandboxes.
sandbox_template_create	Construye una plantilla personalizada (forma de vCPU/memoria/disco, software preinstalado). Asíncrono.
secret_list	Lista los secretos de equipo vinculables (solo metadatos, nunca valores).
sandbox_attach_secret	Vincula un secreto almacenado a un sandbox bajo una variable de entorno.
sandbox_detach_secret	Elimina un enlace de secreto de un sandbox.

Todas las herramientas requieren un sandbox_id excepto sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create y secret_list. La creación de secretos no se expone intencionalmente (el valor bruto pertenece al SDK/consola, no a una transcripción de agente); el servidor solo vincula secretos existentes.

Configuración

Variable	Requerida	Predeterminado
SUPERSERVE_API_KEY	Sí	—
SUPERSERVE_BASE_URL	No	https://api.superserve.ai

Desarrollo

bun install
bunx turbo run build     --filter=@superserve/mcp
bunx turbo run typecheck --filter=@superserve/mcp
bunx turbo run test      --filter=@superserve/mcp        # unit + in-memory integration (no credentials)
SUPERSERVE_API_KEY=ss_live_... bunx turbo run e2e --filter=@superserve/mcp   # live round-trip

El servidor es un adaptador ligero sobre @superserve/sdk; el token de acceso al plano de datos por sandbox lo gestiona el SDK y nunca se expone al modelo.

Licencia

Apache-2.0