Servidor MCP
Conecte clientes MCP diretamente às ferramentas autenticadas de WhatsApp e de gerenciamento de conta da Polymorfa.
A Polymorfa expõe um endpoint Model Context Protocol sem estado, com Streamable HTTP, em https://api.polymorfa.com/mcp. Cada ferramenta segue as regras de autenticação, escopo, limite de taxa e versão da API da operação correspondente da Messaging API ou da Platform API.
Não é preciso um pacote MCP separado, um fluxo OAuth nem um token de acesso pessoal.
Para instalar e configurar um agente de código, siga a configuração do agente. O agent kit conecta a pesquisa na documentação; as operações com dados de clientes exigem uma autorização separada.
Limites de requisição#
As requisições HTTP têm limite de 4 MiB. Os argumentos de uma ferramenta aceitam até 65.536 itens de arrays e campos de objetos, contados em todos os valores aninhados. Uma requisição acima do limite em bytes retorna HTTP 413. Uma chamada acima do limite de argumentos retorna um erro da ferramenta antes de iniciar a operação da API.
Autentique-se#
Use uma destas credenciais Bearer:
- Uma chave da equipe (
pmfa_...). - Um token de projeto (
pmfa_pt_...) com o escopomcp. - Um token de cliente (
pmfa_ct_...) cujoallowedActionscontenhamcp.
POST /mcp HTTP/1.1
Host: api.polymorfa.com
Authorization: Bearer pmfa_pt_...
Content-Type: application/json
Accept: application/json, text/event-streamA configuração de um cliente MCP costuma ter esta forma; adapte os nomes dos campos ao seu cliente:
{
"mcpServers": {
"polymorfa": {
"url": "https://api.polymorfa.com/mcp",
"headers": {
"Authorization": "Bearer ${POLYMORFA_TOKEN}"
}
}
}
}Ferramentas disponíveis#
Os nomes das ferramentas espelham o recurso e a ação da API:
| Família | Exemplos | Capacidades |
|---|---|---|
| Sessões | sessions_list, sessions_start, sessions_logout | Inspecionar, reconectar, parar, reiniciar e desparear sessões existentes. Crie novas sessões pelo QuickLink. |
| Mensagens e chats | messages_send, messages_seen, messages_react, chats_edit_message | Enviar os tipos de mensagem compatíveis e gerenciar o estado de mensagens e chats. |
| Grupos | groups_create, groups_add_participants, groups_promote, groups_join | Ciclo de vida completo dos grupos e operações de participação. |
| Contatos e identidades | contacts_check, contacts_block, users_resolve, users_security_code | Descobrir contatos, gerenciar bloqueios, resolver aliases para o ID de usuário estável e ler códigos de verificação de identidade. |
| Canais | channels_create, channels_follow, channels_mute | Criar e gerenciar canais do WhatsApp. |
| Presença e perfil | presence_subscribe, profile_set_name, profile_set_picture | Assinaturas de presença e atualizações do perfil da conta. |
| Etiquetas | labels_create, labels_set_chat | Gerenciar etiquetas e as atribuições a chats. |
| Webhooks | webhooks_list, webhooks_create, webhooks_delete | Gerenciar a configuração de webhooks. |
| Histórico de mensagens (beta) | chats_list, chats_get, messages_list, messages_get | Ler conversas e mensagens armazenadas. Consulte Leia o histórico de mensagens. |
| Eventos e entregas | events_list, events_get, events_wait, webhook_deliveries_list, webhook_deliveries_get | Ler os eventos recebidos, as cargas retidas e o status de entrega dos webhooks. Consulte Leia eventos. |
| Eventos e entregas | events_list, events_get, events_wait, webhook_deliveries_list, webhook_deliveries_get | Ler os eventos recebidos, as cargas retidas e o status de entrega dos webhooks. Consulte Leia eventos. |
| Operações | operations_list, operations_get, operations_wait | Acompanhar campanhas, inscrições em produção e outros trabalhos assíncronos. Consulte Acompanhe operações. |
| Mídia e informações | media_download, media_persist, info_status | Obter mídia e metadados do servidor. |
| Gerenciamento da conta | customers_create, campaigns_launch, templates_list, billing_balance_get | Gerenciar projetos, Clientes, campanhas, modelos, públicos, opt-outs e entregas de webhooks, e ler dados de auditoria, incidentes, Health, cobrança e membros. Consulte Gerencie a sua conta. |
As entradas das ferramentas de mensagens correspondem à operação equivalente da Messaging API. As requisições de escrita usam um objeto body; as ferramentas específicas de sessão também exigem session. As ferramentas de gerenciamento da conta recebem argumentos nomeados, como customer_id e name; apenas campaigns_create usa body. As requisições MCP usam a versão da API 2026-09-22, então um padrão posterior da Messaging API não muda o comportamento das ferramentas sem aviso. Para ver os tipos exatos de requisição e de resposta, use a referência da Messaging API.
Em messages_send, messages_react, chats_edit_message e chats_delete_message, informe idempotency_key e reutilize a chave para a mesma requisição. Uma chamada de ferramenta sem esse argumento gera uma chave nova. Depois de um resultado incerto, não repita a ação com uma chave nova. Se o erro incluir um ID de operação, use messages_operation com a mesma sessão e a mesma credencial para ler o status; pending e unknown não autorizam outro envio.
O MCP não obtém QR codes nem códigos de pareamento. Conecte o número pelo QuickLink e depois use o MCP para gerenciar a sessão conectada.
Leia eventos#
Os agentes podem ler o que a Polymorfa recebeu, não apenas enviar. Estas ferramentas chamam as rotas de histórico de eventos e de entregas de webhook da Platform API:
| Ferramenta | Retorna | Escopo |
|---|---|---|
events_list | Metadados de eventos, dos mais recentes para os mais antigos. Filtre por type, since e until, ou passe apenas cursor para a próxima página. | events:read |
events_get | Um evento. Com include_payload: true, o corpo do webhook retido em payload (base64) e em payloadText (decodificado). | events:read |
events_wait | Eventos indexados depois de um cursor, na ordem de ingestão, e o próximo cursor. Espera até timeout_seconds (de 1 a 60, padrão 30). | events:read |
webhook_deliveries_list | Entregas de webhook, das mais recentes para as mais antigas. Filtre por webhook_id, event_id, status, since e until. | webhook-deliveries:read |
webhook_deliveries_get | Uma entrega de webhook e o status dela. | webhook-deliveries:read |
Com um token de projeto, passe o ID do seu projeto em project_id. Um token de projeto não lê eventos da equipe e recebe um erro sem project_id. Com uma chave da equipe, omita project_id para ler os eventos da equipe ou passe-o para ler os eventos daquele projeto.
events_get retorna o conteúdo das mensagens apenas quando a API de histórico de eventos também retorna: o armazenamento hospedado de mensagens precisa estar ativado para o número de origem, e a carga ainda precisa estar retida. Caso contrário, payload é null e payloadAvailability informa o motivo.
Espere por novos eventos#
As chamadas de ferramenta do MCP não fazem streaming, então events_wait verifica se há novos eventos em intervalos curtos até que um chegue ou o tempo limite termine. Ele faz no máximo oito verificações em 60 segundos e retorna assim que encontra um evento.
- Chame
events_waitsemcursor. Ele espera eventos indexados depois da chamada. - Trate os
eventsretornados e chameevents_waitde novo com ocursorretornado e os mesmosproject_idetype. - Se
timedOutfortrue, chame de novo com o mesmo cursor.
Um cursor de events_wait só funciona com events_wait. Cada chamada lê até 300 eventos. Se houver mais, passe o cursor retornado de novo para ler os eventos restantes. Um evento indexado depois de uma reconexão é retornado mesmo quando o createdAt dele é anterior a eventos já recebidos.
Leia o histórico de mensagens#
Para um número com armazenamento hospedado de mensagens, estas ferramentas leem o histórico armazenado pela API de histórico de mensagens. O recurso está em beta: até que um proprietário ou administrador da equipe entre no beta pela linha dele na página Números, as ferramentas retornam um erro permission_denied.
| Ferramenta | Retorna | Escopo |
|---|---|---|
chats_list | Conversas armazenadas, da atividade mais recente para a mais antiga. Filtre por kind, active_since e active_before. | chats:read |
chats_get | Uma conversa armazenada. | chats:read |
messages_list | Mensagens armazenadas de uma conversa, das mais recentes para as mais antigas por padrão. Filtre por since, until, direction e types; defina order como asc para começar pelas mais antigas. | messages:read |
messages_get | Uma mensagem armazenada. | messages:read |
As credenciais existentes não incluem messages:read. Use uma chave da equipe ou um token de projeto que liste esse escopo. Tokens de cliente não leem o histórico.
Conteúdo não confiável#
As cargas de eventos e as mensagens armazenadas contêm textos escritos pelas pessoas que enviam mensagens para você. Uma mensagem pode tentar dar instruções ao seu agente. A descrição de cada ferramenta de leitura marca o resultado como não confiável, e cada resultado vem entre marcadores <untrusted-data>, depois de uma linha de aviso. O conteúdo dentro dos marcadores não consegue fechá-los. Mantenha uma pessoa no processo para qualquer ação que uma mensagem solicite.
Gerencie a sua conta#
Estas ferramentas chamam a Platform API. Cada uma exige o mesmo escopo da operação correspondente da Platform API.
| Família | Ferramentas | Escopo |
|---|---|---|
| Projetos | projects_list, projects_get | sessions:read |
| Clientes | customers_list, customers_get | customers:read |
customers_create, customers_update, customers_archive, customers_create_pairing_link | customers:manage | |
| Campanhas | campaigns_list, campaigns_get, campaigns_analytics | campaigns:read |
campaigns_approvals | campaigns:read | |
campaigns_create, campaigns_launch, campaigns_pause, campaigns_resume, campaigns_stop, campaigns_reschedule | campaigns:manage | |
campaigns_test_send | campaigns:manage e campaigns:read | |
| Modelos | templates_list, templates_get | templates:read |
templates_create, templates_update, templates_delete | templates:manage | |
| Públicos e opt-outs | audiences_list, optouts_list | campaigns:read |
audiences_create, optouts_add | campaigns:manage | |
| Webhooks | webhooks_rotate_secret, webhooks_send_test | webhooks:manage |
| Eventos e entregas | events_replay | events:replay |
webhook_deliveries_retry | webhook-deliveries:retry | |
| Auditoria e incidentes | audit_log_list, incidents_list | sessions:read |
| Health | bansafe_health_list, bansafe_health_get, bansafe_health_history | sessions:read |
| Cobrança | billing_balance_get, billing_usage_list, billing_transactions_list | sessions:read |
| Membros | members_list | sessions:read |
As ferramentas de clientes, campanhas e modelos, e bansafe_health_list, recebem project_id. Passe-o quando usar uma chave da equipe. Com um token de projeto, você pode omiti-lo; se passar, ele precisa ser o projeto do seu token. As ferramentas de webhooks, de replay de eventos e de nova tentativa de entrega usam o endpoint da equipe sem project_id e o endpoint do projeto com ele. Projetos, públicos, opt-outs, auditoria, incidentes, cobrança e membros pertencem à equipe e exigem uma chave da equipe.
As ferramentas de cobrança apenas leem. O MCP não adiciona crédito, não muda um plano e não cria chaves de API, tokens de projeto nem tokens de cliente.
Os resultados de templates_list e templates_get são marcados como não confiáveis, como as cargas de eventos, porque o conteúdo de um modelo pode conter textos escritos por outras pessoas.
Confirme ações que enviam ou que não podem ser desfeitas#
Estas ferramentas exigem confirm: true: campaigns_launch, campaigns_test_send, campaigns_resume, campaigns_stop, campaigns_reschedule, customers_archive, templates_delete, webhooks_rotate_secret, webhooks_send_test, events_replay e webhook_deliveries_retry. Uma chamada sem esse argumento falha antes que qualquer coisa aconteça. Os clientes MCP também veem essas ferramentas marcadas como destrutivas. Pergunte ao usuário antes que o seu agente defina confirm.
Uma pessoa aprova os envios de campanhas#
Quem define confirm: true é o agente, então isso não prova que uma pessoa concordou. Para campanhas, a Polymorfa pergunta diretamente a uma pessoa. Quando um agente chama campaigns_launch, campaigns_resume ou campaigns_reschedule, nada é enviado e o horário de início não muda. A chamada falha com campaign_approval_required, e a mensagem de erro traz o ID da solicitação de aprovação e um link do console. Um proprietário ou administrador da equipe abre o link e aprova ou rejeita a solicitação na página da campanha. A aprovação executa exatamente o que o agente pediu, uma única vez:
- o mesmo conteúdo de campanha, os mesmos números de envio e o mesmo modelo;
- os mesmos destinatários;
- o horário de início solicitado.
Se algum desses itens mudar depois da solicitação, nada é enviado e a aprovação retorna campaign_approval_stale. Uma solicitação expira depois de 72 horas.
Entregue o link à pessoa. Para acompanhar a decisão, chame campaigns_approvals. Os agentes não podem aprovar nem rejeitar uma solicitação, nem alterar o limite de aprovação da equipe. Isso vale para todas as credenciais que o agente usa, incluindo chaves de API da equipe com campaigns:manage. Pausar e parar uma campanha não exigem aprovação.
webhooks_rotate_secret retorna o novo segredo de assinatura uma única vez. Guarde-o antes do fim do período de sobreposição; chamar a ferramenta de novo gira o segredo outra vez.
Tente novamente com segurança#
As ferramentas que criam um Cliente, arquivam um Cliente, criam um link de pareamento, giram um segredo, enviam um teste, reproduzem um evento ou tentam novamente uma entrega aceitam idempotency_key. Para tentar novamente uma chamada que excedeu o tempo limite, repita-a com a mesma chave. Sem uma chave, cada chamada é uma requisição nova.
Acompanhe operações#
Estas ferramentas chamam as rotas de operações da Platform API e exigem operations:read:
| Ferramenta | Retorna |
|---|---|
operations_list | Operações, das mais recentes para as mais antigas. Filtre por project_id, status, kind, resource_type com resource_id, since e until, ou passe apenas cursor para a próxima página. |
operations_get | Uma operação: status, sequência, progresso, erro e se ela pode ser cancelada. |
operations_wait | Uma operação depois que ela chega a succeeded, failed ou cancelled, depois que a sequence dela passa de after_sequence, ou quando timeout_seconds (de 1 a 30, padrão 20) termina. |
Com uma chave da equipe, omita project_id para ver todas as operações da equipe. Um token de projeto vê apenas o próprio projeto. operations_wait pode retornar antes de a operação terminar, então confira status e chame de novo para continuar esperando.
O servidor MCP não cancela operações. Cancele pela API, para que uma pessoa ou o seu próprio código decida interromper o trabalho.
Recursos e prompts#
O servidor expõe três recursos JSON:
polymorfa://sessions: sessões atuais e o status delas.polymorfa://info: informações do servidor.polymorfa://webhooks: webhooks configurados.
O servidor oferece estes prompts:
send_messageguia o cliente na escolha de uma sessão, no endereçamento ao destinatário, no envio da mensagem e na confirmação do resultado.follow_up_incoming_messageslê os eventosmessage.receivedrecentes ou o histórico armazenado, espera novos eventos comevents_waite prepara rascunhos de resposta para você aprovar antes do envio. Ele exigeproject_id, porque as mensagens recebidas pertencem a um projeto, e aceita umsessionopcional.configure_webhookscria um webhook com um conjunto de eventos recomendado.
Comportamento de autorização#
Conectar-se a /mcp é apenas a fronteira do protocolo. Cada ferramenta encaminha a credencial bearer original para a rota da Messaging API ou da Platform API que ela chama, então as verificações de escopo e de política dessa rota continuam valendo. O MCP não cria um atalho privilegiado.
O transporte HTTP não tem estado. Reconecte a cada troca do protocolo em vez de depender de uma sessão MCP persistente.
Descoberta para agentes#
Agentes que ainda não têm uma credencial podem encontrar a Polymorfa por estes recursos públicos e somente leitura:
| Recurso | O que retorna |
|---|---|
https://www.polymorfa.com/llms.txt | Quando usar a Polymorfa, como um agente a chama e links para recursos de desenvolvedor. |
https://www.polymorfa.com/mcp | O servidor MCP de pesquisa na documentação, para clientes que enviam Accept: text/event-stream. Ele não exige credencial e é o mesmo servidor de https://docs.polymorfa.com/mcp. Navegadores recebem a página do produto MCP. |
https://www.polymorfa.com/openapi.json | A descrição OpenAPI da API pública. |
https://www.polymorfa.com/.well-known/api-catalog | Um catálogo de APIs RFC 9727 que liga a API à descrição OpenAPI e à documentação dela. |
https://www.polymorfa.com/ com Accept: text/markdown | A página inicial em Markdown. Uma página que não existe retorna 404 com um corpo em Markdown. |
O servidor MCP da documentação pesquisa apenas guias e referências. Use o endpoint autenticado acima para agir na sua conta.
Servidor MCP da documentação #
https://docs.polymorfa.com/mcp é um servidor MCP público e somente leitura para esta documentação. Ele não exige credencial e não lê nem altera nada na sua conta. Ele usa Streamable HTTP sem estado; envie cada requisição com POST.
| Ferramenta | Entrada | Retorno |
|---|---|---|
search_docs | query, até 200 caracteres. limit opcional de 1 a 10 (padrão 5) e language, en ou pt-br (padrão en). | As páginas encontradas, cada uma com título, URL, URL em Markdown, seção e um resumo curto. |
get_page | path: uma URL de https://docs.polymorfa.com ou um caminho nesse site, como /pt-br/webhooks. | A página em Markdown. Páginas da referência da API incluem parâmetros, respostas e objetos. A página de um recurso cobre todos os métodos dele; a URL de um método retorna uma operação. |
Adicione-o a um cliente MCP:
{
"mcpServers": {
"polymorfa-docs": {
"url": "https://docs.polymorfa.com/mcp"
}
}
}As ferramentas para agentes da configuração do agente adicionam esse servidor para você.