Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

Servidor MCP

Conecte clientes MCP diretamente às ferramentas autenticadas de WhatsApp e de gerenciamento de conta da Polymorfa.

Ver em Markdown

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 escopo mcp.
  • Um token de cliente (pmfa_ct_...) cujo allowedActions contenha mcp.
HTTP
POST /mcp HTTP/1.1
Host: api.polymorfa.com
Authorization: Bearer pmfa_pt_...
Content-Type: application/json
Accept: application/json, text/event-stream

A configuração de um cliente MCP costuma ter esta forma; adapte os nomes dos campos ao seu cliente:

JSON
{
  "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íliaExemplosCapacidades
Sessõessessions_list, sessions_start, sessions_logoutInspecionar, reconectar, parar, reiniciar e desparear sessões existentes. Crie novas sessões pelo QuickLink.
Mensagens e chatsmessages_send, messages_seen, messages_react, chats_edit_messageEnviar os tipos de mensagem compatíveis e gerenciar o estado de mensagens e chats.
Gruposgroups_create, groups_add_participants, groups_promote, groups_joinCiclo de vida completo dos grupos e operações de participação.
Contatos e identidadescontacts_check, contacts_block, users_resolve, users_security_codeDescobrir contatos, gerenciar bloqueios, resolver aliases para o ID de usuário estável e ler códigos de verificação de identidade.
Canaischannels_create, channels_follow, channels_muteCriar e gerenciar canais do WhatsApp.
Presença e perfilpresence_subscribe, profile_set_name, profile_set_pictureAssinaturas de presença e atualizações do perfil da conta.
Etiquetaslabels_create, labels_set_chatGerenciar etiquetas e as atribuições a chats.
Webhookswebhooks_list, webhooks_create, webhooks_deleteGerenciar a configuração de webhooks.
Histórico de mensagens (beta)chats_list, chats_get, messages_list, messages_getLer conversas e mensagens armazenadas. Consulte Leia o histórico de mensagens.
Eventos e entregasevents_list, events_get, events_wait, webhook_deliveries_list, webhook_deliveries_getLer os eventos recebidos, as cargas retidas e o status de entrega dos webhooks. Consulte Leia eventos.
Eventos e entregasevents_list, events_get, events_wait, webhook_deliveries_list, webhook_deliveries_getLer os eventos recebidos, as cargas retidas e o status de entrega dos webhooks. Consulte Leia eventos.
Operaçõesoperations_list, operations_get, operations_waitAcompanhar campanhas, inscrições em produção e outros trabalhos assíncronos. Consulte Acompanhe operações.
Mídia e informaçõesmedia_download, media_persist, info_statusObter mídia e metadados do servidor.
Gerenciamento da contacustomers_create, campaigns_launch, templates_list, billing_balance_getGerenciar 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:

FerramentaRetornaEscopo
events_listMetadados 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_getUm evento. Com include_payload: true, o corpo do webhook retido em payload (base64) e em payloadText (decodificado).events:read
events_waitEventos 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_listEntregas de webhook, das mais recentes para as mais antigas. Filtre por webhook_id, event_id, status, since e until.webhook-deliveries:read
webhook_deliveries_getUma 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.

  1. Chame events_wait sem cursor. Ele espera eventos indexados depois da chamada.
  2. Trate os events retornados e chame events_wait de novo com o cursor retornado e os mesmos project_id e type.
  3. Se timedOut for true, 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.

FerramentaRetornaEscopo
chats_listConversas armazenadas, da atividade mais recente para a mais antiga. Filtre por kind, active_since e active_before.chats:read
chats_getUma conversa armazenada.chats:read
messages_listMensagens 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_getUma 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íliaFerramentasEscopo
Projetosprojects_list, projects_getsessions:read
Clientescustomers_list, customers_getcustomers:read
customers_create, customers_update, customers_archive, customers_create_pairing_linkcustomers:manage
Campanhascampaigns_list, campaigns_get, campaigns_analyticscampaigns:read
campaigns_approvalscampaigns:read
campaigns_create, campaigns_launch, campaigns_pause, campaigns_resume, campaigns_stop, campaigns_reschedulecampaigns:manage
campaigns_test_sendcampaigns:manage e campaigns:read
Modelostemplates_list, templates_gettemplates:read
templates_create, templates_update, templates_deletetemplates:manage
Públicos e opt-outsaudiences_list, optouts_listcampaigns:read
audiences_create, optouts_addcampaigns:manage
Webhookswebhooks_rotate_secret, webhooks_send_testwebhooks:manage
Eventos e entregasevents_replayevents:replay
webhook_deliveries_retrywebhook-deliveries:retry
Auditoria e incidentesaudit_log_list, incidents_listsessions:read
Healthbansafe_health_list, bansafe_health_get, bansafe_health_historysessions:read
Cobrançabilling_balance_get, billing_usage_list, billing_transactions_listsessions:read
Membrosmembers_listsessions: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:

FerramentaRetorna
operations_listOperaçõ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_getUma operação: status, sequência, progresso, erro e se ela pode ser cancelada.
operations_waitUma 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_message guia 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_messages lê os eventos message.received recentes ou o histórico armazenado, espera novos eventos com events_wait e prepara rascunhos de resposta para você aprovar antes do envio. Ele exige project_id, porque as mensagens recebidas pertencem a um projeto, e aceita um session opcional.
  • configure_webhooks cria 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:

RecursoO que retorna
https://www.polymorfa.com/llms.txtQuando usar a Polymorfa, como um agente a chama e links para recursos de desenvolvedor.
https://www.polymorfa.com/mcpO 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.jsonA descrição OpenAPI da API pública.
https://www.polymorfa.com/.well-known/api-catalogUm catálogo de APIs RFC 9727 que liga a API à descrição OpenAPI e à documentação dela.
https://www.polymorfa.com/ com Accept: text/markdownA 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.

FerramentaEntradaRetorno
search_docsquery, 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_pagepath: 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:

JSON
{
  "mcpServers": {
    "polymorfa-docs": {
      "url": "https://docs.polymorfa.com/mcp"
    }
  }
}

As ferramentas para agentes da configuração do agente adicionam esse servidor para você.

Próximos passos#