# Mandaí MCP

Endpoint remoto e stateless:

`https://mcp.mandaionline.com/mcp`

## Consultas públicas

Sem autenticação, o servidor oferece recursos de produto, preço, documentação e OpenAPI, além de:

- `estimate_monthly_contract`: estima o contrato mensal;
- `preview_sms`: analisa encoding e segmentos sem telefone;
- `explain_message_status`: explica evidências de cada estado.

## Envio autenticado

`send_sms` cria uma intenção idempotente pela API canônica do Mandaí. Obtenha confirmação explícita do usuário antes de chamar.

### OAuth DPoP

Descubra https://mcp.mandaionline.com/.well-known/oauth-protected-resource e o authorization server anunciado. Use authorization code com PKCE S256, consentimento e `resource=https://mcp.mandaionline.com`, solicitando `messages:create`. Use PAR quando exigido pelo servidor para o scope solicitado.

O cliente precisa suportar DPoP: envie `Authorization: DPoP <access_token>` e uma prova ES256 nova no header `DPoP` em cada requisição. Para o POST MCP, a prova usa `htu=https://mcp.mandaionline.com/mcp`, `htm=POST` e `ath` (SHA-256 do access token), assinada pela chave à qual o token está vinculado. Não coloque uma prova estática na configuração: ela não pode ser reutilizada.

O consentimento e o token devem corresponder ao ambiente informado. O fluxo `service_auth` do [auth.md](https://mandaionline.com/auth.md) concede somente leitura na Sandbox API: esse token não serve para envio nem para o recurso MCP. O registro dinâmico de clientes só está disponível quando anunciado no discovery; não presuma que qualquer cliente possa se registrar automaticamente.

### API key

Para clientes sem suporte ao fluxo OAuth DPoP, configure uma chave com `messages:send` no header do cliente MCP:

```json
{
  "mcpServers": {
    "mandai": {
      "url": "https://mcp.mandaionline.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MANDAI_API_KEY}"
      }
    }
  }
}
```

Não coloque a chave na conversa ou nos argumentos da ferramenta. `send_sms` exige:

- `environment`: `sandbox` ou `production`;
- `idempotency_key`: chave estável de 8 a 128 caracteres;
- `to`: telefone brasileiro em E.164;
- `body`: conteúdo transacional;
- `message_type` e `metadata`: opcionais.

A chave precisa pertencer ao ambiente escolhido. Em Produção, a API também exige tenant autorizado, capacidade vigente e cobertura operacional saudável; não há admissão comercial manual. Uma chamada aprovada pode alcançar um telefone real e consumir o contrato.

Depois de validar a integração na Sandbox, um owner ou administrador pode contratar pelo menos 250 SMS em **Uso e cobrança**, pagar o QR Code do Pix mensal avulso da Woovi e aguardar a conciliação e a disponibilidade da política no ambiente. Não há admissão manual de clientes. O MCP orienta esse fluxo, mas não cria cobranças, não realiza pagamentos e não substitui permissões, quota ou cobertura.

## Segurança

- a chave existe somente no header da requisição e é encaminhada à API do ambiente;
- o MCP não registra chave, telefone, corpo ou argumentos;
- a API aplica escopos, idempotência, rate limits, billing e evidência;
- repetir a mesma `idempotency_key` com conteúdo diferente retorna conflito;
- o MCP não administra chaves, contratos, pagamentos ou estoque.

Documentação: https://mandaionline.com/docs/mcp/

Contato: atendimento@mandaionline.com