Servidor MCP

Cada instância da OnZap tem um servidor MCP (Model Context Protocol) próprio. Conectado a ele, o seu assistente de IA consulta aquele número de WhatsApp com ferramentas prontas: métricas do atendimento, quem está sem resposta, status da conexão, conversas, a documentação da API e, se você permitir, o envio de mensagens com a sua confirmação.

Endereço   https://mcp.onzap.io/{instanceId}/mcp
Acesso     login na OnZap pelo navegador (OAuth), ou o token da instância

O endereço de cada número está no painel, em Instâncias → (a instância) → Credenciais → Usar com IA (MCP).

Perguntas que funcionam bem:

• "Quantas conversas ficaram sem resposta ontem no número de vendas?"
• "Quem está esperando resposta há mais de uma hora?"
• "Qual foi o tempo médio da primeira resposta nesta semana, separando robô e atendente?"
• "O número caiu nos últimos 7 dias?"
• "Gere o código em PHP para enviar uma imagem por esta instância."

Só a documentação, sem login

Para consultar esta documentação no assistente de programação, sem conta e sem instância, use o servidor MCP público da documentação:

claude mcp add --transport http onzap-docs https://mcp.onzap.io/docs

{
  "mcpServers": {
    "onzap-docs": { "url": "https://mcp.onzap.io/docs" }
  }
}

Ele tem buscar_documentacao, ler_pagina (uma página inteira em Markdown) e gerar_codigo (com SUA_INSTANCIA no lugar do ID). Não acessa nenhuma conta nem número; o limite é de 60 chamadas por minuto por IP.

Conectar um número

Na primeira chamada, o app abre o navegador: você entra na OnZap, vê o app e o número, escolhe as permissões e clica em Permitir acesso. Não é preciso colar token em arquivo nenhum.

Claude Code

claude mcp add --transport http onzap-vendas https://mcp.onzap.io/SUA_INSTANCIA/mcp

Use um nome por número (onzap-vendas, onzap-suporte...) se for conectar mais de um.

Claude (site e app)

No painel, o botão Adicionar ao Claude abre o Claude com o conector já preenchido. Ou adicione um conector personalizado com o endereço do servidor MCP da instância e siga o login pelo navegador.

ChatGPT

Adicione um conector personalizado (modo desenvolvedor) com o endereço do servidor MCP da instância e escolha autenticação OAuth.

Cursor

No painel, o botão Adicionar ao Cursor já instala com o endereço da instância. Ou, em .cursor/mcp.json:

{
  "mcpServers": {
    "onzap-vendas": { "url": "https://mcp.onzap.io/SUA_INSTANCIA/mcp" }
  }
}

VS Code (GitHub Copilot)

No painel, o botão Adicionar ao VS Code. Ou, em .vscode/mcp.json:

{
  "servers": {
    "onzap-vendas": { "type": "http", "url": "https://mcp.onzap.io/SUA_INSTANCIA/mcp" }
  }
}

Windsurf (Devin Desktop)

No mcp_config.json das configurações de MCP do app:

{
  "mcpServers": {
    "onzap-vendas": { "serverUrl": "https://mcp.onzap.io/SUA_INSTANCIA/mcp" }
  }
}

Sem navegador (scripts e CI)

O token da instância também abre o servidor MCP, no header Authorization: Bearer (ou X-Instance-Token), mais o Client-Token se a conta exigir. Quem tiver essa configuração lê as conversas do número: trate como senha.

claude mcp add --transport http onzap-vendas https://mcp.onzap.io/SUA_INSTANCIA/mcp \
  --header "Authorization: Bearer SEU_TOKEN"

Para testar, use o MCP Inspector (npx @modelcontextprotocol/inspector), com o transporte Streamable HTTP e o endereço da instância.

Permissões

Cada autorização vale para um número. O app só enxerga o número do endereço em que foi conectado.

• As três de leitura são pedidas na primeira conexão. As de escrita só aparecem quando o app tenta usar uma ferramenta que precisa delas; nessa hora o navegador abre de novo e a permissão vem desligada, para você ligar se quiser.
• buscar_documentacao e gerar_codigo funcionam com qualquer permissão.
• Com o token da instância, todas as ferramentas ficam liberadas (é o mesmo acesso da API).

Apps conectados. Em Configurações, e nas Credenciais de cada instância, aparecem os apps autorizados, com quem autorizou, o último uso e as últimas ações. Desconectar corta o acesso na hora.

Ferramentas

As ferramentas de leitura são marcadas como só leitura; as de envio, como ações que não se desfazem. Os números vêm calculados e com uma frase-resumo pronta, para o assistente não refazer contas.

Envio com confirmação

Nenhuma mensagem sai sem você confirmar:

• Apps que perguntam no meio da chamada (protocolo 2026-07-28 com elicitation): o app mostra a prévia ("Enviar pela instância Vendas para +55 (11) 99999-0001 a mensagem «...»") e o envio só sai se você marcar Confirmo.
• Os demais: a primeira chamada devolve a prévia e um codigoConfirmacao. O assistente mostra a prévia e só repete a chamada com confirmar: true e o código se você disser que sim.

A confirmação vale 5 minutos, uma vez só e só para aqueles dados: mudar o texto ou o destino exige outra prévia. Criar um webhook novo também pede confirmação, porque os eventos (com o texto das mensagens) passam a ir para a URL.

Modo teste

Todo app autorizado começa em modo teste: só envia para os números de teste da conta, que são os telefones verificados dos usuários e os que você cadastrar em Configurações → Números de teste. A comparação ignora o 9º dígito. Grupos ficam de fora.

Para enviar para qualquer número, desligue o modo teste do app em Apps conectados. Cada envio continua pedindo confirmação.

Limites

Os envios também passam pelos limites, pela fila e pela cobrança da instância, como qualquer chamada da API.

Segurança e privacidade

• O token da instância nunca sai da OnZap: as ferramentas chamam a API por dentro, com a credencial montada no servidor.
• A OnZap não roda IA: quem lê e responde é o assistente que você conectou, na conta que você usa com ele.
• As métricas usam só metadados dos eventos. As ações de escrita ficam registradas sem o conteúdo das mensagens, e as chamadas que o app faz à API aparecem em Atividade da API como "via" o app.

Para quem implementa um cliente MCP