Pular para o conteúdo principal
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.
A configuração de um cliente MCP costuma ter esta forma; adapte os nomes dos campos ao seu cliente:
A credencial dá ao cliente acesso real à Polymorfa. Prefira um token de projeto apenas com os escopos de que o agente precisa. Use um token de cliente quando a integração precisar de ações e limites específicos por sessão.

​
Ferramentas disponíveis

Os nomes das ferramentas espelham o recurso e a ação da API: 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: 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. 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. 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: 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: O servidor MCP da documentação pesquisa apenas guias e referências. Use o endpoint autenticado acima para agir na sua conta.

​
Próximos passos

Autenticação

Escolha uma credencial de equipe, de projeto ou de cliente.

Referência da API

Inspecione as operações e os schemas exatos por trás das ferramentas.