Um servidor MCP do WhatsApp é a ponte entre um assistente de IA e o seu WhatsApp CRM: o assistente pede uma ferramenta, o servidor faz uma chamada de API já verificada e a resposta volta para a conversa com o assistente. Na WACRM essa ponte é o wacrm-mcp, parte do WACRM API & MCP, e ele trabalha no seu número do WhatsApp Business com chaves que você mesmo limita, controla e revoga. Este playbook faz parte dos guias da WACRM para todo negócio que vende online.
O que é um servidor MCP do WhatsApp?
É um servidor MCP cujas ferramentas são ações de um WhatsApp CRM. O Model Context Protocol, que a Anthropic apresentou em 25 de novembro de 2024, é descrito pelos seus mantenedores como um padrão de código aberto para conectar aplicações de IA a sistemas externos. Claude, ChatGPT, Visual Studio Code e Cursor estão entre os clientes que o suportam, então um mesmo servidor funciona com muitos assistentes.
As três partes de uma conexão MCP
A arquitetura do MCP tem três participantes:
- Host: o aplicativo de IA em que você digita, como Claude Desktop ou Cursor.
- Cliente: a peça dentro do host que mantém uma conexão com um servidor.
- Servidor: o programa que oferece ferramentas, recursos e prompts. O wacrm-mcp oferece só ferramentas.
As mensagens entre eles usam JSON-RPC 2.0. Um servidor local conversa com o seu cliente pela entrada e saída padrão (stdio); um remoto usa Streamable HTTP. O wacrm-mcp é um servidor stdio local: roda com Node.js 20 ou superior no computador onde roda o seu cliente de IA e chega à WACRM por HTTPS com a sua API key.
Um número comercial, não uma sessão do WhatsApp Web
Muitos projetos de “WhatsApp MCP” que você encontra na internet controlam uma conta pessoal de WhatsApp por meio de uma sessão do WhatsApp Web. Isso é outra coisa. O wacrm-mcp nunca mexe em uma sessão do celular: toda ferramenta chama a Core API da WACRM, que trabalha com o número da WhatsApp Business Platform conectado ao seu projeto. Suas mensagens, contatos e inbox ficam no CRM que a sua equipe já usa, e toda chamada passa pela mesma verificação de scopes que qualquer outra requisição à API.
Note
Em uma linha: o modelo de IA fica no seu cliente, as regras de negócio ficam na Core API da WACRM e o wacrm-mcp só traduz uma chamada de ferramenta em uma chamada de API. Ele não tem lógica de negócio própria.
O que um agente de IA pode fazer na WACRM pelo MCP?
O mesmo que uma pessoa da equipe faz no inbox, dentro dos scopes da chave. As 11 ferramentas se dividem em cinco grupos: mensagens, contatos, atualizações de pedidos, a carteira e o inbox.
| Ferramenta | O que o agente pode fazer | Scope necessário |
|---|---|---|
send_template | Enviar um template de WhatsApp aprovado a um cliente; uma nova tentativa com a mesma Idempotency-Key nunca envia duas vezes | messages:send |
read_conversation | Ler o histórico de mensagens com um contato, página por página | contacts:read |
create_contact | Criar um contato a partir de um número de telefone, com nome e e-mail opcionais | contacts:write |
notify_order | Inscrever o seu próprio endpoint HTTPS nas atualizações de status das mensagens, para confirmações de pedido e de entrega | wa_webhooks:write |
wallet_balance | Ler o saldo da carteira de tokens do projeto e o consumo deste ciclo | wallet:read |
list_conversations | Listar conversas do inbox por status, responsável, etiqueta, busca ou janela aberta | contacts:read |
assign_conversation | Atribuir até 20 conversas a uma pessoa da equipe ou a um agente de IA, ou remover o responsável | inbox:write |
add_note | Adicionar uma nota privada para a sua equipe; ela nunca é enviada ao cliente | inbox:write |
label_conversation | Adicionar ou remover etiquetas em até 20 conversas | inbox:write |
resolve_conversation | Resolver até 20 conversas; uma nova mensagem do cliente reabre a conversa | inbox:write |
inbox_report | Ler o relatório diário do inbox por agente, equipe, canal ou etiqueta, ou a visão ao vivo | inbox:read |
A lista de ferramentas e scopes corresponde à página do wacrm-mcp, que continua sendo a referência se a lista mudar. O preset MCP do Workspace marca exatamente os sete scopes da coluna da direita, e você pode desmarcar qualquer um.
Como uma chamada de ferramenta chega ao WhatsApp?
Em cinco passos curtos, com duas verificações antes de qualquer coisa acontecer. Você pede algo ao seu assistente
com palavras simples, o modelo escolhe uma ferramenta e o cliente envia uma requisição tools/call ao wacrm-mcp.
1 · Você pergunta
”Quais conversas ainda estão esperando resposta?“
2 · O modelo escolhe uma ferramenta
list_conversationscom um filtro de status.3 · Ação autorizada
O wacrm-mcp pede à Core API que conte uma ação no limite da chave.
4 · Scope verificado
A Core API verifica o scope e o projeto da chave e executa a chamada.
5 · Resultado
A lista volta para o seu assistente, ou um template sai do seu número.
Duas regras do WhatsApp definem o que o assistente pode enviar. A Meta abre uma janela de atendimento ao cliente de
24 horas cada vez que um cliente escreve para você; fora dela, uma empresa só pode enviar mensagens de template,
segundo a documentação de preços da Meta. Por isso a
ferramenta de envio do MCP é send_template: um template aprovado vale a qualquer momento. Desde 1º de julho de 2025
a Meta cobra a WhatsApp Business Platform por mensagem entregue, então cada template que o assistente envia é uma
mensagem que a sua empresa paga à Meta.
Quando uma chamada falha, o assistente vê o motivo. Um scope que falta volta como insufficient_scope, um limite do
plano esgotado como plan_limit_reached, e o rate limiting também como erro. Uma ferramenta nunca devolve um
resultado vazio em silêncio, então o modelo não confunde “não permitido” com “nada encontrado”.
Como manter o agente dentro de limites seguros?
Decidindo, chave por chave, o que ele pode tocar e com que frequência. Esses controles ficam na Core API da WACRM e no Workspace, não no assistente, então nenhum prompt consegue contorná-los:
- Scopes por chave. Uma chave carrega só os scopes que você marcou. Uma ferramenta cujo scope falta responde
insufficient_scopeem vez de agir. - Um projeto por chave. Uma chave de projeto só alcança o próprio projeto; pedir dados de outro projeto retorna não encontrado.
- Um limite mensal de ações. Defina qualquer número inteiro de 1 a 1.000.000, ou deixe vazio. Cada chamada de ferramenta conta como uma ação. No limite, a lista de chaves mostra “Limite atingido” e as chamadas seguintes são recusadas, sem cobrança, até você aumentar o limite ou o mês reiniciar (UTC).
- Um limite em massa de 20.
assign_conversation,label_conversationeresolve_conversationrecusam mais de 20 conversas em uma chamada combulk_requires_approval. Limpezas maiores ficam com uma pessoa. - Envios que nunca duplicam.
send_templatesempre leva uma Idempotency-Key, então um cliente que tenta de novo após um timeout recebe a primeira resposta em vez de mandar a mensagem duas vezes ao cliente. - Revogar com um clique. Revogar uma chave interrompe aquele cliente na hora. A página Ferramentas de IA (MCP) só aparece para o dono do projeto, e o cartão de uso lista as ações recentes e se cada uma foi permitida ou recusada.
Note
Mantenha a chave fora da conversa. A chave aparece uma única vez, fica na configuração do cliente como
WACRM_API_KEY e só é enviada no header Authorization: Bearer. O wacrm-mcp nunca a registra em log nem a repete
em um resultado de ferramenta, então nunca cole a chave em um prompt.
A Business Policy do WhatsApp também pede que uma empresa que automatiza respostas ofereça caminhos claros para falar com uma pessoa. Um assistente no MCP é um ajudante interno da sua equipe, então a regra voltada ao cliente é cumprida do jeito de sempre: uma pessoa da equipe está a um toque no inbox.
Quais casos de uso funcionam para uma loja online?
Comece por tarefas em que um erro não custa nada e depois acrescente envios. Estes quatro cobrem quase tudo o que uma loja pede ao seu assistente, e cada um indica as ferramentas e os scopes de que precisa, para você criar uma chave só para aquela tarefa.
Triagem do inbox pela manhã
Peça ao assistente todas as conversas abertas que ainda esperam resposta, agrupadas por assunto, com um resumo de
uma linha para cada uma. Ele chama list_conversations com status aberto e o filtro de janela aberta, lê com
read_conversation as conversas que precisam de contexto e sugere etiquetas como “tamanho”, “entrega” ou
“reembolso”.
Você
Quais conversas de WhatsApp ainda estão esperando por nós hoje de manhã?
Assistente · usou list_conversations, read_conversation
- 1. Cliente pergunta se o tênis azul veste pequeno. Etiqueta sugerida: tamanho.
- 2. Cliente quer a data de entrega de um pedido feito na segunda-feira. Etiqueta sugerida: entrega.
- 3. Cliente relata um pacote danificado e enviou uma foto. Precisa de uma pessoa.
Posso etiquetar as conversas 1 e 2 e deixar uma nota privada na conversa 3 para a equipe?
Quando você concorda, label_conversation aplica as etiquetas e add_note deixa uma nota privada na conversa do
pacote danificado. Ferramentas e scopes: contacts:read, inbox:write. Um restaurante que recebe pedidos de
delivery ou uma clínica com uma fila matinal de dúvidas sobre agendamentos faz a mesma jogada.
Confirmações de pedido e status de entrega
Se a sua loja roda em WooCommerce ou Shopify, a
automação de pedidos da WACRM já envia confirmações de pedido com templates
aprovados. O assistente ajuda com as exceções: uma confirmação para um pedido que alguém da equipe recebeu por
telefone, ou um aviso de atraso na entrega. Ele envia com send_template, e notify_order inscreve o seu próprio
endpoint HTTPS nos eventos message.status, para o seu sistema saber quando cada mensagem foi entregue ou lida. Cada
entrega traz um header X-WACRM-Signature; o guia de webhooks mostra como
verificá-lo.
Leads de e-mail e formulários
Chega por e-mail um pedido de atacado, ou um formulário de contato cai no seu helpdesk. Peça ao assistente que crie
a pessoa com create_contact e deixe uma nota sobre o que ela pediu. Depois a sua equipe faz o acompanhamento pelo
WhatsApp a partir do inbox. Scope: contacts:write. Se o limite de contatos do plano for atingido, a resposta é
plan_limit_reached.
Um relatório semanal do inbox
Toda segunda-feira, peça o relatório do inbox da semana passada agrupado por agente ou por etiqueta, e a visão ao
vivo das conversas esperando agora. inbox_report devolve o relatório do inbox em JSON para o assistente resumir; a
exportação em CSV continua no Workspace. Acrescente wallet_balance ao mesmo prompt para ver o saldo de tokens e o
consumo deste ciclo antes de uma semana movimentada. Scopes: inbox:read, wallet:read. Os dois são só de leitura,
o que torna este caso a primeira tarefa mais segura para uma chave nova.
Qual a diferença entre MCP e o agente de IA integrado?
Eles fazem trabalhos diferentes e funcionam bem juntos. O agente de IA da WACRM conversa com os seus clientes: redige respostas com o seu catálogo no inbox, espera aprovação ou envia dentro das regras que o dono define, e para com o botão de pausa da IA. Um assistente no MCP trabalha para a sua equipe, no seu computador, dentro do seu próprio cliente de IA.
| Agente de IA integrado da WACRM | Seu próprio assistente no MCP | |
|---|---|---|
| Com quem conversa | Com clientes, na conversa do WhatsApp | Com você e a sua equipe, no cliente de IA |
| Onde roda | Dentro da WACRM | No seu cliente MCP, com o wacrm-mcp no mesmo computador |
| O que envia ao WhatsApp | Respostas, com aprovação prévia ou envio automático na janela de 24 horas | Templates aprovados via send_template |
| Tarefa típica | Responder dúvidas de preço e estoque, passar conversas para uma pessoa | Triagem, notas, etiquetas, relatórios, envios de exceção |
Os dois se encontram no inbox: assign_conversation pode atribuir uma conversa a um agente de IA ou a uma pessoa da
equipe. O playbook do agente de IA para e-commerce cobre em detalhe o
lado que atende os clientes.
Como conectar o seu primeiro cliente de IA?
Em três passos a partir do Workspace, sem código:
- Escolha o seu cliente de IA. Abra Settings → AI tools (MCP), clique em Conectar um cliente e escolha Claude Desktop, Cursor ou outro cliente MCP.
- Crie uma chave com o preset MCP. Os sete scopes já vêm marcados. Desmarque o que esta tarefa não precisa e defina um limite mensal de ações.
- Cole a configuração. Copie a chave uma vez e depois a configuração pronta:
claude_desktop_config.jsonpara o Claude Desktop,.cursor/mcp.jsonpara o Cursor ou uma linha de comando para outros clientes. Reinicie o cliente e as 11 ferramentas aparecem.
Nossa equipe entrega os arquivos do servidor wacrm-mcp com o seu Workspace e ajuda você a conectá-lo. As ações MCP funcionam nos planos Corporate e Partner; veja os preços. Para o passo a passo completo, com uma primeira chamada de API com curl, siga o guia rápido de API e MCP. Desenvolvedores que querem os endpoints diretos podem usar a referência para desenvolvedores.
O que verificar antes de um agente agir sozinho?
Passe por esta lista antes de dar a uma chave o scope messages:send ou inbox:write:
- A chave foi criada para uma única tarefa, só com os scopes dessa tarefa marcados.
- Há um limite mensal de ações, dimensionado para uma semana normal dessa tarefa.
- Os templates que o assistente pode enviar estão aprovados e têm nomes claros para o modelo escolher o certo.
- O seu prompt pede que o assistente confirme com você antes de qualquer envio, etiqueta ou resolução.
- Alguém confere toda semana o cartão de uso na página Ferramentas de IA (MCP).
- Você sabe onde fica o botão de revogar.
Lojas que vendem pelo WhatsApp todos os dias podem ver a configuração completa na página da solução para lojas online. Para conectar os seus sistemas e as suas ferramentas de IA, comece pelo WACRM API & MCP; para um agente construído em torno do seu próprio fluxo de trabalho, a nossa equipe de desenvolvimento sob medida monta a conexão com você.
