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:

  1. Autenticamos o cliente IA.
  2. Validamos input (Zod).
  3. Mascaramos PII por padrão.
  4. Logamos invocações.
  5. 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

  1. PT-BR em tudo que toca o LLM - descrições de tools, mensagens de erro, hints. O LLM consome essas strings.
  2. Annotations corretas - readOnlyHint: true em reads; destructiveHint: true em writes. O Claude Desktop mostra escudo amarelo nos destrutivos.
  3. Dry-run by default em writes - todo write tem confirmar: z.boolean().default(false). Sem true, retorna apenas preview.
  4. PII mascarada by default em respostas READ. Desmascarar exige tool específica.
  5. cliente_id: int é o identificador canônico. CNPJ entra apenas em buscar_cliente(termo), que devolve o id.
  6. Tarefas longas são assíncronas - retornamos task_id; o cliente IA usa consultar_status_task para acompanhar.
  7. Truncamento - listas com mais de 50 itens cortam em 20 com footer; mais de 500 bloqueia com erro estruturado.
  8. 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

ResponsabilidadeMCP gatewayWebApiAlcanceCliente IA
Autenticar cliente IA (Bearer)simnãoapresenta token
Autorização por escopo de API Keyconsomesimnão
Validação de input (Zod)simrevalidavia JSON Schema
Mascaramento de PII em respostassimnão (retorna dados crus)não
Conversão JSON → tabela markdownsimnãonão
Erro estruturado em PT-BRsimpassa erro upstreamrenderiza
Persistência / lógica de negócionãosimnão
Disparo de tarefas assíncronaschama endpointsimnão
Acompanhamento de taskssim (consultar_status_task)sim (endpoint)delega
Auditoria de invocaçõessim (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