> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/pt-br/agent-setup/prompt). 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 theme={null}
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 theme={null}
{
  "mcpServers": {
    "polymorfa": {
      "url": "https://api.polymorfa.com/mcp",
      "headers": {
        "Authorization": "Bearer ${POLYMORFA_TOKEN}"
      }
    }
  }
}
```

> [!WARNING]
>
> 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:

| 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](#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](#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](#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](#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](#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](/api/overview).

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](/pt-br/integrations/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](/api/events) e de
[entregas de webhook](/api/webhooks) 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.

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](/pt-br/guides/messaging/message-history).
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](/api/overview). 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](/pt-br/guides/campaigns/send-a-campaign#exija-aprovação-para-envios-grandes)
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](/api/operations) 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](/api/operations#cancel-an-operation), 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:

| 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](https://www.rfc-editor.org/rfc/rfc9727) 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.

## Próximos passos

> **[Autenticação](/api/authentication)**
>
> Escolha uma credencial de equipe, de projeto ou de cliente.

> **[Referência da API](/api/overview)**
>
> Inspecione as operações e os schemas exatos por trás das ferramentas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.