Ir para o conteúdo

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

text
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, responde 403 CLIENT_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: 410 INSTANCE_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

FerramentaEntradaFazConta no plano
send_textto, bodyEnvia texto.Sim: uma mensagem do mês; uma conversa nova pede vaga no limite de conversas.
send_mediato, type (image, video, audio, document), url, caption opcionalEnvia mídia baixada da URL, até 64 MB.Sim, como o send_text.
list_chats—Lista as conversas do número.Não.
get_messageschat opcional (telefone), search opcional, limit (padrão 50, até 200)Mensagens gravadas, das mais novas para as mais velhas.Não.
list_contactslimit (padrão 100, até 1.000)Contatos do número.Não.
get_contactphoneUm 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_messages com chat, 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 formato HTTP <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:

json
{
  "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):

json
{
  "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 Authorization e o valor Bearer <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:

bash
npx @modelcontextprotocol/inspector --cli \
  "$API_URL/api/v1/instances/<id>/mcp" --transport http \
  --header "Authorization: Bearer $API_KEY" --method tools/list
A IA ligada ao MCP manda mensagens em nome do número. Dê a ela uma chave de API só com os números que ela deve usar, e revogue a chave quando a ligação não for mais necessária.