Superserve Sandbox MCP

Servidor MCP

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

Quer deixar um agente criar 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, para que qualquer cliente compatível com MCP — Claude, Cursor, VS Code, Windsurf, Codex — possa criar sandboxes, executar comandos, ler e escrever arquivos, criar templates, gerenciar segredos e controlar 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. Ambas autenticam com sua SUPERSERVE_API_KEY e direcionam uma 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 uma sandbox e executar python --version nela". 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 a herdam do seu shell. Prefira um prompt de entrada secreta em vez de colar a chave crua 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`. `env_vars` encaminha `SUPERSERVE_API_KEY` do seu ambiente, então a chave crua 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 rodar 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 escopado por 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 UI de Custom Connector do Claude Desktop e o modo desenvolvedor do ChatGPT não oferecem campo de bearer estático / cabeçalho customizado (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 uma nova 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 suas sandboxes (ativas e pausadas), filtráveis por metadados.
sandbox_info	Obtém o status, recursos, metadados, regras de rede e vínculos de segredos de uma sandbox. Somente leitura.
sandbox_exec	Executa um comando de shell; retorna stdout, stderr e código de saída. Retoma automaticamente uma sandbox pausada.
sandbox_files_read	Lê um arquivo (texto UTF-8, ou base64 para binário).
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 em base64 (symlinks ignorados). Limitado a 10 MiB; maior → SDK/CLI.
sandbox_pause	Pausa uma sandbox; o estado é preservado.
sandbox_resume	Retoma uma sandbox pausada (geralmente desnecessário — exec retoma automaticamente).
sandbox_kill	Exclui permanentemente uma 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 uma sandbox (host, veredito, bytes) sem retomá-la.
sandbox_computer	Controla uma sandbox de desktop GUI: captura de tela, mouse, teclado, rolagem, redimensionamento, URL do visualizador. Uma ação por chamada.
sandbox_template_list	Lista os templates (imagens base) que seu time pode usar para iniciar.
sandbox_template_create	Cria um template customizado 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 uma sandbox em execução sob uma variável de ambiente.
sandbox_detach_secret	Remove um vínculo de segredo de uma 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 uma 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 uma sandbox pausada, então agentes nunca precisam chamar sandbox_resume primeiro. sandbox_resume existe apenas para aquecer uma 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 informa para ler um trecho com sandbox_exec (ex.: head -c) ou baixar o arquivo inteiro com o SDK/CLI. Conteúdo inline de sandbox_files_write é limitado a 8 MiB.
• Timeout padrão de comando é 60s, com máximo de 10 minutos. Substitua por chamada com timeout_ms.
• Egress é controlável. allow_out (padrões de domínio, IPs ou CIDRs) adiciona destinos permitidos; deny_out (IPs ou CIDRs, sem domínios) os bloqueia. allow_out sozinho não bloqueia uma sandbox — para uma allowlist estrita, combine com deny_out: ["0.0.0.0/0"] (negue tudo, depois permita os destinos listados). Se a allowlist tiver regras de domínio ou a carga de trabalho resolver hostnames, permita também os resolvedores DNS da sandbox, 1.1.1.1/32 e 8.8.8.8/32, já que negar tudo bloqueia também o DNS; deixe-os de fora de uma allowlist só de IPs, onde um resolvedor permitido é apenas um canal extra de saída. Defina isso em sandbox_create ou sandbox_update, e audite o que uma 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 uma sandbox, ou tente novamente mais tarde." — em vez de um stack trace cru, para que o agente possa se autocorrigir.

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 no console — o valor cru 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.

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

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

Portas. Novas 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 mudar o padrão para portas futuras. Portas existentes mantêm seu próprio modo. Inicie o servidor com sandbox_exec, depois chame sandbox_preview_url; a ferramenta publica idempotentemente essa única 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 padrão de uma hora; defina expires_in_seconds para um valor de 1 a 604800 segundos. Veja URLs de pré-visualização.

Uso de computador

sandbox_computer controla um desktop GUI em uma sandbox criada a partir de um template de desktop como superserve/desktop. Recebe uma action por chamada no vocabulário que modelos de computer-use emitem: 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 e stream_url. Ações de ponteiro recebem coordinate: [x, y] em pixels de tela (origem no canto superior esquerdo); key e type recebem text; scroll recebe scroll_direction e um 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" }

Ações de entrada retornam uma nova captura de tela do resultado, então o ciclo agir-depois-olhar do modelo é uma única chamada de ferramenta; passe screenshot_after: false ao enviar várias ações em sequência. wait pausa por duration_ms (máximo de 10 segundos) sem uma requisição à sandbox. stream_url retorna um visualizador de navegador ao vivo para o desktop sob a política de pré-visualização da sandbox.

Se uma ação de entrada falhar, a entrada pode já ter sido entregue. A ferramenta informa isso e pede ao agente para tirar uma captura de tela antes de repetir. Veja o Guia de desktop para a superfície subjacente do SDK.

Ainda não na superfície 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 SDK TypeScript diretamente para:

• Criação de segredos — Secret.create() (o servidor MCP apenas vincula segredos existentes).
• Comandos interativos e de streaming — callbacks de streaming run() 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 arquivo/streaming ou arquivos únicos acima dos limites de 1 MiB de leitura / 8 MiB de escrita inline), 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 estão registrados como acompanhamentos 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, então 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 ferramentas multi-turno 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; inícios posteriores são rápidos.
• 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.

Esta documentação é construída e hospedada no Mintlify, uma plataforma de documentação para desenvolvedores.