MCP
Ligar uma IA (Claude, Cursor, n8n) a um número de WhatsApp pelo servidor MCP do número.
Cada número da sua API é também um servidor MCP (Model Context Protocol, o protocolo aberto para ligar uma IA a ferramentas). Uma IA de fora, como Claude, Cursor ou n8n, se liga nele e usa o WhatsApp como ferramenta: manda mensagem, lê conversas e procura contatos.
O MCP não é um caminho novo de envio. Cada ferramenta chama, por dentro, a rota REST do mesmo número com a mesma chave. Por isso valem o mesmo limite do plano, a mesma contagem do mês e o mesmo bloqueio de conta suspensa.
Endereço e chave
POST $API_URL/api/v1/instances/<id do número>/mcp
Authorization: Bearer <chave>- Chave do número: abre só o MCP daquele número.
- Chave de API (
wck_...) com o escopo Números: abre o MCP dos números da lista dela. Um número fora da lista, ou uma chave sem esse escopo, responde403CLIENT_KEY_SCOPE. As regras da chave valem em cada ferramenta. - Chave de outro número, chave errada ou sem chave:
401, e nenhuma ferramenta roda. - Número removido:
410INSTANCE_REMOVED.
O transporte é o Streamable HTTP, sem sessão: cada POST leva uma mensagem JSON-RPC e a resposta vem em JSON. GET e DELETE respondem 405. O servidor aceita as versões do protocolo de 2025-03-26 a 2026-07-28.
Ferramentas
| Ferramenta | Entrada | Faz | Conta no plano |
|---|---|---|---|
send_text | to, body | Envia texto. | Sim: uma mensagem do mês; uma conversa nova pede vaga no limite de conversas. |
send_media | to, type (image, video, audio, document), url, caption opcional | Envia mídia baixada da URL, até 64 MB. | Sim, como o send_text. |
list_chats | — | Lista as conversas do número. | Não. |
get_messages | chat opcional (telefone), search opcional, limit (padrão 50, até 200) | Mensagens gravadas, das mais novas para as mais velhas. | Não. |
list_contacts | limit (padrão 100, até 1.000) | Contatos do número. | Não. |
get_contact | phone | Um contato pelo telefone. | Não. |
get_number_status | — | Status da conexão, telefone e contadores, sem a chave do número. | Não. |
- Telefones com o código do país, só dígitos:
5511999990000. - No
get_messagescomchat, o filtro também procura os dígitos no texto: uma mensagem de outra conversa que tenha esses dígitos também aparece. - A resposta de uma ferramenta é o JSON da rota REST, como texto.
- Um erro volta como resultado com
isError: true, no formatoHTTP <status> (<code>[: <limite>]): <frase>. Por exemplo:HTTP 403 (plan_limit: max_messages_per_month): Plan limit reached: max_messages_per_month.
Com a conta suspensa ou cancelada, os envios dão ACCOUNT_SUSPENDED, e as leituras continuam. No limite de requisições, cada chamada de ferramenta conta uma vez só.
Como ligar
Troque <sua-api>, <id> e <chave> pelos valores do número. Os nomes dos campos podem mudar entre versões de cada programa; confira na tela dele.
Claude Desktop, no claude_desktop_config.json, com o mcp-remote levando o cabeçalho:
{
"mcpServers": {
"whatsapp": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://<sua-api>/api/v1/instances/<id>/mcp",
"--header", "Authorization: Bearer ${API_KEY}"
],
"env": { "API_KEY": "<chave>" }
}
}
}Cursor, no ~/.cursor/mcp.json (ou .cursor/mcp.json no projeto):
{
"mcpServers": {
"whatsapp": {
"url": "https://<sua-api>/api/v1/instances/<id>/mcp",
"headers": { "Authorization": "Bearer <chave>" }
}
}
}n8n, no nó MCP Client Tool de um agente:
- Endpoint:
https://<sua-api>/api/v1/instances/<id>/mcp - Server Transport: HTTP Streamable
- Authentication: Header Auth, com o nome
Authorizatione o valorBearer <chave> - Tools to Include: todas, ou só as de leitura
ChatGPT: em Configurações > Conectores (modo desenvolvedor), crie um conector MCP com a URL acima. Se a tela só oferecer OAuth ou "sem autenticação", o ChatGPT não consegue mandar a chave no cabeçalho, e este servidor (só chave) não serve para ele direto. Use um intermediário que ponha o cabeçalho, como o mcp-remote.
Teste rápido
Com o inspector oficial do MCP, liste as ferramentas:
npx @modelcontextprotocol/inspector --cli \
"$API_URL/api/v1/instances/<id>/mcp" --transport http \
--header "Authorization: Bearer $API_KEY" --method tools/list