MCP Server

​

O que é e para quem

​

Você diz o quê. A Arara resolve o resto.

​

Instalar e conectar

​

1. Login (uma vez por máquina)

npx -y @ararahq/mcp login

npx -y @ararahq/mcp status

​

2. Adicionar ao cliente

claude mcp add ararahq --scope user -- npx -y @ararahq/mcp --stdio

{
  "mcpServers": {
    "ararahq": {
      "command": "npx",
      "args": ["-y", "@ararahq/mcp", "--stdio"]
    }
  }
}

{
  "mcpServers": {
    "ararahq": {
      "command": "npx",
      "args": ["-y", "@ararahq/mcp", "--stdio"]
    }
  }
}

{
  "command": "npx",
  "args": ["-y", "@ararahq/mcp", "--stdio"]
}

​

Comandos do CLI

​

Primeiro uso

dispara o template promo_setembro para esses 40 números da planilha

como foi a campanha de ontem? quantos clicaram e quantos responderam?

lê o que a Renata respondeu e me sugere uma resposta

​

Servidor hospedado

URL: https://mcp.ararahq.com/mcp
Header: Authorization: Bearer <token OAuth da Arara>

​

Conectar no claude.ai ou no ChatGPT

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.

• 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

• 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.

​

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

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

​

Próximos passos