---
title: MCP para WhatsApp: conecte Claude e Cursor ao número oficial
description: O que é um servidor MCP para WhatsApp, como conectar Claude, Cursor ou outro agente de IA ao seu número oficial e por que o envio exige confirmação dupla.
date: 2026-09-06
category: integracao
tags: mcp, agente de ia, claude, cursor, cloud api
author: gabriel-miranda
cover: /blog-assets/covers/mcp-whatsapp-agente-de-ia.jpg
coverAlt: Estação de trabalho com notebook e monitor para desenvolvimento
coverSource: https://www.pexels.com/photo/34804016/
---

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](/blog/janela-de-24-horas-whatsapp) 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.

```bash
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`](/docs): 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`.

| Grupo | Ferramentas | O que fazem |
|---|---|---|
| Instâncias | `list_instances`, `get_instance` | Números conectados, estado, tipo (atendimento ou marketing), qualidade e capacidade de envio |
| Conversas | `list_messages`, `list_contacts`, `mark_message_read` | Mensagens e contatos de uma instância; é onde se confere se um envio saiu |
| Templates | `list_templates`, `create_template`, `update_template`, `delete_template` | Templates da conta na Meta; criar e editar exige número de marketing |
| Envio | `send_message` | Envio individual no formato da Cloud API, com confirmação dupla |
| Público | `list_audience_segments`, `create_audience_segment`, `upsert_audience_contact`, `set_segment_membership` | A base de contatos e segmentos que alimenta campanhas |
| Campanhas | `campaigns_health`, `preflight_campaign`, `create_campaign`, `get_campaign`, `cancel_campaign`, `resume_campaign` | Simular, criar com idempotência, acompanhar, cancelar e retomar |

### 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:

```bash
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**:

```json
{
  "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](/blog/whatsapp-cloud-api-como-integrar-webhook) ou por [n8n e Make](/blog/whatsapp-business-api-n8n-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.

## Perguntas frequentes

### O que é um servidor MCP?

É um serviço que publica ferramentas (funções com nome, descrição e parâmetros) para agentes de IA, no padrão Model Context Protocol. O cliente de IA lê a lista e chama as ferramentas conforme a conversa pede. No Frame Conexa, as ferramentas operam o seu número oficial do WhatsApp.

### O agente de IA pode enviar mensagem sozinho?

Por padrão, não. `send_message` e `create_campaign` devolvem um preview e um token de confirmação de 10 minutos; o envio só acontece na segunda chamada, com o token. A trava pode ser desligada por token de API, no painel, por quem responde pela conta.

### Funciona com Claude, Cursor e ChatGPT?

Funciona com qualquer cliente que suporte MCP por HTTP: Claude Code, Claude Desktop e claude.ai (conector remoto), Cursor, Windsurf e clientes construídos com os SDKs do protocolo. A autenticação é sempre o header `Authorization: Bearer fc_SEU_TOKEN`.

### Isso é permitido pela Meta?

Usar IA para operar o atendimento do seu próprio negócio é uso normal da plataforma. As restrições da Meta, segundo a página dela sobre "AI Providers", valem para quem oferece um assistente de IA de propósito geral como produto pelo WhatsApp, o que não é o caso de um agente que ajuda o operador da conta.

### Quanto custa uma mensagem enviada pelo agente?

O mesmo que qualquer mensagem pela API oficial: a Meta cobra por mensagem de template entregue, conforme a categoria e o país do destinatário, e mensagem livre dentro da janela de 24 horas segue a regra vigente para mensagens de serviço. O Frame Conexa não cobra por mensagem. Veja [quanto custa a WhatsApp Business API](/blog/whatsapp-business-api-preco).

## 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](/docs/guides/mcp). Para conectar um número e gerar o primeiro token, veja os [planos por número](/#precos).