MCP para WhatsApp: conecte Claude e Cursor ao número oficial

Um servidor MCP para WhatsApp é o que permite a um agente de IA (Claude, Cursor, Claude Code ou qualquer cliente compatível com o Model Context Protocol) operar o seu número oficial por linguagem natural: listar conversas, resumir o que ficou sem resposta, montar um público e disparar uma campanha. O agente não fala com a Meta. Ele fala com um servidor que já conhece as regras da Cloud API, e é esse servidor que decide o que pode e o que não pode sair.

Este guia explica o que o MCP faz, como conectar os clientes mais usados e por que todo envio passa por uma confirmação dupla antes de acontecer.

O que é MCP e o que ele faz com o WhatsApp

MCP (Model Context Protocol) é um padrão aberto para dar ferramentas a modelos de linguagem. Em vez de o agente "adivinhar" como chamar uma API, o servidor MCP publica uma lista de tools com nome, descrição e parâmetros, e o cliente de IA as chama como funções. É o mesmo mecanismo que permite ao Claude ler um arquivo ou consultar um banco de dados, aplicado ao WhatsApp.

No caso do WhatsApp, as ferramentas cobrem o que uma pessoa faria no painel:

• Ler: quais números estão conectados, qual o estado de cada um, o que chegou nas últimas horas, quem está esperando resposta.
• Preparar: criar um template para aprovação da Meta, cadastrar contatos, montar um segmento de público.
• Agir: responder uma conversa aberta, enviar um template, criar uma campanha.

A diferença para um chatbot é o sentido do fluxo. Um chatbot responde a quem escreve. Um agente com MCP trabalha para o operador: é você quem pede "resuma o que ficou sem resposta hoje" ou "confirme as consultas de amanhã", e o agente usa as ferramentas para executar.

Por que o agente não deve falar direto com a Meta

Dá para colocar o token da Cloud API na mão de um agente e deixá-lo chamar o Graph API. É uma má ideia por três motivos.

A Meta tem regras que o modelo não conhece. Mensagem livre só pode sair dentro da janela de 24 horas aberta pelo cliente; fora dela, só template aprovado. Um agente que não sabe disso vai receber o erro 131047 e, pior, pode tentar contornar reenviando. O servidor MCP conhece a janela e devolve o motivo em vez de tentar de novo.

O token da Cloud API é amplo demais. Ele autoriza tudo na conta do WhatsApp Business, inclusive apagar templates e mudar configurações. Um token de API do Frame Conexa tem escopo: enxerga só as instâncias da sua conta, respeita a cota e pode ser revogado num clique sem derrubar o resto.

Envio em massa precisa de freio. Uma campanha para 2.000 pessoas não pode nascer de um "sim" mal interpretado. O servidor exige preview e confirmação antes de qualquer disparo, e isso fica fora do alcance do agente.

Como funciona o servidor MCP do Frame Conexa

O Frame Conexa expõe um servidor MCP em https://frameconexa.com/mcp, com transporte Streamable HTTP. Ele é stateless: cada chamada é independente e autenticada pelo mesmo token fc_ da API pública. Não há sessão para expirar. Um agente pode ficar dias sem chamar e continuar funcionando.

Endpoint, token e o que o agente enxerga

A autenticação é o token gerado em Configurações → API no painel, enviado no header Authorization: Bearer fc_SEU_TOKEN. Requisições são POST com JSON-RPC 2.0. Um GET responde 405, porque não há stream de sessão para abrir.

curl -X POST https://frameconexa.com/mcp \
  -H "Authorization: Bearer fc_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

O que o agente enxerga é exatamente o que o token enxerga. As ferramentas são um espelho da API pública /api/v1: mesmo escopo por token, mesmas cotas, mesmos códigos de erro. Nada de SQL, nada de atalho. Se o token é de uma conta comum, o agente vê todas as instâncias daquela conta e nada além.

As ferramentas: listar, ler, enviar, criar campanha

Leitura primeiro: quase toda operação exige o id de uma instância, que sai de list_instances.

Dupla confirmação: preview e token de 10 minutos antes de qualquer envio

Por padrão, send_message e create_campaign não executam na primeira chamada. Elas devolvem um preview (destinatário ou alcance do segmento, template, projeção de consumo) e um confirmationToken com validade de 10 minutos. O agente mostra o preview para você. Só a segunda chamada, com os mesmos argumentos e o token, efetiva o envio.

Mudar qualquer argumento entre as duas chamadas invalida o token. O que foi aprovado é o que sai.

O interruptor dessa trava é por token de API, no painel. Ele fica fora do alcance do agente de propósito: quem decide desligar é quem responde pela conta, não o software que ela contém.

Atenção: com a trava desligada, um agente com o token dispara mensagens e campanhas sem nenhuma etapa humana. Desligue apenas para automações que você mesmo revisou, e prefira um token separado por automação, para poder revogar sem derrubar o resto.

Configurar no Claude Desktop, Claude Code e Cursor

O token é a única credencial. Guarde-o com o mesmo cuidado de uma senha e nunca o coloque em configuração versionada num repositório público.

Claude Code, um comando:

claude mcp add --transport http conexa https://frameconexa.com/mcp \
  --header "Authorization: Bearer fc_SEU_TOKEN"

Cursor, Windsurf e clientes que leem um arquivo de configuração:

{
  "mcpServers": {
    "conexa": {
      "url": "https://frameconexa.com/mcp",
      "headers": {
        "Authorization": "Bearer fc_SEU_TOKEN"
      }
    }
  }
}

claude.ai e Claude Desktop: adicione um conector remoto personalizado apontando para a URL e informe o header de autorização. A partir daí as ferramentas aparecem em qualquer conversa.

Para testar, peça algo de leitura: "liste meus números conectados". Se a resposta trouxer as instâncias com estado e tipo, a conexão está pronta.

Três usos práticos

"Resuma as conversas sem resposta de hoje"

O agente chama list_instances, depois list_messages na instância certa, filtra o que chegou nas últimas horas sem uma mensagem de saída depois e devolve um resumo por contato. Nenhum envio acontece. É o uso mais seguro e o que mais economiza tempo de quem atende: a fila do dia, lida em um minuto.

"Confirme as consultas de amanhã"

Aqui entra a regra da janela. Para quem escreveu nas últimas 24 horas, o agente pode responder com mensagem livre. Para quem não escreveu, só template aprovado de utilidade (um lembrete de agendamento, por exemplo). O servidor sabe qual é o caso de cada contato e o preview mostra, antes de confirmar, quantas mensagens vão sair e por qual caminho. Se não houver template aprovado para o caso, o agente para e diz por quê, em vez de tentar mandar mensagem livre fora da janela.

"Monte um público com quem clicou no botão da última campanha"

get_campaign traz o resultado da campanha, inclusive quem clicou nos botões de resposta rápida; create_audience_segment e set_segment_membership transformam isso num público estático. A campanha seguinte pode partir dele. Tudo com preflight_campaign antes, que valida template, alcance e capacidade do número sem gravar nada.

O que a Meta permite: bot de atendimento x "AI Provider"

Vale separar duas coisas que se confundem.

Usar IA para atender o seu próprio negócio, como agendar, confirmar pedido, fazer triagem, responder dúvida sobre o produto, é o uso normal da plataforma. A própria Meta cita um bot de suporte de uma empresa de viagens como exemplo do que é permitido.

O que a Meta passou a restringir, segundo a página dela sobre o tema, são os "AI Providers": empresas cujo produto principal é um assistente de IA de propósito geral distribuído pelo WhatsApp. Esse caso tem termos e cobrança próprios, e não é o cenário de quem usa MCP para operar o atendimento de uma loja, de uma clínica ou de uma escola.

O agente conectado por MCP está do lado de dentro: ele ajuda o operador da conta a trabalhar. Não é um produto de IA oferecido ao público do WhatsApp.

Segurança: escopo do token, auditoria e como desligar

• Escopo: o agente só vê o que o token vê. Token de conta comum vê a conta inteira; token escopado a um cliente final, numa parceria de software, vê só aquele cliente.
• Limite de chamadas: o MCP compartilha o rate limit por token da API, 120 requisições por minuto. Em 429, o servidor devolve Retry-After e o agente deve esperar.
• Resultado incerto: quando a Meta não responde a tempo, o erro vem com ambiguous: true. Significa que o envio pode ter saído. O agente nunca deve reenviar às cegas; a instrução é conferir em list_messages ou get_campaign antes.
• Auditoria: toda ação passa pela mesma API pública, com os mesmos registros. O que o agente fez aparece no painel como qualquer outro envio.
• Desligar: revogue o token em Configurações → API. O agente perde acesso na hora, sem afetar outros tokens nem o painel.

Se você já integra por API e webhook ou por n8n e Make, o MCP não substitui nada disso. Ele é a porta para o caso em que a pessoa quer pedir em linguagem natural, e não montar um fluxo. As duas coisas convivem no mesmo número.

Próximo passo

O guia técnico completo, com a lista de ferramentas e o fluxo recomendado para campanhas, está na documentação do servidor MCP. Para conectar um número e gerar o primeiro token, veja os planos por número.