> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ararahq.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Ferramentas do MCP
> Referência das 9 ferramentas, 4 painéis interativos, 4 resources e 3 prompts do MCP da Arara: o que cada um faz, parâmetros, limites e exemplos.
O MCP tem 3 camadas: **tools** (ações que o agente executa), **resources** (dados que o cliente lê sem tool call) e **prompts** (fluxos prontos). Instalação e autenticação: [MCP Server](/mcp-server). A versão atual é o pacote `@ararahq/mcp` 6.x; mudanças em relação às versões antigas estão no [changelog](/changelog).
São 9 tools de propósito. Agente com painel de controle inteiro erra mais do que agente com poucas ações que aceitam o que uma pessoa sabe de cabeça (um nome, um número em qualquer formato) e resolvem o resto.
| Grupo | Ferramentas |
| - | - |
| Falar com a base | `send_whatsapp` · `broadcast` |
| Ver o que voltou | `campaign_report` · `check_status` · `read_conversation` |
| Preparar | `create_template` · `save_contacts` · `opt_out` |
| Conta | `whoami` |
## Como um destinatário é resolvido
`send_whatsapp`, `broadcast`, `check_status` e `read_conversation` aceitam em `to` um número em qualquer grafia **ou** o nome de um contato salvo.
* **Número:** o MCP remove pontuação e espaços. Número com `+` ou com 12 dígitos ou mais é tratado como já tendo DDI; se for brasileiro (`55`) com 10 dígitos depois do DDI, ganha o nono dígito. Número sem DDI com 10 ou 11 dígitos ganha `+55`. O resultado precisa ser E.164 válido, senão a tool falha com `INVALID_PHONE`.
* **Nome:** o MCP busca nos seus contatos salvos. Nenhum resultado dá `CONTACT_NOT_FOUND`; mais de um dá `CONTACT_AMBIGUOUS` com os candidatos, em vez de chutar.
Busca por nome, `save_contacts` e `read_conversation` usam a base de contatos da Arara, que depende do plano. Em plano sem contatos, a API recusa com `PLAN_FEATURE_LOCKED`; passe o número direto nas tools de envio.
## Falar com a base
### send\_whatsapp
Manda uma mensagem pra **uma** pessoa. Texto livre dentro da janela de 24h, ou template aprovado a qualquer hora. Passe **exatamente um** entre `message` e `templateName`.
| Parâmetro | Tipo | Descrição |
| - | - | - |
| `to` | string | Número em qualquer formato ou nome de contato salvo. Até 255 caracteres. |
| `message` | string (um dos dois) | Texto livre, até 4.096 caracteres. Só passa com a janela de 24h aberta. |
| `templateName` | string (um dos dois) | Nome de um template aprovado. Funciona com a janela fechada. |
| `variables` | string\[] (opcional) | Valores posicionais do template, na ordem: `["João", "4412"]` preenche `{{1}}` e `{{2}}`. Até 20 itens, 1.024 caracteres cada. |
| `from` | string (opcional) | Número de origem em E.164. Omitido, a Arara usa o número padrão da organização. |
| `idempotencyKey` | UUID (opcional) | Chave de idempotência. Omitida, o MCP gera uma por chamada. |
O retorno traz o `id` da mensagem, o status de aceite e o destinatário resolvido. Aceite quer dizer **na fila**, não entregue: confira a entrega com `check_status`.
Se você mandou texto livre e a janela estava fechada, o erro `CONVERSATION_WINDOW_CLOSED` já vem com até 10 templates aprovados pra escolher, ou sugere criar um com `create_template` se não houver nenhum.
```
manda um whatsapp pra Renata: seu pedido 4412 saiu pra entrega
```
```
manda o template aviso_entrega pro 11 99999-8888 com João e 4412
```
### broadcast
Manda um **template aprovado** pra várias pessoas de uma vez, como campanha. Disparo em massa é quase sempre fora da janela de 24h, então só aceita template. Teste A/B e agendamento são opções da mesma chamada.
| Parâmetro | Tipo | Descrição |
| - | - | - |
| `templateName` | string | Nome de um template aprovado (não o ID). Com `abTest`, é a variante A. |
| `to` | array | De 1 a 1.000 itens. Cada item é um número ou nome (usa as `variables` compartilhadas) **ou** um objeto `{ to, variables }` com valores só daquela pessoa. |
| `variables` | string\[] (opcional) | Variáveis aplicadas a quem veio como string. Até 20 itens. |
| `name` | string (opcional) | Nome da campanha no dashboard, até 255 caracteres. Omitido: `Broadcast AAAA-MM-DD HH:MM`. |
| `from` | string (opcional) | Número de origem em E.164. |
| `scheduledAt` | string (opcional) | Data e hora ISO-8601 em UTC, ex: `2026-09-20T12:00:00Z`. Presente, a campanha nasce agendada em vez de disparar agora. |
| `abTest` | objeto (opcional) | Liga o teste A/B. Ver abaixo. |
| `dryRun` | boolean (opcional) | Default `true`. Passe `false` pra disparar de verdade. |
| `idempotencyKey` | UUID (opcional) | Chave de idempotência do disparo. Omitida, o MCP gera uma por chamada. |
**Por padrão é uma prévia.** Com `dryRun` omitido ou `true`, o MCP resolve a audiência, renderiza o corpo do template com as variáveis do primeiro destinatário, lista os botões e chama o estimador de custo da Arara. Nada é enviado. A resposta traz a mensagem renderizada, quantos destinatários resolveram, quais não resolveram, custo unitário e total, a configuração de A/B e o agendamento.
Com `dryRun: false`, a campanha é criada e a resposta traz o ID, o status, o total de mensagens e o custo total. Pra disparar, a organização precisa ter um número dedicado conectado.
Números ou nomes que não resolverem vêm listados na resposta, sem derrubar o disparo. Se **nenhum** resolver, a tool falha com `NO_VALID_RECIPIENTS`.
`abTest`: a Arara manda as duas variantes pra uma **fatia** da base, meio a meio, mede a melhor na janela de decisão e dispara o **resto pela vencedora**.
| Campo de `abTest` | Tipo | Descrição |
| - | - | - |
| `variantBTemplateName` | string | Template da variante B (obrigatório). |
| `metric` | enum (opcional) | `DELIVERED`, `READ`, `CLICKED` ou `CONVERTED`. Default `CLICKED`. |
| `samplePct` | inteiro (opcional) | % da base que entra no teste, de 1 a 99. Default `20`. |
| `decisionWindowMinutes` | inteiro (opcional) | Minutos até decidir. Default `240` (4h). |
| `autopilot` | boolean (opcional) | Dispara o resto pela vencedora sozinho. Default `true`. |
```
dispara o template promo_setembro pra lista de clientes VIP com a variável "20% off"
```
```
testa a copy acad_v1 contra a acad_v2 nesses 300 leads: 20% no teste, decide em 4h por clique
```
## Ver o que voltou
### campaign\_report
Sem `campaignId`, lista as campanhas recentes, mais novas primeiro, com status, template, enviados, entregues, lidos, falhas e custo. Com `campaignId`, devolve o relatório completo: enviados, entregues, lidos, **cliques**, **respostas**, conversões (com valor), contatos segurados pelo A/B, bloqueados (com o motivo de cada grupo), estornos (quantidade e valor) e custo. A mensagem de texto já traz cada etapa em percentual da base.
| Parâmetro | Tipo | Descrição |
| - | - | - |
| `campaignId` | UUID (opcional) | ID da campanha, do `broadcast` ou da própria listagem. |
| `status` | string (opcional) | Filtro da listagem, ex: `COMPLETED`, `COMPLETED_WITH_ERRORS`, `AB_TESTING`, `SCHEDULED`, `CANCELED`, `FAILED`. |
| `page` | inteiro (opcional) | Página da listagem. Default `0`. |
| `size` | inteiro (opcional) | Itens por página, de 1 a 100. Default `20`. |
```
me mostra o relatório da campanha promo_setembro: quantos clicaram e quantos responderam?
```
### check\_status
Responde "chegou?", "posso falar agora?" e "o template aprovou?". Passe **exatamente um** dos três.
| Parâmetro | Tipo | Descrição |
| - | - | - |
| `to` | string | Pessoa (número ou nome). Diz se a janela de 24h está aberta e quantas horas restam. |
| `messageId` | string | O `id` devolvido pelo `send_whatsapp`. Status de entrega, custo e motivo se falhou. |
| `templateId` | UUID | O `id` devolvido pelo `create_template`. Status de aprovação da Meta (`APPROVED`, `PENDING`, `REJECTED` e afins), com o motivo quando reprovado. |
```
posso mandar texto livre pro +5511999998888 agora?
```
### read\_conversation
Lê o **conteúdo** das mensagens trocadas com uma pessoa, direto da timeline: direção (cliente ou você), status, template usado, texto e data de cada uma. É como você separa interesse real de resposta automática antes de responder com `send_whatsapp`.
| Parâmetro | Tipo | Descrição |
| - | - | - |
| `to` | string | Número (qualquer formato) ou nome de contato salvo. |
| `limit` | inteiro (opcional) | Quantas mensagens trazer, de 1 a 100. Default `30`. |
## Preparar
### create\_template
Submete um template novo pra aprovação da Meta. Você precisa de um pra qualquer `broadcast` e pra falar com quem está fora da janela de 24h. A aprovação costuma levar minutos; acompanhe com `check_status` passando o `templateId` que volta na resposta.
| Parâmetro | Tipo | Descrição |
| - | - | - |
| `name` | string | Nome único: só letras minúsculas, dígitos e underscore (`aviso_entrega`). Até 512 caracteres. |
| `category` | enum | `MARKETING`, `UTILITY` ou `AUTHENTICATION`. |
| `body` | string | Corpo com placeholders posicionais, até 4.096 caracteres: `Oi {{1}}, seu pedido {{2}} saiu`. |
| `language` | string (opcional) | Default `pt_BR`. |
| `header` | string (opcional) | Texto do cabeçalho ou URL de mídia. |
| `headerType` | enum (opcional) | `text`, `media` ou `document`. Quando há `header` sem `headerType`, vale `text`. |
| `footer` | string (opcional) | Rodapé, até 60 caracteres. |
| `samples` | objeto (opcional) | Exemplo por variável: `{"1": "João"}`. Ajuda a Meta a entender o template. |
| `buttons` | array (opcional) | Até 2 botões `{ type, text, url?, phone? }`. Tipos: `QUICK_REPLY`, `URL`, `PHONE_NUMBER`, `SMART_LINK`, `COPY_CODE`. `url` precisa ser URL válida; `phone`, E.164. |
A Meta reprova template que é só variável (`{{1}}` sem texto fixo). Escreva o texto real da mensagem; variável é pra nome, número de pedido, valor, não pro corpo inteiro.
Botão `SMART_LINK`: passe em `url` o **destino real** (ex: `https://wa.me/5511999999999?text=Quero%20saber%20mais`). A Arara encurta e conta cada clique, que aparece como cliques no `campaign_report`. É assim que você descobre qual copy converteu num teste A/B.
### save\_contacts
Salva (cria ou atualiza) contatos pra você mandar mensagem **por nome** em vez de decorar número. De 1 a 1.000 por chamada.
| Parâmetro | Tipo | Descrição |
| - | - | - |
| `contacts` | array | Lista de `{ name, phone, email?, attributes? }`. `name` até 255 caracteres; `phone` **obrigatoriamente** em E.164 (`+5511999998888`), sem normalização; `email` válido; `attributes` é um objeto livre de valores JSON. |
Devolve quantos foram criados, atualizados e ignorados, com a lista de erros por índice quando alguma linha não passa.
```
salva esses contatos da planilha: João +5511988887777, Renata +5521977776666
```
### opt\_out
Registra que uma pessoa **não quer mais receber mensagens** da sua organização, na lista de opt-out da organização. Idempotente: registrar duas vezes é seguro.
| Parâmetro | Tipo | Descrição |
| - | - | - |
| `phone` | string | E.164 (`+5511999998888`). Aqui não há normalização nem busca por nome. |
| `reason` | string (opcional) | Até 80 caracteres. Ex: `"respondeu PARAR"`, `"pediu no suporte"`. |
Pela LGPD, pedido de saída precisa ser respeitado. Registre sempre que a pessoa responder PARAR/STOP, pedir no suporte ou por escrito.
## Conta
### whoami
Sem parâmetros. Mostra quem está autenticado (nome e e-mail), o plano atual e o saldo da carteira. Chame antes do primeiro disparo da sessão pra conferir em qual conta o agente vai operar.
## Formato de resposta e erros
Toda tool devolve um texto curto pro modelo e um `structuredContent` estável:
```json theme={null}
{ "ok": true, "data": { } }
```
```json theme={null}
{ "ok": false, "error": { "code": "CONTACT_AMBIGUOUS", "message": "...", "retryable": false } }
```
Em erro de limite (`429`) ou de servidor, `retryable` vem `true` e, quando a API manda `Retry-After`, o campo `retryAfterSeconds` vem junto. Os códigos do próprio MCP:
| Código | Quando |
| - | - |
| `INVALID_INPUT` | Combinação de parâmetros inválida (ex: `message` e `templateName` juntos). |
| `INVALID_PHONE` | O número não vira E.164 válido. |
| `CONTACT_NOT_FOUND` | Nenhum contato salvo com esse nome. |
| `CONTACT_AMBIGUOUS` | Mais de um contato com esse nome; a mensagem lista os candidatos. |
| `CONVERSATION_WINDOW_CLOSED` | Texto livre com a janela de 24h fechada; a mensagem lista templates aprovados. |
| `NO_VALID_RECIPIENTS` | Nenhum destinatário do `broadcast` resolveu. |
| `INVALID_API_RESPONSE` | A API respondeu num formato inesperado. |
| `OPERATOR_NOT_CONFIGURED` / `OPERATOR_NOT_ALLOWED` | Chamada a uma tool de operação interna da AraraHQ. |
Os demais códigos vêm da própria API da Arara e passam sem alteração. Veja [Erros](/erros).
## Painéis interativos
Em clientes com suporte a **MCP Apps**, quatro tools abrem um painel dentro do chat em vez de só texto. O texto continua vindo junto, então clientes sem painel não perdem nada.
| Tool | Painel |
| - | - |
| `campaign_report` | Lista de campanhas ou funil da campanha com números grandes, motivos de bloqueio e atualização ao vivo enquanto dispara. Botões **Ver quem respondeu**, **Reenviar aos não lidos** e **Atualizar**. |
| `broadcast` | Celular com a mensagem renderizada, audiência, custo estimado e A/B. **Aprovar e disparar** chama o `broadcast` com `dryRun: false` e passa a mostrar a entrega em tempo real. |
| `check_status` | Pra `messageId`, linha do tempo da mensagem (aceita, enviada, entregue, lida) que acompanha sozinha até o status final. Pra `to`, se a janela está aberta ou fechada. Pra `templateId`, se o template foi aprovado ou reprovado, com o motivo. |
| `read_conversation` | Thread da conversa com campo de resposta que envia texto livre pelo `send_whatsapp`, e botões **Sugerir resposta** e **Pediu pra sair**. |
Os botões que não executam direto viram uma mensagem no chat pro agente continuar (por exemplo, "Reenviar aos não lidos" pede um reenvio com outro template). Os painéis são servidos como resources `ui://arara/campaign.html`, `ui://arara/broadcast.html`, `ui://arara/status.html` e `ui://arara/conversation.html`, e nunca recebem credencial.
## Resources
Dados que o agente lê sem gastar tool call. Todos voltam em JSON; se a leitura falhar, o conteúdo traz `RESOURCE_UNAVAILABLE`.
| Resource | URI | O que devolve |
| - | - | - |
| Organização | `arara://organization` | Quem está autenticado, plano atual e saldo da carteira. |
| Templates aprovados | `arara://templates/approved` | Templates aprovados e disponíveis pra envio (até 100), prontos pra `broadcast` e `send_whatsapp`. |
| Campanhas recentes | `arara://campaigns/recent` | As 10 últimas campanhas com status, contagens e custo. |
| Números | `arara://channels` | Seus números de WhatsApp e o estado do slot do plano. |
Cada cliente expõe resources de um jeito. Se o seu não mostrar, peça ao agente pra ler a URI, por exemplo `arara://templates/approved`.
## Prompts
Fluxos prontos que o cliente MCP expõe como atalhos. Nenhum recebe argumento, e todos param pra pedir aprovação antes de enviar.
| Prompt | O que faz |
| - | - |
| `plan_broadcast` | Chama `whoami` pra conferir conta e saldo, lê os templates aprovados e escolhe o que serve (ou propõe um novo com `create_template`), roda `broadcast` em prévia e só dispara com `dryRun: false` depois da sua aprovação explícita. |
| `campaign_review` | Acha a campanha com `campaign_report`, abre o relatório completo, resume entrega, leitura, cliques, respostas e conversões em percentual da base, explica bloqueados e estornos, e recomenda um próximo passo: responder quem respondeu, reenviar pra quem não leu com outro template, ou parar. |
| `reply_to_responses` | Lê o que a pessoa escreveu com `read_conversation` e rascunha uma resposta curta. Se ela pediu pra sair, chama `opt_out` em vez de responder. Não envia sem você aprovar o texto exato. |
## Automações (em preparação)
Esta seção descreve tools que ainda não estão no pacote publicado. Elas chegam numa próxima versão do `@ararahq/mcp`; os nomes abaixo podem mudar até o lançamento.
Sete tools para montar e acompanhar automações em linguagem natural, sobre a mesma [API de automações](/automacoes-api):
| Tool | O que faz |
| - | - |
| `list_automations` | Lista as automações da organização, com status e custo por execução. |
| `get_automation` | Traz uma automação inteira: gatilho, passos, ramos e estatísticas. |
| `create_automation` | Cria uma automação nova, com passos e ramificações. Nasce sempre desligada. |
| `update_automation` | Substitui nome, gatilho e passos de uma automação existente. |
| `set_automation_active` | Liga ou desliga uma automação. |
| `delete_automation` | Apaga uma automação e as execuções ligadas a ela. |
| `list_automation_runs` | Lista execuções de uma automação, com status e onde cada contato parou. |
Vale a mesma nota de permissão da API: escrita exige `AUTOMATIONS_MANAGE`, leitura exige `READ`. Sem a permissão, a tool falha com o `error.code` que a API devolveu.
`create_automation` e `update_automation` nunca ligam a automação sozinhos: ela sai desligada ou do jeito que já estava. Ligar uma automação com `set_automation_active` manda mensagens reais para clientes reais a partir daquele momento; confirme com a pessoa antes de chamar. O link de uma automação com gatilho `webhook` é uma credencial: nunca cole nem repita esse link na conversa.
```
monta uma automação que pergunta se o cliente quer pagar por Pix ou cartão e etiqueta cada resposta
```
```
me mostra quem parou na pergunta ontem
```
## Próximos passos
Login, configuração em cada cliente e primeiro uso.
Códigos que a API devolve e passam sem alteração pelo MCP.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.