Desenvolvedores

API e MCP do BSN Cloud

Automatize suas VPS por código (REST) ou deixe um agente de IA cuidar delas por você (MCP). Tudo o que dá para fazer aqui passa pelas mesmas permissões e fica na mesma auditoria do painel.

API REST

https://app.bsncloud.com.br/api/v1

Documento OpenAPI

https://app.bsncloud.com.br/api/v1/openapi.json

Servidor MCP

https://app.bsncloud.com.br/mcp

Começar em 3 passos

1. Crie um token
No painel, em Conta › API, clique em Novo token, dê um nome (ex.: “script de backup”) e escolha o papel. O token aparece uma vez só: copie e guarde num lugar seguro.
2. Guarde o token numa variável
Assim ele não fica escrito no código nem no histórico de comandos.
```
export BSN_TOKEN="bcn_cole_o_seu_token_aqui"
```
3. Faça o primeiro pedido
Lista as suas VPS. Copie o “id” de uma para os próximos.
```
curl "https://app.bsncloud.com.br/api/v1/vps" \
  -H "Authorization: Bearer $BSN_TOKEN"
```

Tokens e permissões

Envie o token em todo pedido, no cabeçalho Authorization: Bearer bcn_…. Ele age como a pessoa que o criou, mas limitado ao papel escolhido (nunca mais do que o papel dela). Dá para revogar a qualquer hora em Conta › API, e todo uso fica na auditoria da conta.

Leitura

Vê tudo, não muda nada. O mais seguro para relatórios e agentes de IA que só consultam.

Técnico

Opera as VPS (ligar, snapshot, firewall, apps); não vê cobrança.

Financeiro

Faturas e pagamentos; só vê as VPS.

Admin

Tudo, menos encerrar a conta.

Dica: um token por uso (um para o script, outro para o agente de IA). Se um vazar, você revoga só ele.

Ações que demoram (ligar, snapshot, backup, apps)

O que muda a VPS entra numa fila e responde na hora com 202 e o id da ação. Para saber quando terminou, consulte obter_acao a cada poucos segundos: ela traz a situação (fila, executando, sucesso ou falha) e as etapas que já aconteceram, as mesmas que você vê no painel.

JavaScript

const h = { Authorization: `Bearer ${process.env.BSN_TOKEN}`, 'Content-Type': 'application/json' };
const base = 'https://app.bsncloud.com.br/api/v1';

// 1. Pede o snapshot (volta na hora com o id da ação)
const { id: acaoId } = await (await fetch(`${base}/vps/${vpsId}/snapshots`, {
  method: 'POST', headers: h, body: JSON.stringify({ nome: 'antes-da-atualizacao' }),
})).json();

// 2. Acompanha até terminar
let acao;
do {
  await new Promise((ok) => setTimeout(ok, 3000));
  acao = await (await fetch(`${base}/vps/${vpsId}/acoes/${acaoId}`, { headers: h })).json();
  console.log(acao.status, acao.passos.at(-1)?.passo);
} while (acao.status === 'fila' || acao.status === 'executando');

Erros

Todo erro volta em JSON com error (código), message (em português, para mostrar a uma pessoa) e, quando ajuda, acao (o que fazer) e campos.

200Deu certo (leitura).

202Pedido aceito: a ação entrou na fila. A resposta traz o id para acompanhar em obter_acao.

400Dado inválido. "campos" diz qual campo e por quê.

401Token ausente, errado, revogado ou expirado.

403O papel do token não permite isso (ex.: token de leitura tentando ligar a VPS).

404Não existe, ou não é desta conta.

409Conflito: outra ação já está rodando nesta VPS, ou ela ainda está sendo preparada.

429Muitos pedidos em pouco tempo. Espere alguns segundos e tente de novo.

Agentes de IA (MCP)

MCP é o jeito padrão de dar ferramentas a um assistente de IA. Conectando o BSN Cloud, você pede em português (“tira um snapshot da VPS da loja e me avisa quando terminar”) e o assistente usa as mesmas operações desta página. Antes de qualquer coisa que mude a VPS, ele precisa da sua confirmação.

Endereço: https://app.bsncloud.com.br/mcp · transporte HTTP (Streamable) · token no cabeçalho Authorization. Para um agente que só consulta, use um token de Leitura.

Claude Code (terminal)

Terminal

claude mcp add --transport http bsn-cloud https://app.bsncloud.com.br/mcp \
  --header "Authorization: Bearer $BSN_TOKEN"

Claude Desktop

Em Configurações › Desenvolvedor › Editar configuração, acrescente (precisa do Node.js instalado):

claude_desktop_config.json

{
  "mcpServers": {
    "bsn-cloud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.bsncloud.com.br/mcp",
        "--header",
        "Authorization:${BSN_AUTH}"
      ],
      "env": {
        "BSN_AUTH": "Bearer bcn_cole_o_seu_token_aqui"
      }
    }
  }
}

Cursor

.cursor/mcp.json

{
  "mcpServers": {
    "bsn-cloud": {
      "url": "https://app.bsncloud.com.br/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BSN_TOKEN}"
      }
    }
  }
}

VS Code (Copilot)

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "bsn-token",
      "description": "Token do BSN Cloud",
      "password": true
    }
  ],
  "servers": {
    "bsn-cloud": {
      "type": "http",
      "url": "https://app.bsncloud.com.br/mcp",
      "headers": {
        "Authorization": "Bearer ${input:bsn-token}"
      }
    }
  }
}

n8n

No agente de IA, adicione a ferramenta MCP Client: endereço https://app.bsncloud.com.br/mcp, transporte HTTP Streamable e autenticação Header Auth com nome Authorization e valor Bearer bcn_….

Referência

Cada operação existe na API REST e como ferramenta do MCP (o nome em verde). As marcadas muda algo pedem confirmação no MCP.

Conta

GET/conta obter_conta

Mostra a conta do token

Conta, pessoa e papel ligados ao token de API, com as permissões efetivas.

curl "https://app.bsncloud.com.br/api/v1/conta" \
  -H "Authorization: Bearer $BSN_TOKEN"

VPS

GET/vps listar_vps

Lista as VPS da conta

Todas as VPS da conta com status, IP dedicado, plano, uso e data de renovação.

curl "https://app.bsncloud.com.br/api/v1/vps" \
  -H "Authorization: Bearer $BSN_TOKEN"

GET/vps/{id} obter_vps

Detalhes de uma VPS

Configuração, sistema, ações recentes, snapshots e backups de uma VPS.

id*caminhoid (uuid)

curl "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS" \
  -H "Authorization: Bearer $BSN_TOKEN"

GET/vps/{id}/uso uso_vps

Uso de CPU, memória, disco e rede

Série de uso da VPS na janela pedida (hour, day, week, month, year).

id*caminhoid (uuid)

janelaconsulta"hour" | "day" | "week" | "month" | "year"padrão: day

curl "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/uso" \
  -H "Authorization: Bearer $BSN_TOKEN"

POST/vps/{id}/energiamuda algo energia_vps

Liga, desliga, reinicia ou para uma VPS

Põe a ação na fila e devolve o id dela; acompanhe as etapas em obter_acao. "desligar" pede ao sistema para desligar com segurança; "parar" corta na hora.

id*caminhoid (uuid)

acao*corpo"ligar" | "desligar" | "reiniciar" | "parar"

curl -X POST "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/energia" \
  -H "Authorization: Bearer $BSN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "acao": "ligar" }'

Ações

GET/vps/{id}/acoes listar_acoes

Ações recentes de uma VPS

O que foi pedido para a VPS e como terminou, com o roteiro de etapas de cada ação (feitas, em andamento, avisos).

id*caminhoid (uuid)

curl "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/acoes" \
  -H "Authorization: Bearer $BSN_TOKEN"

GET/vps/{id}/acoes/{acaoId} obter_acao

Acompanha uma ação

Situação de uma ação (fila, executando, sucesso, falha), as etapas do roteiro e as já feitas. Consulte a cada poucos segundos até "sucesso" ou "falha".

id*caminhoid (uuid)

acaoId*caminhoid (uuid)

curl "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/acoes/ID_DA_ACAO" \
  -H "Authorization: Bearer $BSN_TOKEN"

Snapshots e backups

POST/vps/{id}/snapshotsmuda algo criar_snapshot

Tira um snapshot da VPS

Foto rápida do disco para voltar depois (até 3 por VPS). Os snapshots aparecem em obter_vps.

id*caminhoid (uuid)

nome*corpotexto

descricaocorpotexto

curl -X POST "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/snapshots" \
  -H "Authorization: Bearer $BSN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "nome": "antes-da-atualizacao" }'

POST/vps/{id}/backupsmuda algo fazer_backup

Faz um backup agora

Cópia completa da VPS guardada fora dela. Os backups aparecem em obter_vps.

id*caminhoid (uuid)

curl -X POST "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/backups" \
  -H "Authorization: Bearer $BSN_TOKEN"

Rede

GET/vps/{id}/firewall obter_firewall

Regras do firewall da VPS

Portas liberadas e bloqueadas (valem também no IP dedicado).

id*caminhoid (uuid)

curl "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/firewall" \
  -H "Authorization: Bearer $BSN_TOKEN"

POST/vps/{id}/firewall/portasmuda algo liberar_porta

Libera uma porta no firewall

Abre uma porta (ex.: "8080") ou faixa ("3000-3010") para a internet. Vale em segundos.

id*caminhoid (uuid)

porta*corpotexto

protocolocorpo"tcp" | "udp"padrão: tcp

descricaocorpotextopadrão:

curl -X POST "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/firewall/portas" \
  -H "Authorization: Bearer $BSN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "porta": "8080", "protocolo": "tcp" }'

GET/vps/{id}/ip-dedicado saude_ip_dedicado

Saúde do IP dedicado

Se o IP dedicado está respondendo, desde quando e o tráfego do mês.

id*caminhoid (uuid)

curl "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/ip-dedicado" \
  -H "Authorization: Bearer $BSN_TOKEN"

Acesso

GET/vps/{id}/chaves-ssh listar_chaves_ssh

Chaves SSH da conta e quais valem nesta VPS

As chaves cadastradas na conta, marcando as que entram como root nesta VPS.

id*caminhoid (uuid)

curl "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/chaves-ssh" \
  -H "Authorization: Bearer $BSN_TOKEN"

Aplicativos

GET/aplicativos catalogo_aplicativos

Aplicativos que instalam sozinhos

Catálogo com slug, descrição, porta e memória mínima de cada app (use o slug em instalar_aplicativo).

curl "https://app.bsncloud.com.br/api/v1/aplicativos" \
  -H "Authorization: Bearer $BSN_TOKEN"

GET/vps/{id}/aplicativos aplicativos_da_vps

Aplicativos instalados numa VPS

Apps instalados, situação (instalando, pronto, falhou) e o endereço para abrir.

id*caminhoid (uuid)

curl "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/aplicativos" \
  -H "Authorization: Bearer $BSN_TOKEN"

POST/vps/{id}/aplicativosmuda algo instalar_aplicativo

Instala um aplicativo na VPS

Instala em Docker, ao lado do que já existe (não apaga nada). Leva de 2 a 10 minutos.

id*caminhoid (uuid)

slug*corpotexto

curl -X POST "https://app.bsncloud.com.br/api/v1/vps/ID_DA_VPS/aplicativos" \
  -H "Authorization: Bearer $BSN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "n8n" }'

Cobrança

GET/faturas listar_faturas

Faturas da conta

Faturas com status, valor, vencimento e link para pagar ou baixar o recibo.

curl "https://app.bsncloud.com.br/api/v1/faturas" \
  -H "Authorization: Bearer $BSN_TOKEN"

E-mail

GET/email/caixas listar_caixas_email

Caixas de e-mail da conta

Todas as caixas (endereço, nome e situação). Use o id nas outras operações de e-mail.

curl "https://app.bsncloud.com.br/api/v1/email/caixas" \
  -H "Authorization: Bearer $BSN_TOKEN"

GET/email/caixas/{caixaId}/pastas listar_pastas_email

Pastas de uma caixa

Pastas com o papel (entrada, enviados, lixeira…), total e não lidas.

caixaId*caminhoid (uuid)

curl "https://app.bsncloud.com.br/api/v1/email/caixas/SEU_CAIXAID/pastas" \
  -H "Authorization: Bearer $BSN_TOKEN"

GET/email/caixas/{caixaId}/mensagens listar_mensagens_email

Mensagens de uma pasta (com busca)

Lista paginada (mais novas primeiro) com remetente, assunto, data, prévia e marcas. Filtros: todas, nao_lidas, lidas, favoritas, com_anexo.

caixaId*caminhoid (uuid)

pastaconsultatextopadrão: INBOX

buscaconsultatexto

filtroconsulta"todas" | "nao_lidas" | "lidas" | "favoritas" | "com_anexo"padrão: todas

paginaconsultanúmeropadrão: 1

porPaginaconsultanúmeropadrão: 25

curl "https://app.bsncloud.com.br/api/v1/email/caixas/SEU_CAIXAID/mensagens" \
  -H "Authorization: Bearer $BSN_TOKEN"

GET/email/caixas/{caixaId}/mensagens/{uid} ler_mensagem_email

Lê uma mensagem

Cabeçalhos, texto, HTML limpo e lista de anexos. Ler marca como lida.

caixaId*caminhoid (uuid)

uid*caminhonúmero

pastaconsultatextopadrão: INBOX

curl "https://app.bsncloud.com.br/api/v1/email/caixas/SEU_CAIXAID/mensagens/SEU_UID" \
  -H "Authorization: Bearer $BSN_TOKEN"

POST/email/caixas/{caixaId}/enviarmuda algo enviar_email

Envia um e-mail pela caixa

Envia (texto ou HTML) e guarda a cópia em Enviados. Para responder na mesma conversa, informe respostaA {pasta, uid}.

caixaId*caminhoid (uuid)

paracorpoarraypadrão:

cccorpoarraypadrão:

ccocorpoarraypadrão:

assuntocorpotextopadrão:

textocorpotexto

htmlcorpotexto

respostaAcorpoobject

curl -X POST "https://app.bsncloud.com.br/api/v1/email/caixas/SEU_CAIXAID/enviar" \
  -H "Authorization: Bearer $BSN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/email/caixas/{caixaId}/movermuda algo mover_email

Move mensagens de pasta

Move as mensagens (uids) da pasta de origem para a pasta de destino.

caixaId*caminhoid (uuid)

pastacorpotextopadrão: INBOX

uids*corpoarray

destino*corpotexto

curl -X POST "https://app.bsncloud.com.br/api/v1/email/caixas/SEU_CAIXAID/mover" \
  -H "Authorization: Bearer $BSN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uids": "texto", "destino": "texto" }'

POST/email/caixas/{caixaId}/marcarmuda algo marcar_email

Marca como lida/não lida ou favorita

Muda as marcas de lida e/ou favorita das mensagens (uids) de uma pasta.

caixaId*caminhoid (uuid)

pastacorpotextopadrão: INBOX

uids*corpoarray

lidacorposim/não

favoritacorposim/não

curl -X POST "https://app.bsncloud.com.br/api/v1/email/caixas/SEU_CAIXAID/marcar" \
  -H "Authorization: Bearer $BSN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uids": "texto" }'