Arquitetura
Visão pública da arquitetura do MCP Alcance Contabilidade - um gateway HTTPS que traduz o protocolo MCP (Model Context Protocol) em chamadas autenticadas contra a WebApiAlcance.
1. Propósito
Em uma frase: dar a um LLM acesso seguro e auditável aos dados contábeis da Alcance, sem que o LLM jamais conheça a API real ou suas credenciais.
O gateway é o ponto único onde:
- Autenticamos o cliente IA.
- Validamos input (Zod).
- Mascaramos PII por padrão.
- Logamos invocações.
- Traduzimos para a WebApi com API Key dedicada e escopo restrito.
2. Diagrama de contexto (C4 - Nível 1)
┌──────────────────┐ ┌─────────────────────────────┐
│ Operador humano │ ────▶ │ Cliente IA │
│ contador/analista│ PT-BR │ Claude / Cursor / Lovable / │
└──────────────────┘ │ ChatGPT* │
└──────────────┬──────────────┘
│ MCP Streamable HTTP
▼
┌─────────────────────────────┐
│ MCP Alcance │
│ gateway MCP HTTPS │
└──────────────┬──────────────┘
│ HTTPS + API Key
▼
┌─────────────────────────────┐
│ WebApiAlcance │
│ FastAPI │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────────────┐
│ Banco de dados · Processamento │
│ assíncrono │
└─────────────────────────────────────┘* ChatGPT depende de OAuth 2.1 (Fase 2).
3. Padrões inegociáveis
- PT-BR em tudo que toca o LLM - descrições de tools, mensagens de erro, hints. O LLM consome essas strings.
- Annotations corretas -
readOnlyHint: trueem reads;destructiveHint: trueem writes. O Claude Desktop mostra escudo amarelo nos destrutivos. - Dry-run by default em writes - todo write tem
confirmar: z.boolean().default(false). Semtrue, retorna apenas preview. - PII mascarada by default em respostas READ. Desmascarar exige tool específica.
cliente_id: inté o identificador canônico. CNPJ entra apenas embuscar_cliente(termo), que devolve o id.- Tarefas longas são assíncronas - retornamos
task_id; o cliente IA usaconsultar_status_taskpara acompanhar. - Truncamento - listas com mais de 50 itens cortam em 20 com footer; mais de 500 bloqueia com erro estruturado.
- Sem operações destrutivas de gestão - o gateway não expõe exclusão nem administração de usuários ou credenciais.
4. Boundaries - o que o MCP faz vs delega
| Responsabilidade | MCP gateway | WebApiAlcance | Cliente IA |
|---|---|---|---|
| Autenticar cliente IA (Bearer) | sim | não | apresenta token |
| Autorização por escopo de API Key | consome | sim | não |
| Validação de input (Zod) | sim | revalida | via JSON Schema |
| Mascaramento de PII em respostas | sim | não (retorna dados crus) | não |
| Conversão JSON → tabela markdown | sim | não | não |
| Erro estruturado em PT-BR | sim | passa erro upstream | renderiza |
| Persistência / lógica de negócio | não | sim | não |
| Disparo de tarefas assíncronas | chama endpoint | sim | não |
| Acompanhamento de tasks | sim (consultar_status_task) | sim (endpoint) | delega |
| Auditoria de invocações | sim (logs do gateway) | sim (logs HTTP) | não |
5. Evolução
O roadmap prevê autenticação OAuth 2.1, ampliação do catálogo de tools e busca semântica sobre legislação e manuais.
6. Referências públicas
- Specification MCP
- mcp-handler (npm)
- Anthropic MCP docs
- C4 model - usado para os diagramas de contexto e container.