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. Atua como camada HTTPS entre o cliente IA e a API.

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

Cliente IA --(HTTPS + Bearer)--> Gateway MCP --(HTTPS + API Key)--> WebApiAlcance

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 suportado é o HTTP streamable em /api/mcp. Não há fallback SSE garantido.

https://mcp.contabilidadealcance.com.br/api/mcp

Bearer obrigatório

Toda requisição deve incluir o header Authorization: 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 sete 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_clienteread

Localiza clientes por CNPJ. Busca por razão social chega na Fase 1.1.

obter_clienteread

Ficha completa do cliente com PII mascarada.

listar_clientesread

Lista clientes com filtros opcionais (UF, regime tributário, cidade) e paginação. CNPJ/CPF mascarados.

listar_certidoesread

Lista certidões negativas (CND, FGTS, SEFAZ) com filtros e paginação.

listar_lembretesread

Lembretes WhatsApp ativos, filtrando por cliente ou usuário responsável.

criar_lembretewrite

Cria lembrete WhatsApp em modo dry-run; confirmar=true para enviar.

consultar_status_taskread

Consulta o status de uma tarefa assíncrona (geração de PDF, conversão de extrato, etc).

Próximos passos