MCP — Gateway IA
O MCP Alcance é o gateway que conecta clientes de IA — Claude Desktop, Cursor, Lovable e ChatGPT — à WebApiAlcance, expondo a operação contábil interna como um conjunto de ferramentas tipadas, seguras e auditáveis. Roda na Vercel Pro (região gru1, São Paulo) e atua como camada HTTPS pública sobre a API privada on-premise.
O que é MCP?
Model Context Protocol (MCP) é o padrão aberto da Anthropic para integrar Large Language Models a sistemas externos. Em vez de cada cliente IA reinventar a ponte para cada serviço, o MCP define um protocolo único — pense nele como o USB-C das integrações de IA.
Cada servidor MCP expõe três tipos de capacidade:
- Tools — ações tipadas que o LLM pode invocar (ex.:
buscar_cliente). - Resources — leituras passivas, como glossários e enums.
- Prompts — templates prontos, expostos como slash-commands no cliente.
O cliente IA descobre essas capacidades em runtime via handshake, e o LLM decide quando acioná-las com base nas descrições em linguagem natural — por isso o MCP Alcance escreve tudo em PT-BR.
Arquitetura em 1 minuto
┌──────────────┐ HTTPS+Bearer ┌────────────────────┐ mTLS via ┌──────────────────┐ HTTP ┌─────────────────┐
│ Cliente IA │ ────────────────► │ Gateway MCP │ ───Tunnel──► │ Cloudflare WAF │ ────────► │ WebApiAlcance │
│ (Claude etc) │ /api/mcp │ Vercel · gru1 │ Cloudflare │ + Rate Limit │ │ FastAPI local │
└──────────────┘ └────────────────────┘ └──────────────────┘ └─────────────────┘O gateway valida o Bearer do cliente, traduz a chamada MCP para a WebApi (anexando a API Key dedicada com escopo restrito), aplica mascaramento de PII e devolve resposta formatada em markdown — pronta para o LLM consumir.
URL canônica
Aponte qualquer cliente MCP para o endpoint abaixo. O transporte é HTTP streamable, com fallback SSE em /api/sse.
https://mcp-alcancecontabilidade.vercel.app/api/mcpBearer obrigatório
Toda requisição deve incluir o header Authorization: Bearer <MCP_BEARER_TOKEN>. O token é
emitido pelo time TI e é distinto por integração — não compartilhe entre clientes.
Tools disponíveis
A Fase 1 expõe seis tools, todas com nomes em PT-BR e identificador único cliente_id (int). Tools de escrita executam em dry-run por padrão; o efeito real exige confirmar=true.
buscar_clientereadLocaliza clientes por CNPJ. Busca por razão social chega na Fase 1.1.
obter_clientereadFicha completa do cliente com PII mascarada (credenciais gov nunca expostas).
listar_certidoesreadLista certidões negativas (CND, FGTS, SEFAZ) com filtros e paginação.
listar_lembretesreadLembretes WhatsApp ativos, filtrando por cliente ou usuário responsável.
criar_lembretewriteCria lembrete WhatsApp em modo dry-run; confirmar=true para enviar.
consultar_status_taskreadConsulta o status de uma task Celery (geração de PDF, conversão de extrato, etc).