Nexxa WhatsApp MCP

Um servidor Model Context Protocol que permite a agentes de IA (Claude, ChatGPT, n8n, agentes próprios) enviar mensagens de WhatsApp e consultar dados da sua conta Nexxa — com segurança e isolados por tenant.

Visão geral

O MCP da Nexxa expõe um conjunto de tools que um agente pode chamar para operar o WhatsApp em nome da sua conta. Toda chamada é autenticada e restrita ao seu tenant: um token só enxerga e opera instâncias, chats, campanhas e clientes da própria conta.

Endpoint

O servidor usa o transporte Streamable HTTP do MCP. Aponte seu client para:

https://mcp.nexxa.one/mcp

Conectar um client

Qualquer client compatível com MCP via HTTP funciona. Você precisa de uma credencial (veja Autenticação): use uma API Key para integrações simples por header ou um Client MCP OAuth para conectores remotos como Claude.

Claude Desktop / Claude.ai (conector remoto)

Adicione um conector remoto apontando para o endpoint acima. O Claude descobre o fluxo de login automaticamente pelos metadados /.well-known/oauth-protected-resource servidos por este host e conduz você pelo OAuth.

Client genérico via header (API key ou token)

Se o seu client permite definir headers, basta enviar o Authorization em cada requisição:

{
  "mcpServers": {
    "nexxa-whatsapp": {
      "url": "https://mcp.nexxa.one/mcp",
      "headers": {
        "Authorization": "ApiKey SUA_API_KEY"
      }
    }
  }
}

Autenticação

Toda requisição ao endpoint /mcp exige um header Authorization. Três formatos são aceitos:

Sem header válido o servidor responde 401 Unauthorized e anuncia o servidor de autorização no header WWW-Authenticate, permitindo que clients compatíveis iniciem o login sozinhos.

Gerar credenciais no painel

Acesse diretamente https://app.nexxa.one/settings/credentials ou siga o caminho abaixo no painel:

Na tela de credenciais, escolha a aba conforme o tipo de integração:

• API Keys: use quando o client MCP permite enviar Authorization: ApiKey <api_key>.
• Clients MCP (OAuth): use para conectores remotos que pedem client_id e client_secret, como Claude.

Para criar um Client MCP OAuth, abra a aba Clients MCP (OAuth), clique em Novo Client, escolha o tipo do client, preencha as informações solicitadas e salve. O client_secret é exibido apenas uma vez; guarde-o antes de fechar a tela.

Scopes

As permissões de um token são controladas por scopes:

Um token só com mcp:read consegue consultar dados, mas não enviar mensagens. Para um agente que apenas dispara mensagens, conceda ambos.

Fluxo recomendado

Um agente normalmente segue esta sequência. As tools são desenhadas para serem encadeadas:

1. listar_instancias            → descobrir o instance_id da conexão WhatsApp
2. listar_templates_meta        → (envio oficial) ver templates aprovados na Meta
3. get_meta_template_message_guide → (opcional) aprender a montar "components"
4. send_text_message | send_template_message | ... → enviar

Tools disponíveis

Envio de mensagens mcp:message:send

Todas as tools de envio aceitam ainda delay (segundos antes do envio) e campaign_id (rastreamento) opcionais.

WhatsApp Flows mcp:message:send

Use publish=false para criar como rascunho. A tool respeita a allowlist de instâncias configurada na API Key ou no Client OAuth.

Consultas mcp:read

Guia para agentes mcp:read

get_meta_template_message_guide não envia nada e não altera dados — retorna exemplos de como montar o payload de send_template_message. Aceita o argumento opcional topic: overview, body, media_header, buttons ou examples.

Exemplo — enviar texto

{
  "name": "send_text_message",
  "arguments": {
    "instance_id": "inst_123",
    "phone_to": "5511999999999",
    "text": "Olá, tudo bem?"
  }
}

Resposta de sucesso (texto JSON):

{ "success": true, "message_id": "...", "message": "Message sent successfully" }

Templates oficiais (Meta Cloud API)

Para contas oficiais (Cloud API), mensagens fora da janela de 24h exigem um template aprovado pela Meta. Use send_template_message. Requisitos:

• instance_id deve ser de uma instância oficial/Cloud API já conectada;
• template_name deve existir e estar aprovado na Meta (consulte com listar_templates_meta);
• language_code deve bater com o idioma aprovado (padrão pt_BR quando omitido);
• components segue o formato da Meta Cloud API.

Exemplo — template com variáveis no body

{
  "name": "send_template_message",
  "arguments": {
    "instance_id": "inst_123",
    "phone_to": "5511999999999",
    "template_name": "aviso_pagamento",
    "language_code": "pt_BR",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Maria" },
          { "type": "text", "text": "R$ 199,90" }
        ]
      }
    ]
  }
}

Exemplo — header com documento (PDF)

{
  "name": "send_template_message",
  "arguments": {
    "instance_id": "inst_123",
    "phone_to": "5511999999999",
    "template_name": "fatura_pdf",
    "language_code": "pt_BR",
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "document", "document": { "link": "https://exemplo.com/fatura.pdf", "filename": "Fatura.pdf" } }
        ]
      },
      { "type": "body", "parameters": [ { "type": "text", "text": "Maria" } ] }
    ]
  }
}

Erros comuns

OAuth para clients remotos

Clients como o Claude usam OAuth automaticamente. O servidor publica os metadados padrão neste host:

GET  https://mcp.nexxa.one/.well-known/oauth-protected-resource
GET  https://mcp.nexxa.one/.well-known/oauth-authorization-server
GET  https://mcp.nexxa.one/authorize        (alias: /oauth/authorize)
POST https://mcp.nexxa.one/token            (alias: /oauth/token)

Suporta authorization_code com PKCE (plain e S256) e client_credentials para agentes headless. O token emitido fica preso ao tenant do client OAuth.

Agente headless — client_credentials

POST https://mcp.nexxa.one/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials&scope=mcp:read mcp:message:send&resource=https://mcp.nexxa.one/mcp

A resposta traz um access_token (válido por 1h) que você usa como Authorization: Bearer <access_token> nas chamadas ao /mcp.

Limites e escopo

Além da criação de WhatsApp Flows, o MCP não cria nem altera outros recursos estruturais. As seguintes operações não são expostas como tools:

• criar/atualizar instância e conectar WABA manualmente;
• ativar/desativar painel de atendimento ou configurar IA;
• criar/atualizar/pausar campanhas;
• criar/atualizar listas de contato, clientes ou apps;
• criar template na Meta/WABA;
• criar/atualizar configurações de cobrança.

A instância oficial precisa existir e estar conectada antes de qualquer envio. Para descobrir o que está disponível na sua conta, use as tools listar_*.