Superserve Sandbox MCP

Servidor MCP

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

O servidor MCP 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 gravar arquivos, construir templates, intermediar segredos e controlar o acesso à rede em uma microVM Firecracker isolada.

Execute-o de duas maneiras: localmente via stdio usando npx, ou no endpoint hospedado em https://mcp.superserve.ai sem instalação local. Ambos autenticam com sua SUPERSERVE_API_KEY e direcionam uma sandbox por chamada pelo ID. É um wrapper fino sobre o SDK TypeScript, 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 Instalar), depois peça ao agente para "criar uma sandbox e executar python --version nela." O agente chama sandbox_create, depois sandbox_exec, e relata o resultado — sem código seu.

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

Instalar

Defina `SUPERSERVE_API_KEY` no `env` do servidor — clientes MCP não o herdam do seu shell. Prefira um prompt de entrada secreta em vez de colar a chave bruta onde seu cliente oferecer suporte (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 simples:

```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 bruta não é 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 é sem estado e com escopo de conta (sua chave já mapeia para sua equipe), e o token do plano de dados por sandbox nunca sai do servidor.

A 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 API Anthropic Messages. Claude.ai, a UI do Conector Personalizado do Claude Desktop e o modo desenvolvedor do ChatGPT não oferecem um campo de bearer estático / cabeçalho personalizado (eles esperam OAuth), que o endpoint hospedado ainda não suporta — use a instalação [local](#install) 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 simples:

```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-o como um conector em uma requisição da [API Anthropic Messages](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 que a chave viaja como um cabeçalho bearer em vez de uma variável env.

Ferramentas

Ferramenta	O que faz
sandbox_create	Cria uma nova sandbox; retorna seu id. Ativa e pronta imediatamente. Aceita secrets e regras de egresso.
sandbox_update	Altera os metadados ou regras de egresso (allow_out/deny_out) de uma sandbox após a criação.
sandbox_list	Lista suas sandboxes (ativas e pausadas), filtráveis por metadados.
sandbox_info	Obtém o status, recursos, metadados, regras de rede e vinculações de segredos de uma sandbox. Somente leitura.
sandbox_exec	Executa um comando shell; retorna stdout, stderr, 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, data de modificação).
sandbox_files_download_dir	Baixa um diretório como um ZIP base64 (links simbólicos 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	Constrói a URL pública para uma porta de escuta (não autenticada — qualquer coisa nessa porta fica exposta à internet).
sandbox_network_log	Audita as conexões de saída de uma sandbox (host, veredito, bytes). Retoma automaticamente uma sandbox pausada.
sandbox_template_list	Lista os templates (imagens base) a partir dos quais sua equipe pode lançar.
sandbox_template_create	Constrói um template personalizado com uma forma específica de vCPU/memória/disco ou software pré-instalado (assíncrono — pesquise até ficar pronto).
secret_list	Lista segredos vinculáveis da equipe (apenas 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 uma vinculação 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 dessas para obter um ID e, em seguida, encadeie-o em chamadas posteriores. Ferramentas somente leitura (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_preview_url, sandbox_template_list, secret_list) são anotadas para que os clientes possam pular prompts de confirmação; sandbox_kill é anotada como destrutiva.

Exemplo

Um fluxo típico de agente para "criar uma sandbox, escrever um script Python que imprima os primeiros números 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 manter por perto) ou sandbox_kill (permanente).

Configuração

Variável	Obrigatório	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, para que os agentes nunca precisem chamar sandbox_resume primeiro. sandbox_resume existe apenas para aquecer uma sandbox explicitamente.
• A saída é limitada para contexto. sandbox_exec trunca stdout e stderr para 32 KiB cada — um resultado truncado define truncated: true e relata o comprimento original em bytes. sandbox_files_read rejeita arquivos maiores que 1 MiB (não retorna conteúdo parcial); o erro informa para ler uma fatia 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.
• O tempo limite padrão do comando é 60s, limitado a 10 minutos. Substitua-o por chamada com timeout_ms.
• O egresso é controlável. allow_out (padrões de domínio ou CIDRs) adiciona destinos permitidos; deny_out (apenas CIDRs) os bloqueia. allow_out sozinho não bloqueia uma sandbox — para uma lista de permissões estrita, combine-o com deny_out: ["0.0.0.0/0"] (negar tudo, depois permitir os destinos listados). Defina-os em sandbox_create ou sandbox_update e audite o que uma sandbox realmente acessou com sandbox_network_log.
• Erros são acionáveis. Uma chamada de ferramenta com falha retorna uma mensagem curta informando ao agente o que fazer a seguir — ex.: "Cota de sandbox atingida. Pause ou elimine uma sandbox, ou tente novamente mais tarde." — em vez de um rastreamento de pilha bruto, para que o agente possa se autocorrigir.

Segredos, templates e portas

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

1. Crie o segredo uma vez com o SDK TypeScript (Secret.create()) ou o console — o valor bruto nunca viaja 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 (apenas metadados — os valores nunca saem da plataforma).
3. Vincule na criação — secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } em sandbox_create — ou posteriormente com sandbox_attach_secret / sandbox_detach_secret.

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

Templates. Uma sandbox herda sua vCPU/memória/disco de seu template e não pode substituí-los no momento de sandbox_create. Para obter uma forma específica (digamos, uma sandbox de 4 vCPUs) ou software pré-instalado, construa um template com sandbox_template_create e, em seguida, consulte sandbox_template_list até que seu status seja ready antes de passá-lo como from_template.

Portas. Inicie um servidor na sandbox (sandbox_exec, ex.: python3 -m http.server 8000) e, em seguida, chame sandbox_preview_url para obter sua URL pública. Qualquer processo vinculado a uma porta é acessível em https://{port}-{id}.sandbox.superserve.ai com nenhuma autenticação — exponha apenas as portas que você pretende que sejam públicas.

Ainda não está na superfície MCP

O servidor MCP cobre o ciclo comum do 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 — streaming de callbacks run() e commands.spawn (stdin, sinais, processos de longa duração).
• Transferências grandes ou de streaming — o download de diretório é suportado até 10 MiB via sandbox_files_download_dir; além disso (e para uploads de arquivo/streaming ou arquivos únicos além dos limites de 1 MiB de leitura / 8 MiB de gravação inline), use o SDK/CLI (files.downloadDir, upload de streaming).
• Faturamento e descoberta de provedores — dados de uso e Provider.list() para configuração de provedor de segredos.

Estes são acompanhados como itens de acompanhamento.

Como funciona

O servidor encapsula o TypeScript SDK e mantém apenas o seu plano de controle SUPERSERVE_API_KEY. 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 nunca é exposto ao modelo ou 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últiplos turnos 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 Instalar), 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 executa no 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. Fornecer chaves de provedor sem expô-las ao sandbox. A biblioteca que o servidor MCP encapsula.