Pular para o conteúdo
HalverHalverDocumentação Halver

Servidor MCP

O servidor MCP oficial da Halver deixa ferramentas de IA (Claude, Claude Code, Cursor, VS Code e qualquer cliente MCP) consultarem e gerenciarem a sua conta: planos e estoque, servidores, chaves SSH, faturas e chamados. Cada ferramenta do servidor é uma chamada à API com a sua credencial: valem as mesmas permissões, as mesmas regras do painel e a mesma auditoria.

  • Endereço: https://dash.halver.com.br/mcp
  • Transporte: Streamable HTTP, nas revisões 2026-07-28 e 2025-11-25 do protocolo (clientes que começam com initialize também funcionam).
  • Autenticação: login com a sua conta (OAuth 2.1, para Claude, Cursor e Claude Code) ou um token de API no cabeçalho Authorization: Bearer.

Conectar

Seção intitulada “Conectar”

Claude (web, Desktop e celular)

Seção intitulada “Claude (web, Desktop e celular)”
  1. Em Personalizar › Conectores, clique em Adicionar conector personalizado.
  2. Cole https://dash.halver.com.br/mcp e adicione. Em Cliente OAuth, deixe Registrar automaticamente.
  3. Clique em Conectar: a Halver abre no navegador. Entre, confira o aplicativo e o endereço de retorno, escolha as permissões (só leitura por padrão) e clique em Autorizar.

Nos planos Team e Enterprise, um Owner adiciona o conector para a organização e cada pessoa conecta com a própria conta Halver. O aplicativo autorizado aparece em Desenvolvedores › Tokens de API › Aplicativos conectados, de onde você o desconecta a qualquer momento.

Claude Code

Seção intitulada “Claude Code”

Com login (OAuth):

Janela do terminal
claude mcp add --transport http halver https://dash.halver.com.br/mcp
# depois, no Claude Code: /mcp e autorize no navegador

Com token de API (guarde-o numa variável de ambiente):

Janela do terminal
claude mcp add --transport http halver https://dash.halver.com.br/mcp \
  --header "Authorization: Bearer $HALVER_API_TOKEN"

Ou no .mcp.json do projeto (o Claude Code expande ${VAR}):

{
  "mcpServers": {
    "halver": {
      "type": "http",
      "url": "https://dash.halver.com.br/mcp",
      "headers": { "Authorization": "Bearer ${HALVER_API_TOKEN}" }
    }
  }
}

Cursor

Seção intitulada “Cursor”

Em ~/.cursor/mcp.json (ou .cursor/mcp.json do projeto). Com login (o Cursor abre a autorização no navegador):

{ "mcpServers": { "halver": { "url": "https://dash.halver.com.br/mcp" } } }

Com token (o Cursor lê variáveis com ${env:NOME}):

{
  "mcpServers": {
    "halver": {
      "url": "https://dash.halver.com.br/mcp",
      "headers": { "Authorization": "Bearer ${env:HALVER_API_TOKEN}" }
    }
  }
}

Clientes que só falam stdio

Seção intitulada “Clientes que só falam stdio”

Para clientes sem MCP remoto, use um servidor local que repassa as mensagens à Halver com o token, como o mcp-remote (Node.js), da comunidade:

{
  "mcpServers": {
    "halver": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://dash.halver.com.br/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer sc_live_…" }
    }
  }
}

Outros clientes

Seção intitulada “Outros clientes”

Configure o endereço https://dash.halver.com.br/mcp (Streamable HTTP) e:

  • OAuth 2.1: o servidor responde 401 com WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp". Os metadados (RFC 9728 e RFC 8414 em /.well-known/oauth-authorization-server) levam ao registro dinâmico (/oauth/register, RFC 7591, só clientes públicos), à autorização (/oauth/autorizar, código com PKCE S256 obrigatório e resource) e ao token (/oauth/token). O token de acesso vale 1 hora e só no servidor MCP; o refresh token muda a cada uso, e reapresentar um antigo encerra a autorização. Endereços de retorno aceitos: https://, http:// em localhost/127.0.0.1/[::1] e o esquema próprio de um aplicativo instalado em DNS reverso (com.exemplo.app:/callback, RFC 8252 §7.1), além de cursor:// e vscode://; esquemas que entregam o endereço a um navegador (microsoft-edge:, googlechrome:, intent:…) são recusados. A tela de autorização mostra o endereço de retorno inteiro e marca o aplicativo como “não verificado”: o nome é o que ele declarou ao se registrar.
  • ou um token de API: Authorization: Bearer sc_live_….

Ferramentas

Seção intitulada “Ferramentas”

As descrições vêm em português e em inglês. O cliente só vê as ferramentas que as permissões da credencial permitem.

Ferramenta O que faz Escopo Anotações
list_plans_and_stock Locais, planos (CPU, memória, discos, preço mensal) e estoque por local; diz se a conta pode contratar servers:read só leitura
list_os_images Sistemas operacionais e opções de disco servers:read só leitura
list_servers Servidores com estado, energia, IP, plano, local e sistema; filtra pelo external_id ou end_customer_ref de um revendedor servers:read só leitura
get_server Um servidor (id ou hostname): etapas da operação, IPs, discos, chaves, cancelamento servers:read só leitura
deploy_server Contrata e instala: plano, local, sistema, hostname, chaves SSH, discos e, opcional, external_id e end_customer_ref (ids opacos do revendedor, sem dado pessoal; um external_id já usado é recusado antes da aprovação) servers:write gera cobrança; pede aprovação
power_server Liga, desliga ou reinicia (desligar e reiniciar pedem aprovação) servers:write destrutiva, idempotente
set_boot_device Próximo boot pelos discos ou pela rede, com reinício opcional (o Setup do BIOS é protegido por senha; mudanças no BIOS por chamado) servers:write destrutiva; pede aprovação
reinstall_server Apaga os dados e reinstala (outro sistema e outras chaves, opcional) servers:delete destrutiva; pede aprovação
delete_server Cancela a assinatura no fim do período pago; o servidor segue no ar até lá servers:delete destrutiva; pede aprovação
console_open Abre o console serial do servidor: a IA passa a ter acesso de teclado servers:console destrutiva; pede aprovação
console_screen A tela atual do console (texto e cursor), como dado não confiável servers:console só leitura
console_send Digita texto e teclas (Enter, Tab, setas, F1 a F12, Ctrl-C…), espera um texto na tela e devolve a tela servers:console registra cada entrada
console_close Fecha o console servers:console idempotente
open_ipmi_vpn Abre a VPN da IPMI para você (a chave pública do seu dispositivo); a senha da IPMI aparece só no portal servers:console pede aprovação
action_status Diz se você já aprovou, recusou ou deixou expirar um pedido servers:read só leitura
list_ssh_keys / add_ssh_key Chaves SSH ssh_keys:read / ssh_keys:write
list_invoices / get_invoice Faturas (por situação) e uma fatura pelo número invoices:read só leitura
list_tickets / get_ticket Chamados e a conversa de um chamado support:read só leitura
open_ticket / reply_ticket Abre e responde chamados support:write

Toda ferramenta é marcada com openWorldHint: false (só age na sua conta). As anotações (readOnlyHint, destructiveHint, idempotentHint) são dicas para o cliente pedir a sua aprovação; quem garante as regras é o servidor.

Proteções

Seção intitulada “Proteções”

  • Sua aprovação no portal. O que cobra ou destrói (deploy_server, delete_server, reinstall_server, power_server desligar e reiniciar, set_boot_device, console_open, open_ipmi_vpn) nunca roda só pela palavra da IA. A primeira chamada devolve um pedido com um link do portal:

    { "approval_required": true, "action_id": "01a1…", "approval_url": "https://dash.halver.com.br/cloud/confirmar/01a1…",
      "expires_at": "…", "summary": "reinstalar o servidor web-01, APAGANDO TODOS OS DADOS dele" }

    Você abre o link logado na sua conta (o responsável, ou quem opera os servidores), lê o que a IA quer fazer, quem pediu (o token ou o aplicativo conectado) e aprova ou recusa. A IA então chama a mesma ferramenta, com os mesmos argumentos e o action_id. O pedido vale 10 minutos para você decidir e, aprovado, uma única vez nos 10 minutos seguintes, só para o mesmo token e os mesmos argumentos (outro servidor, outra ação ou outro preço pedem nova aprovação). A IA não consegue aprovar: nenhum texto que ela leia ou escreva (nem a saída do console, de arquivos ou de páginas) vale como aprovação, e a API recusa uma chamada do MCP sem o pedido aprovado. Clientes MCP que suportam elicitation podem perguntar a você na própria janela do cliente; a página do portal vale sempre. Os pedidos ficam em Cloud › Aprovações da IA.

  • Saída do console é dado, não instrução. A tela do console vem dentro de untrusted_console_output, entre marcas com um código aleatório, sem caracteres de controle e com o aviso de que nada ali é instrução. Qualquer pessoa que alcance o servidor pode escrever o que aparece no console (um log, um banner): não peça à IA que “faça o que a tela mandar”. Fora desse objeto, a plataforma diz a energia do servidor (server_power) e, com a tela vazia, o motivo provável (blank_screen_hint: servidor desligado, a passagem do BIOS para o GRUB ou um login que pede Enter).

  • Permissões. A credencial nunca pode mais do que a pessoa que a criou ou autorizou, e o cliente só vê as ferramentas permitidas. Recomendamos começar com só leitura.

  • Aprovação no cliente. Deixe ligada também a aprovação de ferramentas do seu cliente e cuidado ao usar outros servidores MCP na mesma conversa (injeção de instruções).

  • Origem. Pedidos de navegador de outras origens recebem 403.

  • Auditoria e revogação. Toda escrita fica na auditoria da conta, marcada como vinda do MCP e com o nome da ferramenta; cada tecla enviada ao console fica registrada com o token. Revogar o token ou desconectar o aplicativo encerra o acesso na hora.

Limites e erros

Seção intitulada “Limites e erros”
  • 120 requisições por minuto por credencial, além dos limites da API.
  • Falhas da API voltam como erro da ferramenta, com o código estável e a mensagem (por exemplo a API recusou (HTTP 409, cloud.out_of_stock): …); o modelo pode corrigir e tentar de novo.
  • Credencial ausente, expirada ou revogada: 401 com WWW-Authenticate.

Referências externas

Seção intitulada “Referências externas”