Servidor MCP

O Pingo Notify fala MCP (Model Context Protocol), então um assistente de IA pode operar um workspace direto: listar conexões, enviar mensagens de WhatsApp, ler uma conversa, gerenciar webhooks. Você aprova o que ele pode fazer uma vez, numa tela de consentimento, e ele nunca manuseia um token de API.

Conectar

Adicione uma URL ao cliente, como conector customizado ou remoto:

https://api.pingonotify.com/v3/mcp

Tudo depois disso é o protocolo fazendo o trabalho dele:

Conectar não exige plano nenhum, e continua funcionando com assinatura expirada — mas enviar não. Veja Limites.

O que o assistente recebe

Um workspace, fixado no consentimento

Tudo que o assistente enxerga pertence ao workspace que você escolheu ao autorizar. Não há ferramenta para trocar de workspace nem header que ele possa mandar para mudar isso: uma requisição que tentar recebe 403 — This access token is bound to a different workspace; re-authorize to switch. Um segundo workspace significa uma segunda autorização.

Escopo é teto, nunca concessão

A permissão efetiva de um token é a interseção entre os escopos que você aprovou e o que você pode fazer naquele workspace. Aprovar messages:send não deixa um assistente enviar se o seu próprio papel não pode; escopo só estreita.

Você pode sempre aprovar menos do que foi pedido. Reaprovar com menos escopos revoga os tokens já emitidos para aquela integração, para que a tela e a realidade nunca discordem.

Ele conhece o próprio limite antes de tentar

O handshake carrega um parágrafo montado para aquele token: as ferramentas que este acesso pode usar e, pelo nome, as que não pode. Um assistente que já sabe que lhe falta webhooks:write avisa você em vez de gastar um turno descobrindo.

Ferramenta fora de escopo continua listada de propósito. Esconder trocaria uma recusa que diz qual escopo pedir por um inútil "ferramenta desconhecida".

As ferramentas

Vinte e três ferramentas. O corte é por domínio, não por rota — o helpdesk está fora por decisão de produto.

Orientação

Comece por list_connections, sempre. Toda outra ferramenta precisa de um connectionId, e é ela que revela o tipo da conexão — que decide se uma ferramenta de envio funciona. Ela também informa canSend, verdadeiro só enquanto a conexão está open.

check_whatsapp_number aceita até 50 números por chamada e devolve o id canônico de cada um. get_workspace conta ao assistente quais escopos ele de fato tem.

Mensageria

Há uma ferramenta por forma de mensagem, em vez de uma ferramenta com um campo type. Um único schema com sete ramos opcionais deixa o modelo montar uma combinação que o WhatsApp recusa — e esse erro chega depois de o envio ter sido cobrado.

Webhooks

Regras que falham em silêncio

Vale ler antes de soltar um assistente: ignorar estas não produz erro nenhum, só um resultado que ninguém recebe.

• Conexão oficial alimenta menos o webhook. Mensagens recebidas (messages.upsert) e atualizações de entrega (messages.update) chegam sim; send.message, messages.delete, messages.edited, presence.update e connection.update nunca chegam. Inscrever-se nesses numa conexão oficial produz silêncio, não recusa.
• Dois eventos são aceitos no cadastro e nunca entregues em conexão nenhuma: connection.update e presence.update. O list_webhook_event_types carrega essa verdade por evento, e é por isso que o assistente deve chamá-lo antes de criar uma inscrição. Para status de conexão, faça polling em list_connections.
• Webhook sem conexão vinculada nunca dispara. O create_webhook exige pelo menos um id de conexão — passe todos se você quer o workspace inteiro. O webhook nasce ativo e o list_webhook_deliveries volta vazio, o que se lê exatamente como "evento errado".
• Seu endpoint vai ver o mesmo evento mais de uma vez. A entrega estoura em 10 segundos e é retentada até três vezes, com uma linha registrada por tentativa. Faça o endpoint idempotente; um endpoint que responde em mais de 10 segundos garante duplicatas.
• Telefone vai no formato internacional, só dígitos — 5511999998888, sem +, sem espaço, sem pontuação. Para um número que você nunca mandou mensagem, rode check_whatsapp_number primeiro e envie o id canônico que ele devolve, não o que a pessoa digitou.
• Mídia já hospedada vai por URL pública https; arquivo local vai por upload. Base64 no argumento não é aceito, e não é capricho: quando a imagem chegou ao assistente como imagem, ela não é mais uma string que ele possa recuperar — e quando os bytes existem, escrevê-los consumiria a resposta inteira (1 MB de arquivo são ~1,4 milhão de caracteres). Para um arquivo na máquina do assistente, prepare_media_upload devolve uma URL de upload de uso único: ele sobe o arquivo com um curl -F 'file=@caminho' e o envio acontece nesse mesmo request, sem os bytes passarem pelo contexto. Sem um terminal disponível, a mesma URL serve para você subir o arquivo à mão.
• O tipo da mídia é uma escolha, e o contato vê coisas diferentes. Uma imagem aparece na bolha com a legenda embaixo; um vídeo vira player com miniatura e toca dentro da conversa; um áudio é anexo, com botão de play e o nome do arquivo ao lado; um áudio de voz é a bolha redonda com forma de onda e velocidade 1×/1,5×/2×, que é o que as pessoas querem dizer com "manda um áudio"; um documento é o card com ícone, nome e tamanho, que o contato baixa para abrir. Tudo que não é imagem, vídeo ou áudio só pode ser documento. O assistente declara esse tipo ao pedir a URL de upload (ou no mediatype, quando manda por URL) — ele não é adivinhado pela extensão do arquivo, justamente para um vídeo não chegar como card de arquivo.
• Enviar custa dinheiro do workspace e é irreversível. As instruções do servidor pedem que o assistente confirme com você antes de enviar, a menos que você já tenha pedido aquele envio na conversa.
• download_message_media desiste em silêncio com arquivo grande. Acima de uns 750 KB ele responde sem conteúdo e com uma nota mandando abrir o arquivo no Pingo — um sucesso, não um erro. Um cliente que só checa falha segue adiante de mãos vazias.
• send_whatsapp_template preenche só variáveis posicionais de texto. Um template com parameterFormat: NAMED, com header de mídia ou com botão dinâmico não tem como ser preenchido por esta ferramenta — esse caso é a API HTTP. A Meta recusa o envio inteiro quando nome, idioma ou número de parâmetros não batem.
• delay é em milissegundos e para em 20000. A espera é bloqueante do lado do WhatsApp; valores mais altos estouram a requisição por timeout depois de a mensagem ter sido aceita — erro para o assistente, mensagem entregue para o contato.

Limites

O balde do MCP é chaveado por credencial de propósito. Um cliente MCP remoto não é chamado pelo seu navegador: quem chama é a infraestrutura que hospeda o modelo, de um punhado de IPs de saída. Por IP, um workspace derrubaria o outro.

O que ele não faz, de propósito

Os dois primeiros continuam no painel, onde há uma pessoa.

Quando algo dá errado

Uma ferramenta que falha volta como conteúdo legível, não como exceção de protocolo — então o assistente vê o motivo e consegue corrigir o rumo: pedir outro escopo, avisar você, tentar outra ferramenta. Falhas inesperadas nunca vazam detalhe; a stack e qualquer mensagem de banco ficam no log.

Escrevendo o seu próprio cliente

Se você está escrevendo o cliente em vez de usar um pronto, quatro detalhes poupam uma tarde:

• Peça o grant refresh_token no registro. grant_types omitido significa só authorization_code, e aí nenhum refresh token é emitido — o seu conector para de funcionar uma hora depois e precisa de gente de novo.
• Mande token_endpoint_auth_method: "none" para ser cliente público. Omitir o campo cria um cliente confidencial, que recebe um client_secret mostrado uma única vez e tem de enviá-lo em toda chamada de token.
• A primeira requisição precisa de Accept: application/json, text/event-stream. O transporte do MCP exige, mesmo que este servidor sempre responda JSON.
• O parâmetro resource prende o token a um caminho. Um token emitido para https://api.pingonotify.com/v3/mcp é aceito sob /v3/mcp e recusado com 401 em todo o resto da API. Peça o recurso que você realmente pretende chamar.

prompt=consent força a tela mesmo quando já existe um consentimento vivo que cobre o pedido; prompt=none nunca mostra a tela e responde consent_required ou login_required. Fora disso, uma reautorização pode se completar em silêncio — mas só quando existe exatamente um consentimento que cobre os escopos pedidos e o seu papel ainda permite.