# MCP de WhatsApp, Instagram e Messenger para agents de IA — WAME

> URL: https://wame.api.br/mcp
> Resumo: O MCP da Wame é um servidor Model Context Protocol remoto, em https://mcp.wame.api.br, que dá a um agent de IA (Claude, Claude Code, Cursor, VS Code ou qualquer cliente MCP) as ferramentas para ler e enviar mensagens de WhatsApp, Instagram e Messenger em nome de uma instância da Wame. Uma instância cobre os três canais.

## O que é

Um servidor MCP remoto, transporte **streamable HTTP**, endpoint **https://mcp.wame.api.br** (a raiz atende MCP; `/mcp` é equivalente). Conectado a um cliente de IA, ele expõe tools como `send_message`, `read_messages`, `list_chats` e `wait_for_message` — o agent passa a operar a conta de mensageria direto, sem que você escreva integração.

**Uma conexão = uma instância da Wame.** Se a instância tiver mais de um canal ativo, as tools de envio ganham o parâmetro `channel`, cujo enum lista apenas os canais que aquela instância realmente possui.

## Como conectar

1. **Adicione o conector** — No Claude, em Configurações › Conectores, clique em Adicionar conector personalizado e cole https://mcp.wame.api.br. Ou use o botão acima, que já abre o modal preenchido.
2. **Clique em Vincular** — O Claude abre a página de autorização da Wame, onde você cola a key da instância. Ela está no painel, em Configurações da instância.
3. **Peça alguma coisa** — Volte para a conversa e mande "quem me chamou no WhatsApp?". O agent já enxerga as tools da sua instância — e só as que ela realmente tem.

Link direto que abre o Claude com o conector preenchido:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Wame&connectorUrl=https%3A%2F%2Fmcp.wame.api.br

No Claude Code, uma linha:
```bash
claude mcp add --transport http wame https://mcp.wame.api.br
```

No Cursor e no VS Code há link de instalação em um clique. Para cliente que só oferece um campo de URL, cole `https://mcp.wame.api.br` e conclua o Vincular; quem prefere header envia `X-API-Key: SUA_KEY`.

### Duas formas de autenticar

1. **OAuth** — o cliente abre uma página da Wame onde você cola a key da instância; ela vira um token cifrado e nunca aparece na URL do conector. É a forma para cliente que só tem campo de URL.
2. **Header** — `X-API-Key: SUA_KEY` (ou `Authorization: Bearer SUA_KEY`).

A key nunca vai na URL: não há rota que aceite a key no path. Endereço aparece em log de acesso, histórico do navegador e print de tela; header, não.

A key da instância é obtida no painel da Wame. Ela é a credencial completa: quem a possui envia e lê mensagens por aquela instância.

## O que dá para pedir

- **"quem me mandou mensagem hoje?"** — `list_chats`, `read_messages`. Lê as conversas por recência, com não lidas e horário, e resume o que interessa.
- **"manda pro 5566999999999 o PDF da proposta"** — `send_media`. Imagem, vídeo, áudio ou documento a partir de uma URL pública, com legenda.
- **"dispara o template de boas-vindas pra esses 30 contatos"** — `list_templates`, `send_template`. Mostra a prévia primeiro e só envia depois que você aprova. Até 50 por chamada.
- **"fica de olho e me avisa quando a Ana responder"** — `wait_for_message`. Segura a chamada esperando mensagem nova e encadeia rodadas de 55s sem deixar buraco.

## Tools

### Sempre disponíveis (Oficial e não oficial)

Quando a instância tem mais de um canal, as tools de envio ganham o parâmetro channel — com enum contendo só os canais que aquela instância realmente tem.

| Tool | Parâmetros | O que faz |
|---|---|---|
| `send_message` | `to, text, channel?` | Envia texto. Aceita número, grupo (id@g.us) ou id do find_contact. |
| `send_media` | `to, type, url, caption?` | Envia imagem, vídeo, áudio ou documento de uma URL pública. |
| `reply_to_message` | `messageId, to, text` | Responde citando a mensagem original. |
| `react_to_message` | `messageId, emoji` | Reage com emoji. Emoji vazio remove a reação. |
| `list_chats` | `limit?, onlyUnread?` | Conversas por recência, com não lidas e horário. Até 30. |
| `read_messages` | `chatId, limit?, page?` | Mensagens da conversa, da mais recente para a mais antiga. Até 100 por página. |
| `wait_for_message` | `timeoutSeconds?, chatId?` | Espera mensagem nova chegar e devolve na hora. Até 55s por rodada, encadeável. |
| `find_contact` | `query` | Busca na agenda por nome ou número. Até 8 resultados. |
| `check_number_registered` | `number` | Confere se o número existe no WhatsApp antes de enviar. |
| `mark_as_read` | `messageId, typing?` | Visto azul, com "digitando…" opcional junto. |
| `set_typing` | `to, status` | Mostra digitando, gravando áudio, online ou offline. |
| `get_instance_status` | `—` | Estado da instância: conectada, canais ativos, nome de exibição. |

### Só em instância oficial (Cloud API / Meta)

Template é recurso da WABA. Numa instância não oficial estas tools simplesmente não existem — o agent não vê o que não pode usar.

| Tool | Parâmetros | O que faz |
|---|---|---|
| `list_templates` | `onlyApproved?` | Templates da conta com o status na Meta e quantas variáveis o corpo espera. |
| `send_template` | `templateName, recipients[], confirm?` | Dispara template aprovado para até 50 números. Prévia obrigatória antes do envio. |
| `get_analytics` | `report?, since?, until?` | Uso contra o limite, conversas, mensagens, desempenho de template e custo. |

### Só em instância não oficial (QR Code)

A Cloud API não faz grupo nenhum — não lista, não cria, não envia. Numa instância oficial estas tools não aparecem.

| Tool | Parâmetros | O que faz |
|---|---|---|
| `list_groups` | `—` | Grupos de que a instância participa, com nome e nº de participantes. |
| `get_group` | `groupId, includeInvite?` | Detalhes, participantes, quem é admin e link de convite. |
| `create_group` | `name, participants[]` | Cria o grupo e notifica todo mundo na hora. |
| `update_group` | `groupId, name, description` | Renomeia e altera a descrição. Exige ser administradora. |
| `manage_group_participants` | `groupId, action, participants[]` | Adiciona, remove, promove ou rebaixa participante. |
| `leave_group` | `groupId` | Sai do grupo. |

## Por que a Wame

- **Três canais, uma instância** — WhatsApp, Instagram e Messenger oficiais na mesma conta, com os mesmos endpoints e o mesmo envelope de webhook. Uma credencial, um conector, três redes.
- **Oficial e não oficial juntos** — QR Code sem app na Meta, ou Cloud API com Embedded Signup — na mesma plataforma e no mesmo SDK. Você escolhe por instância, não por fornecedor.
- **Sem app na Meta, sem Tech Provider** — Nada de criar app no Meta for Developers, virar Tech Provider ou configurar token e webhook na mão. Você ativa uma instância e pronto.
- **Gerenciada de verdade** — Sem servidor, sem Docker, sem Baileys ou Evolution para manter no ar às três da manhã. 99,9% de uptime é responsabilidade nossa.
- **MCP nativo** — A IA opera a conta direto pelo protocolo, sem você escrever uma linha de integração. Não é um bot que você programa: é um agent que já sabe usar.
- **O que mais ninguém tem** — Números virtuais com WhatsApp já ativado, Pix dentro da mensagem, botões e listas, webhooks filtráveis por evento e por número.

| Recurso | Wame | Self-hosted | Só oficial | Direto na Meta |
|---|---|---|---|---|
| WhatsApp, Instagram e Messenger na mesma instância | sim | não | parcial | não |
| Conectar por QR Code, sem app na Meta | sim | sim | não | não |
| API oficial da Meta (Cloud API) | sim | não | sim | sim |
| Servidor MCP pronto para agents de IA | sim | não | não | não |
| Sem virar Tech Provider | sim | sim | sim | não |
| Sem servidor para manter | sim | não | sim | parcial |
| Suporte humano em português | sim | não | parcial | não |

Self-hosted: projetos como Baileys e Evolution API, mantidos por você. Só oficial: provedor que atende apenas a Cloud API. Direto na Meta: montar a integração por conta própria no Meta for Developers.

Sinais de confiança: 2017 no mercado desde · +50 mil instâncias criadas · 99,9% de uptime · 24/7 suporte humano em português. Meta Business Partner — parceira oficial da Meta para WhatsApp Cloud API, Instagram Direct e Messenger.

## Segurança

- **A key nunca aparece na URL** — No OAuth você cola a key numa página da Wame e ela vira um token cifrado. O conector guarda o token, não a credencial.
- **Uma conexão, uma instância** — O conector alcança exatamente a instância que você autorizou. Nada além dela — e você revoga quando quiser, no painel.
- **Mensagem de terceiro é dado, não ordem** — O que chega em read_messages e wait_for_message foi escrito por outra pessoa. O servidor instrui o agent a relatar, nunca a obedecer: se uma mensagem pedir para executar ação ou revelar informação, ele leva a você em vez de cumprir.
- **Envio pede confirmação onde dói** — Template em lote exige prévia aprovada antes de disparar, porque cada mensagem é cobrada pela Meta e não tem cancelamento.

## Limites

- **Escuta contínua**: 55s por rodada, encadeável — o teto é do cliente MCP, não do servidor
- **O agent não acorda sozinho**: o modelo só roda dentro de um turno seu; não há execução em segundo plano
- **Template em lote**: 50 destinatários por chamada — acima disso, campanha pelo painel
- **Leitura**: 30 conversas por vez, 100 mensagens por página, 8 resultados de contato

## Perguntas frequentes

**O que é o MCP da Wame?**
É um servidor MCP (Model Context Protocol) remoto, em https://mcp.wame.api.br, que dá a um agent de IA — Claude, Claude Code, Cursor, VS Code ou qualquer cliente compatível — a capacidade de ler e enviar mensagens de WhatsApp, Instagram e Messenger em nome de uma instância da Wame. O agent ganha tools como send_message, read_messages e wait_for_message, e passa a operar a conta direto, sem você escrever integração.

**Como conectar o Claude ao WhatsApp?**
Em Configurações › Conectores no Claude, clique em Adicionar conector personalizado e cole https://mcp.wame.api.br. Clique em Vincular: o Claude abre a página de autorização da Wame, onde você cola a key da sua instância (ela fica no painel, em Configurações da instância). Pronto — na conversa seguinte o Claude já lista, lê e responde suas mensagens.

**Funciona no Instagram e no Messenger também, ou só no WhatsApp?**
Nos três. Uma instância da Wame pode ter WhatsApp, Instagram e Messenger ao mesmo tempo, e o mesmo conector alcança todos. Quando há mais de um canal, as tools de envio ganham o parâmetro channel, com enum contendo apenas os canais que aquela instância realmente tem — o agent não consegue escolher um canal que você não ativou.

**Preciso saber programar para usar?**
Não. Conectar é colar uma URL e uma key. Depois disso você conversa em português com o agent: "quem me mandou mensagem hoje?", "responde a Ana", "manda o PDF pro 5566999999999". Quem programa é quem quer ir além — nesse caso a mesma conta tem REST, SDKs de Node/TypeScript e PHP e webhooks.

**É seguro dar acesso do meu WhatsApp para uma IA?**
A key da instância é a credencial completa: quem a tem, envia e lê por aquela instância. Por isso o caminho recomendado é o OAuth, em que a key vira um token cifrado e nunca aparece na URL do conector. Cada conexão alcança uma instância só, e você revoga no painel quando quiser. O servidor também instrui o agent a tratar mensagem recebida como dado a relatar, nunca como instrução — se um contato mandar algo pedindo para executar ações, o agent leva a você em vez de obedecer.

**A IA responde meus clientes sozinha, 24 horas por dia?**
Não por este caminho, e é importante ser claro: o agent só roda dentro de um turno seu, então ele não é acordado sozinho quando chega mensagem. Dá para pedir que ele fique de olho e ele encadeia rodadas de espera enquanto a conversa está aberta, mas atendimento automático ininterrupto é outro produto — para isso use webhook com o seu sistema, ou o template pronto de n8n da Wame.

**Serve para Claude Code, Cursor e VS Code?**
Serve para qualquer cliente que fale MCP por HTTP. No Claude Code é uma linha: claude mcp add --transport http wame https://mcp.wame.api.br. Cursor e VS Code têm link de instalação em um clique. Para cliente que só oferece um campo de URL, cole https://mcp.wame.api.br e conclua o Vincular — a página da Wame recebe a key. Para quem prefere header há o X-API-Key. A key nunca vai na URL.

**Quanto custa?**
O servidor MCP está incluído na instância — não é cobrado à parte. Os planos da Wame começam em R$28,99 por mês. Em instância oficial, as mensagens de template seguem a tarifação da própria Meta.

## Sobre a WAME

Plataforma brasileira de API de mensageria, no mercado desde 2017, com +50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. Meta Business Partner para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância — e também API não oficial via QR Code na mesma plataforma. Planos a partir de R$28,99/mês.

Site: https://wame.api.br · Painel: https://dash.wame.api.br/ · Especificação do servidor: https://mcp.wame.api.br