MCP Query

Endpoint REST MCP-compatible pra consultar qualquer tabela Protheus. SQL injection protection embutida, paginacao por R_E_C_N_O_, modo rawQuery pra SUM/GROUP BY.

Assinatura: GET /McpQuery/query?tableName=SA1&fields=A1_COD,A1_NOME&cWhere=...&limit=50&offset=0

Retorna: JsonObject {data, count, hasMore}

O McpQuery.prw e um WSRESTFUL que expoe consultas SQL ao Protheus de forma segura. E o primeiro MCP server open source pra Protheus — compativel com Model Context Protocol da Anthropic.

Parametros (modo normal)

Param	Tipo	Obrigatorio	Descricao
`tableName`	String	Sim*	Nome da tabela (SA1, SC5, SX1, etc). So letras/numeros/underscore.
`fields`	String	Nao	Lista de campos separados por virgula. Default: `*`
`cWhere`	String	Nao	Clausula WHERE adicional (sem subselect, sem DDL/DML)
`limit`	Numeric	Nao	Max registros (default 100, max 1000)
`offset`	Numeric	Nao	Pagina (R_E_C_N_O_ > offset)
`rawQuery`	String	Sim*	SELECT completo (modo alternativo, max 10000 linhas)

* tableName OU rawQuery e obrigatorio.

Exemplo basico

curl 'https://seu-protheus:8443/McpQuery/query?tableName=SA1&fields=A1_COD,A1_NOME&limit=10'

Resposta:

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

Modo rawQuery (analitico)

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)' \
  --data-urlencode 'limit=100'

Validacoes embutidas

Tabela: regex [A-Z0-9_]+, max 20 chars
Fields: bloqueia SELECT, INSERT, UPDATE, DELETE, DROP, EXEC, UNION, ;, --, /*, xp_, sp_
cWhere: bloqueia subselect (palavra SELECT no WHERE) + tudo do fields
rawQuery: deve comecar com SELECT, bloqueia DDL/DML + UNION + CHAR()/CONVERT()/CAST() + 0x
Multi-statement: ponto-e-virgula sempre rejeitado
Tabelas bloqueadas: SX8 (numeradores) hardcoded
Campos sensiveis: retorna ***REDACTED*** em PSW, CHKSUM, LICENSA, CORPKEY, SECRET, TOKEN, APIKEY

Tabelas de framework (SX1-SXG, SIX)

Sao detectadas automaticamente e usam padrao SX#cEmp0 (sem D_E_L_E_T_).

Auditoria

Toda chamada gera linha estruturada no console:

[MCP-AUDIT] [QUERY] 14/05/2026 10:32:08 Tabela=SA1 fields=A1_COD,A1_NOME where= limit=10 offset=0
[MCP-AUDIT] [INJECTION] 14/05/2026 10:32:15 Tabela=SA1 Where bloqueado: --

Quando usar

Integrar LLM (Claude/ChatGPT) pra consulta de dados do ERP
Substituir dezenas de endpoints REST custom por um generico
Relatorios analiticos via SUM/GROUP BY (modo rawQuery)

Quando NAO usar

Operacoes de escrita (use McpExecAuto)
Latencia < 50ms (overhead TcGenQry ~20-100ms)
JOIN de 5+ tabelas (cria View no banco)

Pegadinhas

Sem auth no fonte original — adicione Basic Auth/JWT via TLPP @Security antes de subir
Datas no Protheus sao YYYYMMDD como string — usar A1_DTCAD >= '20260101'
RawQuery requer TOP injetado se voce nao colocar — o engine adiciona automatico

Fonte completo

Codigo AdvPL aberto (MIT, ~14KB): baixar McpQuery.prw.

Tutorial completo com arquitetura, casos reais e benchmarks: post no blog.

Exemplos

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'

Output: {"data":[{"A1_COD":"000001","A1_NOME":"ACME LTDA","A1_EST":"SP"}],"count":50,"hasMore":true}

Faturamento agregado por mes (rawQuery)

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

Output: {"data":[{"MES":"202601","TOTAL":"4828150.00"}],"count":12,"hasMore":false}