GeneXus MCP Server Guide

Este repositório reúne o conhecimento sobre o uso do GeneXus MCP Server, com foco no que já foi confirmado e no que ainda falta validar.

Fonte inicial

• GeneXus for Agents - Installation guide

Escopo desta documentação

Este material parte do cenário Windows Native, foco do guia oficial de instalação.

Objetivo

• Registrar a definição do servidor
• Registrar a localização exata na máquina
• Concentrar observações, validações e descobertas futuras em um único lugar
• Entender como usar o MCP com ou sem a IDE aberta

Organização acordada

Este repositório fica como base de conhecimento sobre o GeneXus MCP Server.

Há um workspace local separado para testes e artefatos de estudo, em C:\Dev\Test.

Este documento registra o estado atual do que já entendemos e o que ainda falta confirmar.

Regra prática:

• aqui ficam as anotações, decisões e explicações em .md
• o que vier da KB, o que for exportado e o que for preparado para importação fica no workspace de testes local
• artefatos de estudo não devem ficar misturados com a documentação permanente

Definição inicial

O GeneXus MCP Server é o backend local do GeneXus Next para integração com ferramentas e agentes. Na instalação validada, ele é atendido pelo executável GeneXus.Services.Host.exe.

Model Context Protocol (MCP) é o protocolo que permite a agentes se conectar a servidores que expõem operações controladas.

O guia oficial confirma que o servidor:

• já vem incluído no GeneXus Next
• fica disponível quando a IDE está em execução
• também pode ser executado diretamente a partir da pasta bl
• está disponível desde GeneXus Next 2026.01 e GeneXus 18 Upgrade 15
• permite, entre outras ações, criar e abrir Knowledge Bases, criar ou modificar objetos, definir rules, configurar propriedades e importar ou exportar objetos em texto

Localização no drive

O servidor fica na pasta bl da instalação do GeneXus Next.

O executável confirmado é GeneXus.Services.Host.exe.

Na instalação validada nesta máquina, o caminho absoluto do host é:

C:\Users\ANTONIOJOSE\AppData\Local\Programs\GeneXus\GeneXus Next\bl\GeneXus.Services.Host.exe

Arquivos de apoio

Com base no guia oficial, os arquivos locais mais relevantes para acompanhamento são:

• GXMBLServices.log, para monitorar a execução e interação do backend
• settings.json, criado por padrão em bl
• settings-overrides.json, para sobrescrever configurações sem alterar o arquivo padrão

Conexão com a CLI

O guia oficial mostra que o servidor expõe o endpoint http://localhost:8001/mcp e pode ser conectado à CLI compatível com MCP.

Como iniciar o servidor

O foco principal aqui é conseguir usar o GeneXus MCP Server sem depender da IDE aberta, sem excluir o uso misto quando ele fizer sentido.

Pelo guia oficial, existem dois modos úteis:

• iniciar a IDE, o que sobe o servidor automaticamente junto com ela
• iniciar apenas o backend local, executando GeneXus.Services.Host.exe a partir da pasta bl

Fluxo operacional recomendado

1. Abrir a instalação do GeneXus Next.
2. Entrar na pasta bl.
3. Executar GeneXus.Services.Host.exe.
4. Confirmar que o servidor respondeu no endpoint padrão.

Atalhos locais validados

Nesta máquina já existem atalhos no menu Iniciar para subir apenas o host:

• GENEXUS MCP, para abrir o host normalmente
• GENEXUS MCP MIN, para abrir o host minimizado

Esses atalhos aparecem na busca do Windows e apontam para GeneXus.Services.Host.exe.

Comportamento esperado ao iniciar

Ao abrir o host por atalho ou executando o .exe diretamente, é esperado que apareça uma janela de terminal.

Os sinais relevantes de inicialização correta são:

• GeneXus Services Host started. port:8001
• Now listening on: http://localhost:8001
• Application started. Press Ctrl+C to shut down.

Também é normal que a janela mostre logs de carregamento de pacotes e mensagens 404 em endpoints auxiliares de OAuth discovery.

A janela precisa permanecer aberta enquanto o servidor estiver em uso.

Como validar se está ativo

A forma prática de validação é confirmar que o endpoint MCP responde em:

http://localhost:8001/mcp

Também faz sentido observar o GXMBLServices.log, porque ele registra a execução e a interação do backend.

Critérios práticos de validação

• o processo do host está em execução
• o endpoint http://localhost:8001/mcp responde
• o GXMBLServices.log mostra inicialização sem erro de carregamento
• a CLI consegue se conectar ao servidor MCP

Validação MCP real

O endpoint não responde a um GET simples. Ele espera um cliente MCP com Accept: application/json, text/event-stream. Ao usar scripts, cuidado: a resposta pode chegar em SSE com prefixos event: e data:. Extraia as linhas data: e parseie o JSON contido nelas.

Na validação realizada:

• initialize respondeu com sucesso
• o servidor devolveu Mcp-Session-Id
• tools/list retornou as ferramentas GeneXus expostas

Isso confirma que o servidor está funcional como MCP, e não apenas escutando a porta.

Ao trabalhar com Knowledge Bases, é importante considerar que a KB aberta fica associada à sessão MCP que executou o open_knowledge_base.

Na prática, isso significa que abrir a KB em uma sessão não garante que outra sessão MCP já enxergue o mesmo estado aberto.

Como registrar no Codex Windows

O Codex local suporta MCP servers externos no arquivo de configuração do usuário. O registro deste servidor usa o alias gxnext.

codex mcp add gxnext --url http://localhost:8001/mcp

Uso diário

Fluxo mínimo para trabalhar com o GeneXus MCP Server:

1. Iniciar o host GeneXus.Services.Host.exe.
2. Confirmar que a porta 8001 está aberta.
3. Confirmar o handshake MCP com initialize.
4. Usar o servidor no Codex como gxnext.

Dica de ambiente: em scripts locais no Windows, use python3 sempre que disponível. O comando python pode apontar para Python 2 e causar erros de sintaxe ou encoding.

Se o initialize falhar com 406, o problema costuma ser o Accept da requisição e não necessariamente o servidor desligado.

Em operações de listagem, export_kb_to_text com listOnly:true pode concluir com sucesso sem devolver a lista de objetos no payload MCP.

Quando for necessário obter a listagem real de objetos, pode ser necessário exportar da KB para o filesystem de trabalho e ler os artefatos gerados.

Estado atual

• O GeneXus MCP Server pode responder em http://localhost:8001/mcp
• O host local é GeneXus.Services.Host.exe
• o caminho absoluto validado do host nesta máquina é C:\Users\ANTONIOJOSE\AppData\Local\Programs\GeneXus\GeneXus Next\bl\GeneXus.Services.Host.exe
• O servidor pode ser iniciado sem abrir a IDE
• há atalhos locais para abertura normal e minimizada do host
• O log relevante é GXMBLServices.log
• settings.json e settings-overrides.json fazem parte do apoio local

Termo de trabalho

Arquivo Textual de Objeto Genexus significa um arquivo .gx que representa textualmente um objeto GeneXus e que pode servir como fonte para leitura, estudo, exportação ou importação no fluxo MCP.

Workspace de testes

O workspace local para artefatos gerados e exportados é C:\Dev\Test\NextTest1. Essa é a pasta oficial de currentDirectory para todas as operações MCP com a KB NextTest1.

Estrutura interna:

Subpasta	Uso
ExportadosPeloGenexusMCP\	Exports feitos via MCP — Textual (src/src.ns) e estrutura física
ProntosParaImportacao\	Objetos validados prontos para import_text_to_kb
RascunhosGerados\	Rascunhos ainda não validados
Exemplos\	Exemplos de referência
Verify-*\	Pastas de verificação por objeto

Fluxo de build validado

O fluxo completo validado para uma KB com Transaction nova é:

1. open_knowledge_base com currentDirectory apontando para o workspace de testes
2. import_text_to_kb com os arquivos .gx prontos
3. build_all — requer prefer-offline=true e audit=false no ~/.npmrc
4. Verificar se o banco de aplicação já existe no LocalDB antes de qualquer operação de banco
5. create_or_impact_database com isCreate: false se banco existir com dados, isCreate: true se não existir
6. Subir a aplicação via dotnet GxNetCoreStartup.dll na pasta NetModel\web\bin

npm install travando o build

O build_all chama npm install para os UserControls do GeneXusUnanimo. Sem configuração adequada, esse processo trava indefinidamente.

Solução validada: adicionar ao ~/.npmrc:

prefer-offline=true

Em avaliação: audit=false também resolve, mas desativa verificações de segurança globalmente. Ainda não confirmado se prefer-offline=true sozinho é suficiente — validar no próximo build.

Pontos em aberto

• A ferramenta run do MCP não está funcional nesta versão — declarada no schema mas não implementada. Ver mcp-tools.md para detalhes e alternativa.
• Confirmar se prefer-offline=true sozinho no ~/.npmrc é suficiente para evitar o hang do npm install no build_all (em observação no próximo build)
• Procedure nova via MCP — PrcSaudacao foi importada com sucesso e está na KB, mas não gerou .dll durante o build_all. Possível timing issue (build rodou antes da spec processar o novo objeto) ou bug real. Requer novo build_all para validar se compila na próxima execução.

Validações concluídas

• Round-trip de WebPanel via MCP: export → edição do .layout.xml → import → build → resultado visível no browser ✅
• textblock no layout requer controlName além de name — sem ele o import falha ✅
• Encerrar o web app antes de buildar — processo segura .dll em NetModel\web\bin\ ✅
• Folder é tipo de objeto GeneXus criável via import_text_to_kb com arquivo de corpo vazio ✅
• Mover objetos entre pastas via MCP não funciona — nem via Folder em #Properties, nem via subdiretório; exclusivo da IDE ✅
• MCP não tem delete_object — objetos importados não podem ser removidos via MCP ✅
• WorkWith e WorkWithDevices — exportáveis via MCP, mas não reimportáveis: o validador rejeita tabs no YAML mesmo em arquivos gerados pelo próprio GeneXus; criação e edição exclusivas da IDE ✅
• BusinessComponent = true em #Properties exige minúsculo (TOML) — True maiúsculo causa erro de parsing ✅
• &bc.Load(Key) requer o PK como parâmetro — Load() sem parâmetro não é aceito pelo validador ✅
• Round-trip de objetos gerados pelo WorkWithWeb (WWxxx, ViewXxx, XxxGeneral) — são WebPanel/WebComponent comuns e suportam o fluxo padrão: export → edição do .layout.xml → validate → import → build → visível no browser ✅
• Round-trip de código .main.gx (não só layout) — editar eventos/rules em WebPanel funciona: Form.Caption alterado no Event Start, importado, compilado, mudança refletida no browser ✅
• execute.xml pode ficar bloqueado após build_all: o GeneXus reporta falha geral, mas o passo dotnet publish já ocorreu e os DLLs em bin\ estão atualizados — a aplicação serve as mudanças corretamente ✅
• Daemons GeneXus (SpecifierDaemon, GeneratorDaemon, ResidentBuilderDaemon) ficam órfãos após fechar a IDE e travam builds via MCP; solução: listar com Get-WmiObject Win32_Process e matar os PIDs com Stop-Process -Force antes do próximo build ✅
• WebPanel novo criado do zero via MCP — arquivo .webpanel.main.gx com mínimo de eventos/variables compila e gera DLL funcional ✅
• build_one e compile_object — não funcionam nesta versão do GeneXus; ambas retornam "Erro interno" sem detalhes; use build_all como alternativa ❌