MCP Query: o primeiro MCP server open source pro Protheus que deixa Claude e ChatGPT consultar suas tabelas com seguranca

O cenario mudou em 2025-2026. Devs Protheus que antes faziam User Function REST pra cada tabela hoje recebem perguntas tipo "da pra ligar o Claude no nosso ERP?" e ficam sem resposta tecnica clara.

Este post entrega a resposta — e o fonte AdvPL completo pra voce baixar e rodar hoje no seu ambiente.

O problema que esse fonte resolve

Cenario classico: o cliente quer um chatbot que consulta o ERP. Hoje voce tem 3 opcoes:

1. Criar 1 endpoint REST por tabela: SA1 (clientes), SC5 (pedidos), SE2 (titulos)... acaba em 40-80 endpoints. Cada um com codigo duplicado de validacao, paginacao e seguranca. Manutencao vira pesadelo.
2. Expor o DBAccess direto: qualquer dev com a string de conexao vira um SELECT inocente em '; DROP TABLE SA1; --. Inviavel em producao.
3. Comprar conector pago: licenca de R$ 2-8k/mes por ambiente. Para POC dispendioso, e ainda assim nao integra com Claude/MCP.

O McpQuery resolve as 3 dores: 1 endpoint generico, SQL injection protection embutida, open source MIT. Voce baixa, instala no RPO, configura porta REST e em 15 minutos seu Protheus responde a queries MCP.

Arquitetura

O fluxo e simples mas tem 4 camadas de validacao antes do SQL bater no DBAccess:

Pontos de design que valem destacar:

• Dois modos: tableName + fields + cWhere (modo seguro, com TOP N + ORDER BY R_E_C_N_O_) ou rawQuery (SELECT completo com SUM/GROUP BY/JOIN, pra relatorios analiticos)
• Paginacao deterministica: usa R_E_C_N_O_ > offset em vez de OFFSET N ROWS. Performance previsivel ate em tabelas de 50M+ registros.
• Tabelas de framework (SX1-SXG, SIX) sao tratadas separado — nao tem D_E_L_E_T_ e usam padrao SX#cEmp0
• Auditoria nativa via ConOut("[MCP-AUDIT] ...") — qualquer SIEM (Splunk, Datadog, ELK) ja parse direto

Na pratica

Tres exemplos reais que voce pode rodar agora:

Exemplo 1 — Listar clientes ativos do estado SP

curl 'https://seu-protheus:8443/McpQuery/query?tableName=SA1&fields=A1_COD,A1_NOME,A1_EST&cWhere=A1_EST%3D%27SP%27&limit=50' \
  -H "Authorization: Basic YWRtaW46c2VuaGE="

Resposta:

{
  "data": [
    {"A1_COD": "000001", "A1_NOME": "ACME LTDA", "A1_EST": "SP"},
    {"A1_COD": "000002", "A1_NOME": "FOO IND COM", "A1_EST": "SP"}
  ],
  "count": 50,
  "hasMore": true
}

Exemplo 2 — Total faturado por mes (rawQuery)

curl 'https://seu-protheus:8443/McpQuery/query' \
  -G --data-urlencode 'rawQuery=SELECT SUBSTR(F2_EMISSAO,1,6) MES, SUM(F2_VALBRUT) TOTAL FROM SF2010 WHERE D_E_L_E_T_=' ' GROUP BY SUBSTR(F2_EMISSAO,1,6) ORDER BY MES' \
  --data-urlencode 'limit=1000'

Exemplo 3 — LLM pergunta direto via MCP

Voce configura o Claude Desktop com um MCP server stub que faz proxy pro endpoint. Ai conversa fica:

Usuario: Quantos pedidos abertos temos do cliente 000123?
Claude:  [chama McpQuery com tableName=SC5, cWhere=C5_CLIENTE='000123' AND C5_LIBEROK=' ']
         Voce tem 7 pedidos abertos somando R$ 482.150,00. Quer detalhamento?

Seguranca embutida (o diferencial)

Quando voce expoe SQL via REST, atacante tenta de tudo. O McpQuery bloqueia antes de chegar no banco:

Toda tentativa bloqueada vai pro ConOut com tipo [MCP-AUDIT] [INJECTION]. Voce monta um alerta no Datadog/Splunk e quando alguem tenta atacar voce sabe em segundos.

Quando NAO usar

Pra ser justo com voce, eis 3 cenarios onde nao recomendamos:

• Operacoes de escrita: McpQuery e read-only. Pra criar/alterar dados use o irmao dele, McpExecAuto.
• Latencia < 50ms exigida: a stack TcGenQry + DbUseArea tem ~20-100ms de overhead vs JDBC direto. Pra trading-grade workloads, use replica leitura + JDBC.
• Joins complexos com 5+ tabelas + UNION: o modo rawQuery suporta, mas a blocklist de UNION pode ser restritiva. Avalie criar uma View no banco e expor essa View como tabela.

Caso real

Cliente da industria quimica (40 empresas, 350k SKUs), implantou o McpQuery em outubro/2025 pra alimentar um chatbot interno baseado em Claude 3.5 Sonnet.

Numeros pos-3-meses:

• Volume: 1.200 consultas/dia em horario comercial, picos de 80 req/min
• Latencia p95: 180ms (incluindo Claude + McpQuery + DBAccess)
• Tentativas de injection bloqueadas: 7 nos primeiros 30 dias (todas vindas de pen-test contratado), 0 vindas de usuarios reais
• Redirecionamento de chamadas pro SAC: -34% (usuarios resolvem auto-consulta via chatbot)

Proximos passos

• Baixe o fonte acima (~14KB, MIT)
• Suba no seu RPO via TDS-VSCode ou advpl-compile (claude-advpl-skill faz isso em terminal)
• Configure o appserver.ini com porta REST + Basic Auth + TLS
• Teste o endpoint ?tableName=_DEBUG pra confirmar resolucao das tabelas SIX/SX7/SX9
• Integre com seu LLM preferido — docs MCP oficial ou via plugin OpenAI Function Calling

Quer ver rodando antes de implantar? Marque uma demo de 30min com a gente. A gente mostra Claude consultando um Protheus de demonstracao em tempo real.