Superserve Sandbox MCP

Servidor MCP

Crie, execute e gerencie sandboxes Superserve a partir de qualquer cliente MCP.

Quer permitir que um agente crie sandboxes por conta própria? Este servidor MCP faz exatamente isso.

O servidor MCP do Superserve (@superserve/mcp) expõe primitivas de sandbox como ferramentas do Model Context Protocol, permitindo que qualquer cliente compatível com MCP — Claude, Cursor, VS Code, Windsurf, Codex — crie sandboxes, execute comandos, leia e escreva arquivos, construa templates, gerencie segredos e controle o acesso à rede em uma microVM Firecracker isolada.

Execute de duas formas: localmente via stdio usando npx, ou contra o endpoint hospedado em https://mcp.superserve.ai sem instalação local. Ambos autenticam com sua SUPERSERVE_API_KEY e direcionam um sandbox por chamada usando o ID. É um wrapper fino sobre o TypeScript SDK, então o token do plano de dados por sandbox nunca chega ao modelo.

Início rápido

Adicione o servidor ao seu cliente (veja Instalação) e peça ao agente para "criar um sandbox e executar python --version nele". O agente chama sandbox_create, depois sandbox_exec, e reporta o resultado — sem código da sua parte.

Você precisa de uma chave de API Superserve — crie uma na página de chave de API. Não há instalação global; npx busca o servidor no primeiro uso.

Instalação

Nota

Defina SUPERSERVE_API_KEY no env do servidor — clientes MCP não herdam isso do seu shell. Prefira um prompt de entrada secreta em vez de colar a chave bruta onde seu cliente suportar (veja VS Code abaixo).

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` Adicione ao `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" }
    }
  }
}
```

Adicione ao `.cursor/mcp.json` (projeto) 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" }
    }
  }
}
```

Adicione ao `.vscode/mcp.json`. O bloco `inputs` solicita a chave em vez de armazená-la em texto puro:

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

Adicione ao `~/.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" }
    }
  }
}
```

Adicione ao `~/.codex/config.toml`. O `env_vars` encaminha `SUPERSERVE_API_KEY` do seu ambiente, então a chave bruta não fica armazenada no arquivo de configuração (exporte-a no seu shell primeiro). O Codex também lê o `instructions` do servidor para orientação de fluxo de trabalho entre ferramentas.

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

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

Hospedado (remoto)

Não quer executar nada localmente? O endpoint hospedado em https://mcp.superserve.ai fala Streamable HTTP — sem npx, sem Node. Envie sua chave de API Superserve como um token bearer. O endpoint é stateless e limitado à conta (sua chave já mapeia para seu time), e o token do plano de dados por sandbox nunca sai do servidor.

Nota

Autenticação bearer funciona em qualquer cliente que permita definir um cabeçalho de requisição — Claude Code, Cursor, VS Code e o conector da Anthropic Messages API. Claude.ai, a interface de Custom Connector do Claude Desktop e o modo desenvolvedor do ChatGPT não oferecem campo de bearer estático / cabeçalho personalizado (eles esperam OAuth), que o endpoint hospedado ainda não suporta — use a instalação local nesses casos.

```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" ``` Adicione ao `.cursor/mcp.json` (projeto) 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" }
    }
  }
}
```

Adicione ao `.vscode/mcp.json`. O bloco `inputs` solicita a chave em vez de armazená-la em texto puro:

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

Passe como conector em uma requisição [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"
    }
  ]
}
```

Mesmas ferramentas e comportamento do servidor local — a única diferença é o transporte e o fato de a chave viajar como cabeçalho bearer em vez de uma variável env.

Ferramentas

Ferramenta	O que faz
sandbox_create	Cria um novo sandbox; retorna seu id. Aceita secrets, regras de egress e preview_access.
sandbox_update	Altera metadados, regras de egress, janelas de ciclo de vida ou preview_access.
sandbox_list	Lista seus sandboxes (ativos e pausados), filtráveis por metadados.
sandbox_info	Obtém o status, recursos, metadados, regras de rede e vínculos de segredos de um sandbox. Somente leitura.
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 para binários).
sandbox_files_write	Cria ou sobrescreve um arquivo. Diretórios pai são criados automaticamente.
sandbox_files_list	Lista as entradas de um diretório (nome, tipo, tamanho, hora de modificação).
sandbox_files_download_dir	Baixa um diretório como ZIP base64 (symlinks ignorados). Limitado a 10 MiB; maior → SDK/CLI.
sandbox_pause	Pausa um sandbox; o estado é preservado.
sandbox_resume	Retoma um sandbox pausado (geralmente desnecessário — exec retoma automaticamente).
sandbox_kill	Exclui permanentemente um sandbox.
sandbox_preview_url	Publica uma porta e retorna uma URL pública limpa ou uma URL privada assinada com expiração.
sandbox_network_log	Audita as conexões de saída de um sandbox (host, veredito, bytes) sem retomá-lo.
sandbox_template_list	Lista os templates (imagens base) que seu time pode usar para iniciar.
sandbox_template_create	Constrói um template personalizado com formato específico de vCPU/memória/disco ou software pré-instalado (assíncrono — consulte até ficar pronto).
secret_list	Lista segredos do time que podem ser vinculados (somente metadados — nunca valores).
sandbox_attach_secret	Vincula um segredo armazenado a um sandbox em execução sob uma variável de ambiente.
sandbox_detach_secret	Remove um vínculo de segredo de um sandbox.

A maioria das ferramentas recebe um sandbox_id; as exceções são sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create e secret_list. Comece com uma delas para obter um ID e depois passe-o nas chamadas seguintes. Ferramentas somente leitura (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_network_log, sandbox_template_list, secret_list) são anotadas para que clientes possam pular prompts de confirmação; sandbox_preview_url é uma escrita idempotente porque publica a porta solicitada, e sandbox_kill é anotada como destrutiva.

Exemplo

Um fluxo típico de agente para "subir um sandbox, escrever um script Python que imprime os primeiros primos e executá-lo":

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

Quando terminar, o agente pode sandbox_pause (estado preservado, mais barato de manter) ou sandbox_kill (permanente).

Configuração

Variável	Obrigatória	Descrição
SUPERSERVE_API_KEY	Sim	Sua chave de API Superserve (começa com ss_live_).
SUPERSERVE_BASE_URL	Não	Substitui a URL do plano de controle (padrão: https://api.superserve.ai).

Comportamento e limites

• Retomada automática. sandbox_exec e as ferramentas de arquivo retomam transparentemente um sandbox pausado, então agentes nunca precisam chamar sandbox_resume primeiro. sandbox_resume existe apenas para aquecer um sandbox explicitamente.
• Saída limitada para contexto. sandbox_exec trunca stdout e stderr em 32 KiB cada — um resultado truncado define truncated: true e reporta o tamanho original em bytes. sandbox_files_read rejeita arquivos maiores que 1 MiB (não retorna conteúdo parcial); o erro orienta a ler um trecho com sandbox_exec (ex.: head -c) ou baixar o arquivo inteiro com o SDK/CLI. O conteúdo inline de sandbox_files_write é limitado a 8 MiB.
• Timeout padrão de comando é 60s, com teto de 10 minutos. Substitua por chamada com timeout_ms.
• Egress é controlável. allow_out (padrões de domínio ou CIDRs) adiciona destinos permitidos; deny_out (somente CIDRs) os bloqueia. allow_out sozinho não bloqueia um sandbox — para uma allowlist estrita, combine com deny_out: ["0.0.0.0/0"] (negue tudo, depois permita os destinos listados). Defina em sandbox_create ou sandbox_update e audite o que um sandbox realmente acessou com sandbox_network_log.
• Erros acionáveis. Uma chamada de ferramenta com falha retorna uma mensagem curta dizendo ao agente o que fazer em seguida — ex.: "Cota de sandbox atingida. Pause ou encerre um sandbox, ou tente novamente mais tarde." — em vez de um stack trace bruto, permitindo que o agente se autocorrija.

Segredos, templates e portas

Segredos. Não passe credenciais como env_vars em texto puro. Em vez disso:

1. Crie o segredo uma vez com o TypeScript SDK (Secret.create()) ou o console — o valor bruto nunca trafega pelo agente ou pelo servidor MCP, então a criação de segredos é intencionalmente não é uma ferramenta MCP.
2. Descubra segredos vinculáveis com secret_list (somente metadados — valores nunca saem da plataforma).
3. Vincule na criação — secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } em sandbox_create — ou depois com sandbox_attach_secret / sandbox_detach_secret.

O sandbox vê um token proxy; a plataforma troca pela credencial real apenas para requisições de saída aos hosts permitidos do segredo.

Templates. Um sandbox herda vCPU/memória/disco do seu template e não pode sobrescrevê-los no momento de sandbox_create. Para obter um formato específico (ex.: um sandbox de 4 vCPU) ou software pré-instalado, construa um template com sandbox_template_create e depois consulte sandbox_template_list até que seu status seja ready antes de passá-lo como from_template.

Portas. Novos sandboxes MCP usam public como acesso padrão para portas recém-publicadas; apenas portas publicadas explicitamente são alcançáveis. Passe preview_access: "private" para sandbox_create (ou sandbox_update) para alterar o padrão para portas futuras. Portas existentes mantêm seu próprio modo. Inicie o servidor com sandbox_exec e depois chame sandbox_preview_url; a ferramenta publica idempotentemente essa porta e usa o modo de porta retornado para devolver uma URL pública limpa ou uma URL privada assinada com expiração. Links privados têm padrão de uma hora; defina expires_in_seconds com um valor de 1 a 604800 segundos. Veja URLs de pré-visualização.

Ainda não no escopo do MCP

O servidor MCP cobre o loop comum de agente; a tabela acima é o conjunto completo de ferramentas v1. Alguns recursos do SDK ainda não estão expostos — use o TypeScript SDK diretamente para:

• Criação de segredos — Secret.create() (o servidor MCP apenas vincula segredos existentes).
• Comandos interativos e de streaming — streaming de run() callbacks e commands.spawn (stdin, sinais, processos de longa duração).
• Transferências grandes ou em streaming — download de diretórios é suportado até 10 MiB via sandbox_files_download_dir; além disso (e para uploads de arquivos/streaming ou arquivos únicos acima dos limites de leitura de 1 MiB / gravação inline de 8 MiB), use o SDK/CLI (files.downloadDir, upload em streaming).
• Cobrança e descoberta de provedores — dados de uso e Provider.list() para configuração de provedores de segredos.

Estes são acompanhados como itens futuros.

Como funciona

O servidor encapsula o SDK TypeScript e apenas mantém seu SUPERSERVE_API_KEY do plano de controle. Cada chamada de ferramenta conecta-se ao sandbox de destino por ID; o SDK gerencia o token de acesso do plano de dados por sandbox internamente e o rotaciona ao retomar, de modo que ele nunca é exposto ao modelo nem retornado na saída da ferramenta. As ferramentas são sem estado — não há um "sandbox atual" oculto — o que mantém o comportamento previsível em chamadas de múltiplas etapas e paralelas.

Solução de problemas

• As ferramentas não aparecem, ou o servidor falha ao iniciar. A chave de API é quase sempre a causa — clientes MCP não herdam variáveis de ambiente do seu shell. Defina SUPERSERVE_API_KEY no bloco env do servidor (veja Instalação), não apenas no seu terminal.
• Authentication failed. A chave está ausente ou inválida. Chaves de produção começam com ss_live_; crie uma na página de chave de API.
• A primeira chamada é lenta. npx baixa o pacote no primeiro uso e o armazena em cache; inicializações posteriores são rápidas.
• Requer Node 18+. O servidor local roda em Node via npx. (O endpoint hospedado não tem requisito de runtime local.)
• 401 Unauthorized do endpoint hospedado. O token de portador está ausente ou não é uma chave ss_live_ válida. Envie-o como Authorization: Bearer ss_live_… (veja Hospedado).

Relacionados

Pausar, retomar e excluir sandboxes. Exec, streaming, cwd, env e timeouts. Intermediar chaves de provedores sem expô-las ao sandbox. A biblioteca que o servidor MCP encapsula.