Claude, ChatGPT e outros apps de IA (MCP)

Conecte um assistente de IA ao seu número pelo servidor MCP do Wabox: OAuth com escolha de instâncias e permissões (ou o token da instância), tools de envio, grupos e conexão por QR, e como revogar.

O Wabox expõe um servidor MCP em https://mcp.wabox.me/mcp. Qualquer app compatível (Claude, ChatGPT, Claude Code, Cursor, Codex…) pode enviar mensagens, administrar grupos e até conectar o número pelo QR, usando as suas instâncias. A autorização é por OAuth: você escolhe quais instâncias e quais permissões numa tela do Wabox e pode revogar a qualquer momento em Apps conectados. Apps que não fazem OAuth podem usar o token da instância.

O MCP só envia e consulta metadados. Ele não lê o histórico de conversas (D14; as mensagens recentes guardadas no pareamento ficam só em GET /chats/{phone}/messages da REST). Para reagir a mensagens recebidas, use webhooks.

Conectar

Claude

1. No claude.ai, abra Configurações › Conectores › Adicionar conector personalizado.
2. Nome: Wabox. URL: https://mcp.wabox.me/mcp.
3. Clique em Conectar. O Wabox abre a tela de autorização: entre na sua conta, marque as instâncias e permissões e clique em Autorizar.

ChatGPT

1. Em Configurações › Conectores, ative o modo desenvolvedor e clique em Criar.
2. Nome: Wabox. URL: https://mcp.wabox.me/mcp. Autenticação: OAuth.
3. Clique em Criar e autorize na tela do Wabox.

Claude Code

claude mcp add --transport http wabox https://mcp.wabox.me/mcp

Depois, dentro do Claude Code, rode /mcp, escolha wabox e conclua a autorização no navegador.

Cursor

Em ~/.cursor/mcp.json (ou .cursor/mcp.json do projeto):

{
  "mcpServers": {
    "wabox": { "url": "https://mcp.wabox.me/mcp" }
  }
}

Em Settings › MCP, clique em wabox para autenticar.

Codex

codex mcp add wabox --url https://mcp.wabox.me/mcp
codex mcp login wabox

O segundo comando abre o navegador para você autorizar na tela do Wabox.

A mesma URL e os mesmos passos estão no painel, em Apps conectados › Como conectar.

Sem OAuth: token da instância

Para clientes que só sabem mandar um header (agentes rodando em servidor, n8n, scripts, Codex sem navegador), o servidor também aceita o token da instância como bearer. Nesse caso o app enxerga uma instância só, com todas as permissões, e valem as mesmas proteções da API REST: Client-Token (se ativado) e lista de IPs.

Claude Code

claude mcp add --transport http wabox https://mcp.wabox.me/mcp \
  --header "Authorization: Bearer $WABOX_INSTANCE_TOKEN"

Cursor

{
  "mcpServers": {
    "wabox": {
      "url": "https://mcp.wabox.me/mcp",
      "headers": { "Authorization": "Bearer ${env:WABOX_INSTANCE_TOKEN}" }
    }
  }
}

Codex

codex mcp add wabox --url https://mcp.wabox.me/mcp --bearer-token-env-var WABOX_INSTANCE_TOKEN

Com Client-Token ativado, envie também o header Client-Token (Claude Code e Cursor aceitam vários headers). O token da instância fica em Instância › Dados; gerar um novo token derruba o acesso do app.

A tela de autorização

Ao conectar por OAuth, o app é enviado para app.wabox.me/oauth/authorize. Ali você define:

Campo	O que significa
Workspace	Só aparece se você participa de mais de um.
Instâncias	O app só poderá usar as marcadas. Com uma instância só, ela já vem marcada.
Permissões	As que o app pediu; desmarque o que ele não deve poder fazer.

Qualquer membro do workspace pode autorizar um app. Owners e admins podem revogar qualquer autorização; membros, só as próprias.

Permissões (escopos)

Escopo	Libera
messages:send	send_text, send_image, send_audio, send_video
groups:read	group_metadata
groups:write	group_create, group_add_participants, group_remove_participants, group_add_admins, group_remove_admins
instance:read	list_instances, get_instance
instance:connect	instance_qr

O app só enxerga as tools dos escopos concedidos. status está sempre disponível.

Tools

Tool	O que faz
status	Ponto de partida: quem é o app, workspace, escopos, instâncias (conexão e assinatura) e próximos passos (instância desconectada, trial vencido, permissão que falta).
list_instances	Instâncias que o app pode usar: id, nome, número, status.
get_instance	Status ao vivo de uma instância (conectada, celular alcançável, assinatura).
instance_qr	O QR code de login como imagem, para você escanear direto no chat quando a instância cair. Inicia a sessão se for preciso; se já estiver conectada, diz isso.
send_text	Texto para um número ou grupo, com resposta (citação) opcional.
send_image / send_video	Mídia por URL pública, com legenda opcional.
send_audio	Áudio por URL. Vai como nota de voz por padrão (as_voice_note: false manda como arquivo).
group_create	Cria um grupo com participantes; a instância entra como admin.
group_metadata	Nome, descrição, participantes e admins.
group_add_participants / group_remove_participants	Adiciona ou remove números.
group_add_admins / group_remove_admins	Promove ou rebaixa participantes.

Todas aceitam instance_id. Ele é opcional quando o app foi autorizado para uma única instância; com várias, o app precisa informar (ou chamar list_instances antes).

O que acontece num envio

Antes de enfileirar, a tool confere que a instância está conectada, que a assinatura ou trial está ativa e que o número existe no WhatsApp. Erros voltam com o mesmo code da API REST (instance_not_connected, phone_not_on_whatsapp, subscription_required, rate_limited…), então o assistente consegue explicar o que faltou. O sucesso significa enfileirado: a entrega real chega no webhook delivery, com o mesmo message_id que a tool devolveu. Os envios passam pela mesma fila, pacing anti-ban e rate limit da API.

Exemplos de pedidos

Depois de conectar, peça ao assistente em linguagem natural:

• “Use o Wabox para ver o status da minha instância e me dizer o que falta.”
• “Meu número caiu. Pegue o QR do Wabox e me mostre para eu escanear.”
• “Mande pelo Wabox ‘Seu pedido saiu para entrega’ para o 5511988887777.”
• “Crie um grupo ‘Suporte Loja’ no Wabox com 5511988887777 e 5511977776666 e coloque o primeiro como admin.”
• “Envie para o grupo 120363012345678901-group a imagem https://exemplo.com/promo.png com a legenda ‘Promoção de hoje’.”

Revogar

Em Apps conectados (menu lateral, ou na aba da instância) cada autorização mostra o app, as instâncias, os escopos, quem autorizou e o último uso. Revogar corta o acesso na hora: o app precisa passar pela autorização de novo para voltar a usar suas instâncias. Apps que usam o token da instância são desligados gerando um novo token em Instância › Dados.

MCP da conta vs MCP das docs

Servidor	URL	Serve para
MCP da conta	https://mcp.wabox.me/mcp	Operar as suas instâncias: enviar, grupos, QR, status. Precisa de autorização.
MCP das docs	https://developer.wabox.me/mcp	Buscar nesta documentação. Só leitura, sem login. Veja Construir com IA.

Vale conectar os dois: o das docs ajuda o assistente a escrever a integração; o da conta deixa ele operar o número.

Segurança

• Por OAuth, o app nunca recebe o token da instância. Ele recebe tokens próprios, curtos (1 h) e renováveis, guardados hasheados. Reuso de um token de renovação já usado revoga a autorização inteira.
• Client-Token e lista de IPs não se aplicam a apps autorizados por OAuth: os apps de IA rodam na nuvem do fornecedor, com IPs que mudam, e a autorização já é uma credencial individual e revogável. Com o token da instância como bearer, os dois valem, como na REST.
• Para desenvolvedores de apps: o servidor segue a spec de autorização do MCP com registro dinâmico de clientes (RFC 7591), Client ID Metadata Documents, PKCE S256 obrigatório e metadata em /.well-known/oauth-authorization-server e /.well-known/oauth-protected-resource.