> ## 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. # MCP Server > Conecte Claude Code, Claude Desktop, Cursor ou qualquer cliente MCP à sua operação de WhatsApp na Arara. Instalou, autorizou no browser e o agente já fala com a sua base: dispara campanha, lê o que voltou e responde quem levantou a mão. Você pede em português, o agente executa. ## O que é e para quem **MCP (Model Context Protocol)** é o protocolo aberto, criado pela Anthropic, para conectar LLMs a ferramentas externas. O pacote `@ararahq/mcp` roda local via stdio em qualquer cliente que fale MCP: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code e SDKs de MCP. Há também um [servidor hospedado](#servidor-hospedado) para claude.ai e ChatGPT. Use o MCP quando o agente é **seu** (Claude Code, Cursor, Claude Desktop) e trabalha **para você**: dispara campanha, lê o relatório, lê o que a pessoa respondeu e manda a resposta que você aprovou. Já o [Brain](/brain) é a IA da Arara que conversa **com o seu cliente** no WhatsApp. | Você precisa de... | Use | | - | - | | Agente de IA que age na sua conta (Claude Code, Claude Desktop, Cursor) | **MCP** | | IA que atende o seu cliente no WhatsApp e executa Pix, agenda e catálogo | [Brain](/brain) | | Backend próprio que dispara WhatsApp (e-commerce, CRM) | [SDK](/sdks) ou [API REST](/api-reference/introduction) | | Resposta automática às respostas da base, com escalada para uma pessoa | [Automações](/integracoes) | | Automação visual sem código | [Integrações](/integracoes) | Não são exclusivos: operação típica usa SDK no backend, automações para responder e MCP para o dono trabalhar pelo agente. ### Você diz o quê. A Arara resolve o resto. O MCP tem poucas ferramentas de propósito: agente bom não precisa de um painel de controle inteiro, precisa de poucas ações que aceitam o que uma pessoa sabe de cabeça. `send_whatsapp` aceita `"Renata"` ou `"11 99999-8888"`. O MCP busca o contato salvo ou normaliza o número para E.164 e, se a janela de 24h estiver fechada, não inventa template: devolve os seus aprovados para escolher. | Grupo | Ferramentas | | - | - | | Falar com a base | `send_whatsapp` · `broadcast` (prévia por padrão, A/B e agendamento) | | Ver o que voltou | `campaign_report` · `check_status` · `read_conversation` | | Preparar | `create_template` (com botões e smart-link) · `save_contacts` · `opt_out` | | Conta | `whoami` | Quatro tools abrem **painéis interativos** dentro do chat (funil da campanha, prévia da campanha com aprovação, linha do tempo da entrega, thread da conversa) em clientes com suporte a MCP Apps. Leitura leve (conta, templates aprovados, campanhas recentes, números) fica em **resources**, sem gastar tool call. Parâmetros, limites e exemplos: [Ferramentas do MCP](/mcp-tools). A lista de tools do cliente também mostra ferramentas de operação interna da equipe da Arara. Elas não estão disponíveis para clientes. Para a sua organização, as listadas na tabela acima são as que funcionam. Configuração de conta (chaves de API, perfil do negócio, números, automações) é trabalho do [painel](https://app.ararahq.com), não do agente. ## Instalar e conectar Requisito: **Node.js 20 ou mais novo**. No Linux, o keychain usa o Secret Service (`libsecret`), que precisa estar instalado. ### 1. Login (uma vez por máquina) ```bash theme={null} npx -y @ararahq/mcp login ``` O terminal mostra um link e um código e abre a Arara no browser. Você aprova com a sua conta, e as credenciais OAuth vão para o keychain do sistema (Keychain no macOS, Secret Service no Linux, Credential Manager no Windows). Nada fica em arquivo de projeto nem na configuração do cliente. Confira: ```bash theme={null} npx -y @ararahq/mcp status ``` ### 2. Adicionar ao cliente ```bash theme={null} claude mcp add ararahq --scope user -- npx -y @ararahq/mcp --stdio ``` Reinicie a sessão do Claude Code. Edite `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json theme={null} { "mcpServers": { "ararahq": { "command": "npx", "args": ["-y", "@ararahq/mcp", "--stdio"] } } } ``` Reinicie o Claude Desktop. Em `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (projeto): ```json theme={null} { "mcpServers": { "ararahq": { "command": "npx", "args": ["-y", "@ararahq/mcp", "--stdio"] } } } ``` Windsurf, VS Code e qualquer cliente com transporte stdio usam o mesmo comando. Aponte a configuração MCP do cliente para: ```json theme={null} { "command": "npx", "args": ["-y", "@ararahq/mcp", "--stdio"] } ``` Deixe o `--stdio` explícito. Sem ele, se a variável `PORT` existir no ambiente do cliente, o binário sobe em modo HTTP em vez de stdio. ### Comandos do CLI | Comando | O que faz | | - | - | | `npx -y @ararahq/mcp login` | Login OAuth pelo browser (device flow). Salva os tokens no keychain. | | `npx -y @ararahq/mcp status` | Diz com qual conta (nome e e-mail) o MCP está autenticado. | | `npx -y @ararahq/mcp doctor` | Versão do MCP, versão do Node, URL da API em uso e status do login. | | `npx -y @ararahq/mcp tools` | Lista os nomes de todas as tools registradas (inclui as de operação interna). | | `npx -y @ararahq/mcp logout` | Remove os tokens do keychain desta máquina. | | `npx -y @ararahq/mcp --version` | Versão instalada. | ## Primeiro uso Depois de conectar, confira com `whoami` em qual organização o agente vai operar e peça uma destas três coisas. **Falar com a base** ``` dispara o template promo_setembro para esses 40 números da planilha ``` `broadcast` resolve os números (qualquer formato), renderiza a mensagem e estima o custo **sem enviar**. Você confere a prévia e aprova; só aí a campanha é criada. Quem não resolver aparece listado, não some em silêncio. **Ver o que voltou** ``` como foi a campanha de ontem? quantos clicaram e quantos responderam? ``` `campaign_report` devolve enviados, entregues, lidos, cliques, respostas e conversões, mais quantos foram bloqueados e por quê, estornos e custo. **Responder quem levantou a mão** ``` lê o que a Renata respondeu e me sugere uma resposta ``` `read_conversation` traz o que ela escreveu; `send_whatsapp` responde depois que você aprova o texto. ## Servidor hospedado A AraraHQ também roda o servidor em `https://mcp.ararahq.com/mcp`, na Cloudflare Workers, para clientes que falam MCP Streamable HTTP. ``` URL: https://mcp.ararahq.com/mcp Header: Authorization: Bearer ``` ### Conectar no claude.ai ou no ChatGPT Adicione um conector personalizado com a URL `https://mcp.ararahq.com/mcp`. O cliente faz o resto sozinho: 1. Lê `/.well-known/oauth-protected-resource` no MCP e descobre o servidor de autorização (`https://api.ararahq.com/api`). 2. Registra um client via `POST /oauth/register` (registro dinâmico). 3. Abre `https://app.ararahq.com/oauth/authorize`, onde você entra na sua conta e aprova o acesso. 4. Troca o código por token em `POST /oauth/token` (authorization code com PKCE `S256`) e passa a mandar o bearer em cada chamada. Não há chave de API nem token para colar em lugar nenhum. Como o hospedado se comporta: * **Stateless**, só `POST /mcp`. `GET` responde `405`. Não existe endpoint SSE legado. * **Só bearer no header** `Authorization`. Não existe credencial na query string nem API key como argumento de tool. Sem token válido, responde `401` com `WWW-Authenticate` apontando pro metadata do recurso. * **Protected Resource Metadata** em `/.well-known/oauth-protected-resource` e `/.well-known/oauth-protected-resource/mcp`, com `https://api.ararahq.com/api` como servidor de autorização. * **Allowlist de Host e de Origin.** Requisição de browser só é aceita de `https://claude.ai` e `https://chatgpt.com`; cliente sem `Origin` (não browser) passa. * **Rate limit por usuário autenticado**, não por IP: 120 requisições por minuto. Acima disso, `429` com `Retry-After: 60`. * A identidade do token é consultada na API e guardada por 60 segundos, só com a impressão digital (SHA-256) do token, nome e e-mail. O token em si nunca é armazenado. * `GET /health` devolve status, nome e versão. ## Autenticação OAuth, e só OAuth. * **Local:** `login` roda o device flow da Arara com o client `arara-mcp`. Access token e refresh token ficam no keychain. Quando o access token está a 30 segundos de expirar, o MCP renova sozinho com o refresh token. Se o refresh também tiver expirado, rode `login` de novo. * **Hospedado:** cada requisição carrega o bearer token no header. O servidor não guarda, não renova e não emite token. * Ao aprovar o login, a organização recebe um alerta no dashboard ("Novo dispositivo conectado") com o e-mail de quem autorizou. * `logout` apaga os tokens desta máquina. Sem login, as tools não executam. Rode `status` ou `doctor` pra conferir antes de abrir o cliente. ## Guarda-rails * **Disparo começa em prévia.** `broadcast` só envia com `dryRun: false`. O prompt `plan_broadcast` e o painel de disparo pedem sua aprovação antes. * **Retry sem mensagem duplicada.** `send_whatsapp` e `broadcast` mandam `Idempotency-Key` em toda chamada. As retentativas automáticas reaproveitam a mesma chave; pra repetir uma chamada inteira com segurança, passe o mesmo `idempotencyKey`. * **Anotações de segurança do MCP.** Tools de leitura vêm marcadas como `readOnlyHint`; `opt_out` vem como `destructiveHint`. Clientes que respeitam as anotações pedem confirmação antes de executar escrita. * **Nada some calado.** Destinatário que não resolve volta na resposta; contato bloqueado no disparo aparece no `campaign_report` com o motivo. * **Pedido de saída.** `opt_out` registra o número na lista de opt-out da organização. Use sempre que alguém responder PARAR ou pedir pra sair. ## Segurança * **Credencial nunca aparece:** nenhuma tool aceita ou devolve token. O que chega ao modelo é só o resultado. * **Keychain do sistema:** tokens locais nunca ficam em texto puro no disco nem na configuração do cliente. * **Payload validado:** toda resposta da API passa por schema antes de ser usada. Formato inesperado vira erro `INVALID_API_RESPONSE`, não crash. * **Timeout explícito:** 10 segundos por chamada à API. * **Retry contido:** no máximo 2 retentativas, só em métodos seguros ou chamadas com `Idempotency-Key`, respeitando `Retry-After`. * **Sem telemetria:** o pacote não coleta nada. ## Configuração avançada Variáveis de ambiente lidas pelo binário: ```sh theme={null} ARARA_API_URL=https://... # Endpoint da API (default: https://api.ararahq.com/api) MCP_TRANSPORT=http # Streamable HTTP em vez de stdio PORT=3333 # Porta do modo HTTP (default 3333). Sem --stdio, definir PORT liga o modo HTTP MCP_PUBLIC_URL=https://.../mcp # URL pública do recurso, publicada no metadata OAuth MCP_RESOURCE_METADATA_URL=https://... # URL do metadata anunciada no WWW-Authenticate MCP_ALLOWED_HOSTS=mcp.ararahq.com # Allowlist de Host (default: localhost,127.0.0.1,mcp.ararahq.com) MCP_ALLOWED_ORIGINS=https://claude.ai # Allowlist de Origin (default: https://chatgpt.com,https://claude.ai) ARARA_OAUTH_ISSUER=https://... # Servidor de autorização anunciado (default: ARARA_API_URL) ARARA_OAUTH_SCOPES="scope1 scope2" # Escopos publicados no metadata, separados por espaço ``` No modo HTTP em Node, o corpo da requisição é limitado a 64 KB e o rate limit é de 120 requisições por minuto por IP. ## Próximos passos Referência de tools, resources e prompts: parâmetros, limites e exemplos. A IA da Arara que atende o seu cliente no WhatsApp. A CLI tem um `arara mcp` próprio, diferente deste pacote. Código aberto MIT, releases versionadas, issues abertas. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.