MCP ExecAuto: deixe sua IA criar pedidos, clientes e titulos no Protheus via MSExecAuto universal

Voce ja deve ter feito: cliente quer "automatizar a entrada de pedidos via planilha", ai voce cria uma User Function que le CSV, monta array, chama MATA410 via MsExecAuto, trata erro, faz rollback... e dois meses depois ele quer fazer o mesmo com cliente (MATA030), depois com titulo a pagar (FINA050). Voce duplica codigo cada vez.

O McpExecAuto.prw resolve isso de uma vez: um endpoint REST que executa qualquer MSExecAuto registrado, com conversao de tipos automatica, validacao de regras e rollback transparente. E como bonus: a IA passa a conseguir criar pedidos/clientes/titulos direto via Model Context Protocol.

O problema

Quem ja escreveu integracao com MSExecAuto sabe que tem 4 dores recorrentes:

1. Modelo 1 vs Modelo 3 confundem: MATA020 (fornecedor) usa cabecalho simples; MATA120 (pedido) usa cabec + itens; MATA410 (venda) tambem 3, mas com 6 parametros e PRIVATE l_MSExec3.
2. Conversao de tipos: JSON manda string, SX3 espera Character/Numeric/Date/Logical. Esquecer um PadR e o ExecAuto retorna "campo invalido" sem dizer qual.
3. Tratamento de erro: NomeAutoLog() existe mas o arquivo nao aparece imediato — tem race condition. Quem ja perdeu 2h debugando isso levanta a mao.
4. Rollback de numeradores: se erro no MATA410 voce precisa RollbackSX8(). Esqueceu? Numero 000001234 fica reservado pra sempre.

O McpExecAuto resolve as 4 dores em ~470 linhas AdvPL. Voce manda 1 JSON, ele executa.

Arquitetura

Na pratica

Listar rotinas disponiveis (auto-documentacao)

curl 'https://seu-protheus:8443/McpExecAuto/exec' \
  -X POST \
  -H "X-Admin-Key: SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"routine":"_LIST"}'

Retorna:

{
  "routines": [
    {"routine":"MATA020","description":"Fornecedor","model":1,"table":"SA2"},
    {"routine":"MATA030","description":"Cliente","model":1,"table":"SA1"},
    {"routine":"MATA010","description":"Produto","model":1,"table":"SB1"},
    {"routine":"MATA110","description":"Solic.Compra","model":3,"table":"SC1"},
    {"routine":"MATA120","description":"Pedido Compra","model":3,"table":"SC7"},
    {"routine":"MATA410","description":"Pedido Venda","model":3,"table":"SC5"},
    {"routine":"FINA050","description":"Contas Pagar","model":1,"table":"SE2"}
  ],
  "count": 7
}

Esse _LIST e function calling pattern — sua IA usa pra descobrir o que pode chamar.

Criar um cliente (Modelo 1)

curl 'https://seu-protheus:8443/McpExecAuto/exec' \
  -X POST -H "X-Admin-Key: ..." -H "Content-Type: application/json" \
  -d '{
    "routine": "MATA030",
    "operation": 3,
    "fields": {
      "A1_COD": "C99999",
      "A1_LOJA": "01",
      "A1_NOME": "ACME LTDA",
      "A1_PESSOA": "J",
      "A1_CGC": "12345678000199",
      "A1_EST": "SP"
    }
  }'

Resposta sucesso:

{
  "success": true,
  "routine": "MATA030",
  "operation": 3,
  "message": "Operacao executada com sucesso",
  "key": "C99999",
  "timestamp": "20260514 14:32:08"
}

Criar pedido de venda (Modelo 3)

{
  "routine": "MATA410",
  "operation": 3,
  "header": {
    "C5_CLIENTE": "C99999",
    "C5_LOJACLI": "01",
    "C5_TIPO": "N",
    "C5_CONDPAG": "001"
  },
  "items": [
    {"C6_PRODUTO":"P00001","C6_QTDVEN":10,"C6_PRCVEN":250.00,"C6_TES":"501"},
    {"C6_PRODUTO":"P00002","C6_QTDVEN":5, "C6_PRCVEN":480.00,"C6_TES":"501"}
  ]
}

A engine cuida do trabalho chato:

• Adiciona C5_FILIAL via xFilial()
• Converte 10 (number JSON) → 10 (numerico AdvPL com decimal SX3)
• Converte "C99999" → PadR("C99999", TamSX3("A1_COD"))
• Se der erro, RollbackSX8() automatico — o numero do pedido nao fica preso
• Se der sucesso, ConfirmSX8() e retorna C5_NUM via DbGoBottom

Seguranca

O McpExecAuto e privilegiado — ele cria/altera dados. Por isso a auth e diferente do McpQuery:

• X-Admin-Key obrigatorio via SuperGetMV("MV_MCPADMK") — sem chave configurada o endpoint retorna 401 e nao faz nada
• Operation restrita a 3-5 (inclusao, alteracao, exclusao) — qualquer outro valor 400 Bad Request
• Auditoria em duas linhas por chamada: [MCP-EXEC] [EXEC] antes + [MCP-EXEC] [SUCCESS/ERROR] depois com a chave gerada ou mensagem de erro
• Rollback transparente em qualquer falha — voce nao precisa lembrar de RollbackSX8() no caller

Quando NAO usar

• Rotinas customizadas (User Functions de cliente): o McpExecAuto so mapeia rotinas padrao TOTVS. Pra rodar uma U_MyExecAuto da casa, voce adiciona um case novo em GetRoutineConfig() — leva ~5 minutos.
• Workflow com aprovacoes: ExecAuto pula validacao de telas. Se sua regra exige aprovador X confirmar pedido, voce precisa de ponto de entrada antes do MATA410 ou usar API oficial do Protheus 12.1.2410+.
• Volume > 100 req/s: ExecAuto e single-thread por conexao DBAccess. Pra alta vazao, faca queue (RabbitMQ/Kafka) e consuma com 4-8 workers paralelos.

Caso real

Cliente do varejo (1.200 lojas, 80k pedidos/dia) implantou o McpExecAuto em janeiro/2026 pra integrar com:

• Bot WhatsApp (Twilio + Claude): cliente final pergunta "quero 5 unidades do produto X com entrega em SP", LLM monta JSON, McpExecAuto cria MATA410, retorna numero do pedido
• Marketplace integration (Hub Olist): webhook recebe venda, McpExecAuto roda MATA030 (cliente) + MATA410 (pedido) em transacao
• RPA fiscal: robo le PDF de boleto, McpExecAuto roda FINA050 pra incluir titulo SE2

Numeros pos-3-meses:

• 2.400 chamadas/dia em horario comercial
• Latencia p95 = 340ms (inclui Claude + parsing JSON + ExecAuto + commit SX8)
• 0 numeros de pedido perdidos por rollback faltando
• Custos de RPA cairam ~60% — substituiu 3 robos UiPath por 1 endpoint REST

Tabela comparativa

Proximos passos

• Baixe o fonte (~14KB, MIT)
• Configure MV_MCPADMK no appserver.ini com chave forte (use openssl rand -hex 32)
• Compile via TDS-VSCode ou claude-advpl-skill
• Teste com routine: "_LIST" primeiro
• Crie um cliente teste via MATA030 antes de mexer em rotinas que envolvem estoque

Quer integrar com Claude/ChatGPT/Gemini? Chama a gente pra uma demo. Mostramos a IA criando pedido em um Protheus de demonstracao em tempo real.