Superserve Sandbox

@superserve/mcp

Servidor Model Context Protocol para sandboxes do Superserve. Crie, execute comandos e gerencie microVMs Firecracker isoladas a partir de qualquer cliente MCP — Claude, Cursor, VS Code, Windsurf, Codex.

Executa localmente via stdio através de npx. Autentica com sua chave de API do Superserve. Direciona um sandbox por chamada pelo id.

Instalação

Adicione ao seu cliente MCP e defina SUPERSERVE_API_KEY no seu env (os clientes não herdam isso do seu shell). Crie uma chave em 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 a chave):

{
  "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 encaminha a chave do seu ambiente em vez de armazená-la no arquivo:

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

Hospedado (remoto)

Uma instância hospedada roda em https://mcp.superserve.ai (Streamable HTTP) — sem instalação local. Envie sua chave de API do Superserve como bearer token; o servidor é stateless e limitado à conta (a chave já mapeia para o seu time).

A autenticação Bearer funciona no Claude Code, Cursor, VS Code e no conector da Anthropic Messages API. Claude.ai, a interface de Custom Connector do Claude Desktop e o modo de desenvolvimento do ChatGPT esperam OAuth (sem campo de bearer estático), que o endpoint hospedado ainda não suporta.

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

Executando o servidor hospedado

O mesmo pacote inclui o servidor hospedado. Execute-o standalone (self-host / staging):

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

Ou monte o handler padrão Web em qualquer runtime fetch (ex.: um route handler do Next.js):

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

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

Ele serve o endpoint MCP em / (POST) e um probe de liveness GET /health. Config: PORT (padrão 8080), SUPERSERVE_BASE_URL (opcional). A chave de API é lida por requisição do cabeçalho bearer e nunca é registrada em logs.

Ferramentas

Tool	Descrição
sandbox_create	Cria um sandbox; retorna seu id. Aceita bindings secrets e regras de egress.
sandbox_update	Altera os metadados de um sandbox ou as regras de egress (allow_out/deny_out) após a criação.
sandbox_list	Lista sandboxes (ativos e pausados), com filtro por metadados.
sandbox_info	Obtém o status, os recursos, os metadados, as regras de rede e os bindings de segredos de um sandbox.
sandbox_exec	Executa um comando de shell; retorna stdout, stderr e código de saída. Retoma automaticamente um sandbox pausado.
sandbox_files_read	Lê um arquivo (texto UTF-8 ou base64). Rejeita arquivos acima de 1 MiB.
sandbox_files_write	Cria ou sobrescreve um arquivo (conteúdo inline limitado a 8 MiB).
sandbox_files_list	Lista um diretório.
sandbox_files_download_dir	Baixa um diretório como ZIP em base64 (symlinks ignorados). Limitado a 10 MiB.
sandbox_pause	Pausa um sandbox (estado preservado).
sandbox_resume	Retoma um sandbox pausado (geralmente desnecessário — exec retoma automaticamente).
sandbox_kill	Exclui um sandbox.
sandbox_preview_url	Publica uma porta e retorna uma URL de preview assinada, pública ou privada.
sandbox_network_log	Audita as conexões de saída de um sandbox.
sandbox_template_list	Lista os templates (imagens base pré-construídas) que seu time pode usar para criar sandboxes.
sandbox_template_create	Constrói um template personalizado (formato vCPU/memória/disco, software pré-instalado). Assíncrono.
secret_list	Lista segredos do time que podem ser vinculados (apenas metadados — nunca valores).
sandbox_attach_secret	Vincula um segredo armazenado a um sandbox sob uma variável de ambiente.
sandbox_detach_secret	Remove um vínculo de segredo de um sandbox.

Todas as ferramentas aceitam um sandbox_id, exceto sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create e secret_list. A criação de segredos é intencionalmente não exposta (o valor bruto pertence ao SDK/console, não a um transcript do agente); o servidor apenas vincula segredos existentes.

Configuração

Variável	Obrigatória	Padrão
SUPERSERVE_API_KEY	Sim	—
SUPERSERVE_BASE_URL	Não	https://api.superserve.ai

Desenvolvimento

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

O servidor é um adaptador leve sobre @superserve/sdk; o token de acesso do plano de dados por sandbox é gerenciado pelo SDK e nunca é exposto ao modelo.

Licença

Apache-2.0