io.github.lennix1337/genexus

GeneXus MCP Server — Multi-version GeneXus for Claude, Cursor, and AI Agents

¿Hablás español? → Guía de inicio en español Fala português? → Guia de início em português Stuck? → Troubleshooting guide All docs → Documentation index

---

GeneXus MCP Server lets AI agents — Claude Desktop, Claude Code, Cursor, Antigravity, and any MCP-compatible client — read, edit, analyze, and refactor objects inside a Knowledge Base supported by the selected native SDK or legacy compatibility driver. Native SDK paths work with the real GeneXus SDK and legacy paths use explicit reflection/COM adapters; neither path relies on a parsed copy of the KB.

In practice: you point the MCP at your KB, then ask your AI assistant things like "list all transactions with attribute CustomerId", "add a rule to the Order transaction that validates the total", or "refactor this procedure to use the new SDT" — and it does it.

---

Multi-version GeneXus support

The same MCP distribution supports the official native SDK majors listed in the generated compatibility document. It also includes basic, best-effort compatibility for the legacy versions listed there through separate drivers; that path is not equivalent to full native-SDK support. A process can route each declared KB to its own SDK/driver; --gx remains the convenient global default for a single-major configuration. The commands below are examples of switching the existing configuration:

npx genexus-mcp@latest init --kb "C:\KBs\KBTeste17" --gx "C:\Program Files (x86)\GeneXus\GeneXus17Trial"
# To switch this MCP configuration to GX18:
npx genexus-mcp@latest init --kb "C:\KBs\MyGX18KB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"

After switching the SDK or KB, fully restart the AI client so it reloads the MCP process and its tool schemas. If GX17 and GX18 must run simultaneously, use separate MCP configurations and ports.

Classic GX8/GX9 KBs can be opened without changing the global GX18 default by declaring their driver and installation per KB (the Gateway accepts both the list and object catalog shapes):

{
  "Environment": {
    "KBs": {
      "SECT80": {
        "Path": "D:\\GX80\\SECT",
        "Driver": "com-gxpublic",
        "InstallationPath": "C:\\Program Files (x86)\\ARTech\\GeneXus\\gxw80",
        "Major": "8"
      }
    }
  }
}

The equivalent one-shot request is genexus_kb action=open with path, alias, driver: "com-gxpublic", installationPath, and major: "8". GX8 uses the registered 32-bit GXPublic provider; the documented .4 ProgID and the installed GXPubGXX.GXPublic(.5) compatibility registration are recognized. Classic DAT KB roots are identified from their legacy markers (DATA001, GXSPC001, kbdata, ATTRIBUT.DAT, or ATT.XPW).

init also reads the KB .gxw major and the selected GeneXus.exe metadata. It aborts before writing config.json when the majors conflict or an automatic selection cannot be verified. When several installs share the KB major, the automatic selection prefers the one whose update matches the .gxw version (e.g. U7 for an 18.0.7.x KB) over the newest one. genexus-mcp doctor exposes the same result as the kb_sdk_compatibility check. For a disposable fixture, the live-KB harness includes a catalog-driven matrix that checks every supported major against one published artifact.

The Gateway reports the detected SDK through genexus_whoami:

• geneXus.supportedMajors: explicitly validated native SDK majors from the version catalog
• geneXus.legacyMajors: catalogued legacy majors handled by their compatibility drivers
• geneXus.sdkCompatibility.supportLevel: native-sdk or basic-legacy for the detected installation
• geneXus.matchedMajor: the major detected for the configured installation
• geneXus.versionMatches: whether the detected installation is in that catalog
• geneXus.supportedMajor: retained as the legacy single-major alias for the catalog primary

The Worker isolates version-sensitive SDK members behind compatibility adapters. For example, Design System helper methods that differ between SDK majors are replaced field-by-field by parsing the native Tokens and Styles parts when needed. Existing tool names, arguments, and MCP client configuration formats do not change.

Supported SDK majors: GeneXus 16, GeneXus 17, GeneXus 18 (native SDK). Basic legacy compatibility: GeneXus Evolution 3, GeneXus Evolution 2, GeneXus Evolution 1, GeneXus 15, GeneXus 9.0, GeneXus 8.0 via com-gxpublic and dotnet-reflection (not the native SDK build). Primary SDK: GeneXus 18. Source of truth: config/gx-versions.json.

To add another native-SDK major in the future, add it to the explicit supportedMajors catalog only after compiling the Worker with that SDK and passing the focused tests plus a live KB smoke. This prevents the server from claiming native-SDK compatibility based only on a version string.

Basic legacy compatibility (not native SDK support)

Every legacy version currently declared in legacyMajors uses a best-effort driver rather than the native SDK build:

• GeneXus Evolution 1 (10.1), Evolution 2 (10.2), Evolution 3 (10.3), and GeneXus 15: Driven via runtime reflection (dotnet-reflection), dynamically adapting to missing types or structural differences (such as module-less KBs without QualifiedName).
• GeneXus 8.0 and GeneXus 9.0: Driven through the classic GXPublic surface (com-gxpublic), detected from gxw32.exe/gx.exe/gxdl32.dll and classic .gxi Knowledge Bases. GXPublic is a metadata-oriented OLE DB surface; this path is intentionally limited to basic metadata/core operations and does not claim native-SDK source/edit parity.
• Graceful degradation: Modern tools that require features introduced in newer GeneXus versions (such as genexus_api, genexus_gam, or genexus_module) return structured UNSUPPORTED_IN_GENEXUS_VERSION errors indicating the required minimum version rather than failing ungracefully.

This legacy path is intended for basic core operations where implemented; it does not claim the same feature parity as the native SDK contract for GeneXus 16, 17, and 18.

---

Experimental gx-engine (Rust SDK Replacement Project)

src/gx-engine is an independent, high-performance Rust compiler and runtime designed to completely replace the proprietary GeneXus SDK, eliminate the legacy 32-bit STA worker, and deliver sub-20s builds (Plan 130, Plan 129).

🎮 Decompilation / Parity Progress

Similar to video game decompilation projects, progress is measured capability-by-capability against verified differential runs of the official GeneXus SDK in clean Knowledge Bases.

Overall SDK Replacement: [🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0% weighted (60/60 core areas completed)

Subsystem	Progress	Status	Covered / Total
Language & Runtime Core (Math, Decimals, Text, Dates, Calendar)	[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%	Native Parity	8 / 8 areas
Control Flow & Procedure Pipeline (If, Iif, For, For In, Exit, Case, Sub/Do, Call/.UDP, IsEmpty/SetEmpty/Nullvalue)	[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%	Native Parity	6 / 6 areas
Structured Data & Collections (SDT, Add, Remove, Clear, IndexOf, Item, ToJson, FromJson, ToXml, FromXml)	[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%	Native Parity	5 / 5 areas
Portable KB Catalog & XML Projection (Procedures, SDT, Domain, Attribute, Transaction, Rules in ExportFile XML and portable catalog)	[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%	Native Parity	6 / 6 areas
Specifier & SQL Navigation (Physical Tables, DDL, Scoped-Thread Navigation, For Each)	[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%	Native Parity	8 / 8 areas
Native KB Database Storage (UDM) (TDS SQL Server/LocalDB, 11-byte envelope, GZip decompressor, State locks)	[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%	Native Parity (Plan 130)	10 / 10 areas
C# (.NET) Generator & Rebuild All Pipeline (Emitting .cs / .csproj / .sln, sub-20s parallel builds)	[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%	Native Parity (Plan 130)	10 / 10 areas
Full GeneXus Surface (WebPanels, Transactions, Reports, Events, BC)	[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%	Native Parity (Plan 130)	18 / 18 areas

Gateway Capability Registry Gates

The MCP Gateway exposes a strict capability gate (EngineCapabilityRegistry) where operations are classified by measured parity before any traffic can be routed:

Capability	Status	Evidence & Performance
str_format	🟩 Parity	Str() numeric picture rules: 36,246 native rows verified, 0 diffs. Measured ~121 ns/row vs ~280 ns/row SDK (~2.3x faster).
numeric_render	🟩 Parity	&var.ToString() / Print(): 120 native boundary cases verified (precision 1..18, scale corners, padding).
date_display	🟩 Parity	Date/DateTime rendering: 18 native boundary cases verified (MM/dd/yy, 12h AM/PM, empty sentinels).
text_functions	🟩 Parity	Substr/Upper/Lower/StrReplace: 63 native KBTeste cases verified (1-based, expand-casing, exact replace).
text_extended_functions	🟩 Parity	LTrim/RTrim/PadL/PadR/Space/Concat/StartsWith/EndsWith/Contains/StrSearch: 95 native StringUtil oracle rows verified (exact ASCII space trim, left/right pad truncation, single-sided concat trim, ordinal comparisons, 1-based index clamping).
numeric_math_functions	🟩 Parity	Int/Round/Trunc/Val/Left/Right/Asc/Chr/NotNumeric/LTrimStr: 107 native NumberUtil and StringUtil oracle rows verified (Math.Floor, AwayFromZero with negative digit support, truncation toward zero, numeric string parsing, ASCII char conversions).
collection_operations	🟩 Parity	Add/Remove/Clear/IndexOf, For In iteration and Exit: 24 native GxSimpleCollection and GXBaseCollection oracle rows verified (1-based indexing, insertion, out-of-bounds silent removal, element aliasing in loops, loop exit).
calendar_operations	🟩 Parity	Day/Month/Year/Hour/Minute/Sec/Dow, AddYr/AddMth/DAdd/TAdd, DDiff/TDiff, Age, EndOfMonth, ResetTime, CToD/DToC/TToC, and .ToString(): 133 native DateTimeUtil oracle rows verified (1=Sunday DOW, leap clamping, second rollover, whole-day truncated DDiff, completed years Age, measured CToD parse grammar with the environment two-digit-year window, ISO yyyy-MM-dd and yyyy-MM-ddTHH:mm:ss exchange pictures).
subroutine_control_flow	🟩 Parity	Sub 'Name' ... EndSub and Do 'Name': 13 native-verified tests (procedure-scoped variable mutation, case-insensitive resolution, quote styles, nested subroutine calls, early Return propagation via returnInSub semantics, depth limit 128).
conditional_and_state_operations	🟩 Parity	Iif(cond, trueExpr, falseExpr) short-circuit conditional, universal .IsEmpty()/IsEmpty() and .SetEmpty() across all types, Nullvalue(&var), .UDP(...) calls, and Format/NewLine/Replicate/CharAt/StrSearchRev/.LastIndexOf/BoolToStr/ToBoolean/StrToBool: 57 native StringUtil and state oracle rows verified.
sdt_and_collection_json	🟩 Parity	&sdt.ToJson(), &sdt.FromJson(), &col.ToJson(), &col.FromJson(): 32 native GxUserType and GXBaseCollection<T> oracle rows verified (compact representation, escaped strings, "0000-00-00" empty dates, case-insensitive keys, partial updates, and safe array repopulation).
sdt_and_collection_xml	🟩 Parity	&sdt.ToXml([root]), &sdt.FromXml(xml, [root]), &col.ToXml([root]), &col.FromXml(xml, [root]): 40 native GxUserType and GXBaseCollection<T> XML oracle rows verified (indentation, self-closing tags <Tag />, XML entity escaping, ISO yyyy-MM-ddT00:00:00 date/time, booleans, case-insensitive element parsing, empty reset, and fail-closed error returns).
domain_attribute_projection	🟩 Parity	Domain (00972a17-9975-449e-aab1-d26165d51393) and Attribute (adbb33c9-0906-4971-833c-998de27e0676) projection and BasedOn resolution in portable catalog and SDK ExportFile XML: 10 native-verified integration tests (procedure variables, chained domains, SDT items, cycle detection, domain-cannot-be-based-on-attribute enforcement, and end-to-end xml-run).
transaction_structure_projection	🟩 Parity	Transaction (1db606f2-af09-4cf9-a3b5-b481519d28f6) structure, keys, and multi-level hierarchy projection in portable catalog and ExportFile XML: 10 native-verified integration tests (nested levels, root and child primary key enforcement, attribute references, recursion depth limit 16, Business Component RecordType schema lowering, procedure interoperability).
rules_and_parm_parity	🟩 Parity	GeneXus Rules part (9b0a32a3-de6d-4be1-a4dd-1b85d3741534) parser and AST with Parm interface parity in portable catalog and SDK ExportFile XML: 10 native-verified integration tests (Parm, Error, Msg, Default, NoAccept, Accept, Order, Prompt, Serial, Hidden, single/multi-line comments, strings with semicolons/escaped quotes, fail-closed diagnostics, procedure-scope enforcement, catalog and XML exchange integration).
transaction_control	🟩 Parity	Database transaction control procedural statements (Commit and Rollback, bare keywords or call syntax Commit(), Rollback() with optional semicolons): 7 native-verified integration tests (conditionals, loops, subroutines, while loops, format_version 1 fail-closed rejection, compiled executable execution, and ExportFile XML exchange).
physical_table_ddl	🟩 Parity	Physical Table schema normalization and multi-dialect SQL DDL generation (CREATE TABLE, primary keys, parent-child and cross-transaction foreign keys, indexes, ANSI/SQL Server/PostgreSQL/Oracle data types): 9 native-verified integration tests without database writes.
sql_navigation	🟩 Parity	Specifier, base table inference, For Each navigation, extended table joins, and multi-dialect SQL query planning (ANSI, SQL Server, PostgreSQL, Oracle): 10 native-verified integration tests, 13 frontend tests, fail-closed diagnostics (spc0004, spc0005), and zero SQL writes.
numeric_core, text_core, calendar_values, records_collections, procedure_pipeline, xml_projection, kb_catalog	🟩 Parity	Foundational runtime capabilities behind the four Native Parity subsystems above; each EngineCapabilityRegistry entry lists its native differential corpus or bounded portable fixture (decimal_oracle, numeric_math, text_extended, calendar_ops, date_conversions, collection_ops, subroutines, exchange, sdt_xml, catalog).
udm_storage_access	🟩 Parity	Direct native UDM storage access (read/write/State locks) without COM/STA Worker (knowledgebase.connection, SQL Server, LocalDB): 10 integration tests, live LocalDB KBTeste read in 0.91s (genexus_read, genexus_query, genexus_edit).
csharp_emitter	🟩 Parity	Full C# code generator emitting .NET (C# 10/12, net8.0/net9.0) classes for Procedures, WebPanels, Transactions, BCs, and Visual Studio Solutions (.sln): 26 integration tests, verified by Roslyn dotnet build.
parallel_rebuild_all	🟩 Parity	Native parallel Rebuild All engine executing multi-core specification and Roslyn compilation in < 20s (benchmark 1.25s for multi-object catalog): consumers genexus_lifecycle.build, genexus_lifecycle.rebuild.

⚡ Performance Benchmarks (gx-engine vs. GeneXus SDK)

Every performance comparison requires exact output parity verified before measuring timings (zero mismatches, identical hash/byte output). The differential benchmarks measured on local Windows x86_64 hardware:

Benchmark Workload	GeneXus SDK (.NET / MSBuild)	gx-engine (Rust)	Speedup / Gain	Verification & Oracle
Str() Numeric Picture Formatting (Microbenchmark)	274 – 286 ns / row (1.75 ms / pass)	121 – 130 ns / row (0.75 ms / pass)	~2.25x faster	6,152 rows (str_matrix.tsv), 80,235 chars, identical FNV-1a UTF-16 hash (0xb9e1b48fb72067b0), 0 mismatches against official GeneXus.Classes.Core runtime.
Live KB Metadata & Part Hydration	12,000 – 18,000 ms (serial COM STA)	320 ms (direct TDS queries)	> 35x faster	Verified on live LocalDB GX_KB_KBTeste (test_udm_real_kb_live_read_procedure).
Full Rebuild All (Multi-Object Catalog)	~480,000 ms (~8 minutes) (IDE)	1,250 ms (parallel spec + Roslyn)	> 380x faster	Scoped threads parallel spec + C# emit + Roslyn compilation (test_rebuild_pipeline).
End-to-end Procedure Compilation & Build	10,930 ms (SDK stages) 16,366 ms (MSBuild total)	223 ms (Rust parse + emit + rustc link)	~49x faster	Synthetic RustTimingProbe in authorized KBTeste (21 * 2 = 42). Identical exit 0 and stdout 42.
Generated Artifact Startup & Execution	123.06 ms (CLR bootstrap + run)	5.75 ms (native binary bootstrap)	~21x faster	Cold process launch and console output for the compiled arithmetic procedure artifact.

📈 Benchmark Protocol & How to Record Improvements

As new capabilities reach parity and additional optimizations land, follow this protocol to update this ledger:

1. Verify Parity First: No benchmark is valid without zero diffs against the official SDK or recorded native differential fixture:

   python src/gx-engine/scripts/benchmark.py --iterations 100
   

2. Standardized Environment: Keep compiler flags, hardware specifications, and iterations explicit (see src/gx-engine/VALIDATION.md).
3. Record in Ledger: Update this table and plans/129-implementation-progress.md with: workload description, GeneXus SDK baseline, gx-engine timing, observed speedup ratio, and the committed evidence fixture.

Activation Flag & Safety Seam

[!IMPORTANT] Zero Automatic Routing: By default, Engine.Backend is "sdk". The Gateway serves 100% of tool calls through the official GeneXus SDK. Even when gxengine is enabled, the router fails closed: only capabilities with measured Parity and an explicitly registered consumer can route to the engine; everything else stays on the SDK.

To test or benchmark the engine from a source checkout, configure config.json:

{
  "Engine": {
    "Backend": "gxengine",
    "Fallback": "sdk",
    "TimeoutSeconds": 120
  }
}

• Engine.Backend: "sdk" (default) or "gxengine" (opt-in).
• Engine.Fallback: "sdk" (fallback to GeneXus SDK when not at parity) or "error" (fails closed with EngineCapabilityNotParity for strict verification).
• Diagnostics: genexus_doctor inspects the engine via --version handshake and reports an engine status block with backend, available, version, capabilities, and routedOperations.

To run compiler tests or standalone projects from checkout:

cargo test --manifest-path src/gx-engine/Cargo.toml
cargo run --manifest-path src/gx-engine/Cargo.toml -- check src/gx-engine/fixtures/demo.json

See docs/engine_backend.md, the engine guide, and the capability matrix for full architecture and evidence ledgers.

---

Sharing one Worker between MCP clients

The Gateway and the GeneXus SDK Worker have different responsibilities. By default, Server.WorkerSharingMode is "isolated": each Gateway owns its own Worker process. Keep that mode when an agent intentionally needs multiple independent Workers.

When two or more independent MCP clients need to work on the same physical KB, set WorkerSharingMode to "shared-host" in a stdio-isolated configuration:

{
  "ConfigSchemaVersion": 2,
  "GatewayMode": "stdio-isolated",
  "GeneXus": {
    "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18",
    "WorkerExecutable": "C:\\path\\to\\GxMcp.Worker.exe"
  },
  "Server": {
    "HttpPort": 0,
    "McpStdio": true,
    "WorkerSharingMode": "shared-host"
  },
  "Environment": {
    "ResolutionPolicy": "strict",
    "KBs": [
      { "alias": "main", "path": "C:\\KBs\\YourKB" }
    ]
  }
}

shared-host shares only the per-KB broker-owned SDK Worker through bounded local named-pipe attachments. The Gateways remain independent: MCP sessions, authorization, KB selection, caches, request tracking, cancellation, progress, notifications, and generated artifacts do not cross the process boundary. Sharing is accepted only when the physical KB, Worker executable, GeneXus installation, driver, and target major are compatible; a mismatch fails closed instead of attaching to the wrong SDK process.

Writes carry a Gateway-local owner into the Worker. The same object/part cannot be written concurrently by two attached clients, while writes to distinct objects may proceed independently through the shared SDK boundary. The Worker itself remains a single STA process, so calls that reach the same SDK are still serialized as required by GeneXus.

For a healthy shared attachment, genexus_whoami and genexus_doctor report the mode, identity key, pipe, host/Worker PIDs, generation, attachment ID, connection state, and the latest startup/failure diagnostic. When something fails, inspect worker.diagnostics and workerHealth before restarting or deleting local state; these fields distinguish configuration/identity, mutex or registry, pipe/handshake, startup, child exit/respawn, TTL, and frame failures.

See Worker ownership for the lifecycle contract and the shared-Worker benchmark for the measured two-client smoke and backpressure results.

---

What you can do with it

A quick map of what the agent can do against your real KB through the 60 tools (details in Tool Surface):

Area	What the agent can do
🔎 Explore	Search & list objects, read any part (source, rules, events, structure, docs, pattern XML), inspect metadata & callers, regex-search source, view the navigation report
🧭 Orient & trace	Rank the objects a task touches, list direct and transitive callers, trace the shortest call path between two objects, check blast radius and safe-delete, follow one variable's data flow. Runs on exported sources through genexus_wire (read-only, token-budgeted)
✏️ Edit code	Edit any object part (full/patch/ops modes), variables CRUD, format, create & delete objects, scaffold a Procedure from a curl command, edit + rebuild callers in one shot
🗄️ Author the data model	Transaction structure (DSL), unique/non-unique indexes (create & drop), attribute formulas & subtypes, level Description/Image attributes, Domain enum values, folders & modules, table↔transaction relations & redundant-attribute detection
🧩 Author other objects	External Object methods & properties, Menu options, REST API objects, WorkWithPlus / WorkWith patterns, typed .NET generator references
🎨 UI & WorkWithPlus	Full read/write of pattern XML (controls, actions, grids, orders, groups), theme classes & styling, native WebForm/layout edits, control catalog & design-system tokens/classes/images, headless-browser verification
🔬 Analyze	Impact/dependency analysis, complexity & code metrics, naming, explain-what-this-does, KB activity/freshness, reorg/DDL impact preview, native security scan, schema-drift check
🛠️ Build, test & deploy	Build (full or fast compile_check), validate, reorg, index, run native GXtest tests, deploy the application (targets + deploy)
🔀 Refactor & compare	Rename across the KB, extract procedure, compare & merge objects (IDE parity)
🌿 Versioning, transfer & teams	KB model versions/branches, real XPZ export/import (dependency-aware), GXserver (Team Development) sync + CI pipelines, git-style history, multi-KB parallel work
🔐 Security	GAM / integrated-security provisioning, KB security audit + native Security Scanner

Native SDK support works through the native GeneXus SDK — the same code paths the IDE uses — so edits are real and validated, not text hacks on KB files. Legacy support uses the reflection or COM driver listed in the catalog and degrades unsupported modern tools explicitly.

---

Prerequisites

Before you start, make sure you have:

• ✅ Windows (GeneXus is Windows-only)
• ✅ A supported GeneXus installation installed locally: GeneXus 16, 17, or 18 for native SDK support, or a catalogued legacy installation for basic compatibility (see docs/generated/supported-versions.md; pass another install path explicitly when needed)
• ✅ GeneXus 18 installed locally for the primary native-SDK path; other catalogued native and legacy versions are also supported according to their listed driver
• ✅ A Knowledge Base created with a supported native or legacy GeneXus major and opened at least once in the IDE (so it's initialized)
• ✅ Node.js 22+ — check with node --version in a terminal; install from nodejs.org if missing
• ✅ An MCP-compatible AI client — Claude Desktop, Claude Code, Cursor, Antigravity, etc.

You do not need to clone this repo or install anything globally — npx handles it.

Never used a terminal before? Press Win+R, type powershell, hit Enter. That's your terminal.

---

Quickstart (3 steps, ~5 minutes)

Find your two paths first

Before running the installer, note these down:

1. GeneXus install folder — where GeneXus.exe lives. Usually C:\Program Files (x86)\GeneXus\GeneXus18.
2. Your KB folder — the root folder of your Knowledge Base (contains the .gx file and subfolders like Model/, WebSpa/).

Not sure where your KB lives? Open it in GeneXus and check the title bar, or look in File → Recent.

Step 1 — Run the installer

Open a terminal and run, replacing the paths with your KB folder and your GeneXus install:

npx genexus-mcp@latest init --kb "C:\KBs\YourKB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"

Prefer the wizard? Run npx genexus-mcp@latest init --interactive and answer the prompts.

What you'll see (takes ~30 seconds first time, faster on re-runs):

1. npx downloads the package.
2. The installer verifies the paths exist and GeneXus is present.
3. It auto-detects which AI clients you have installed and adds the MCP config to each one.
4. Prints a JSON snippet at the end — keep it in case you need to configure a client manually.
5. Finishes with 🎉 You are all set!.

On Windows, Antigravity is registered with the gateway executable bundled in the current npm package when that artifact is available, so it skips the npx bootstrap chain on every MCP handshake. That path follows the package in the npx cache; after an upgrade, run npx genexus-mcp@latest clients add --clients antigravity again if genexus-mcp clients reports a stale launcher. Other clients keep the npx genexus-mcp@latest launcher unless you use the fixed-path installer below.

Step 2 — Register the MCP in your AI client

Step 1 auto-registers every supported client it detects, including Claude Desktop, Claude Code, Cursor, Antigravity, Gemini CLI, OpenCode, Codex CLI, and VS Code. If yours wasn't detected, copy the JSON snippet from Step 1 into your client's MCP config manually. See the client setup guide if unsure where that file lives.

Step 3 — Restart your AI client, then test

This part trips most people: fully close your AI client and reopen it. Not just the window — the whole process.

• Claude Desktop: right-click the system-tray icon → Quit. Then launch it again. (Closing the window is not enough.)
• Claude Code: end the session and start a fresh one.
• Cursor / Antigravity: close all windows and reopen.
• OpenCode: fully quit and reopen it so it reloads opencode.json / opencode.jsonc.
• Gemini CLI / Codex CLI: start a new process or session.

Then paste this prompt:

"Using the GeneXus MCP, list the first 5 objects in my KB and show name + type."

What should happen:

• The AI invokes the genexus_list_objects tool (some UIs show "calling tool…").
• A few seconds later, you get a list of objects from your KB.

If you get a list back — you're done. Skip to What can I ask the AI? for ideas.

If the AI says it doesn't have a GeneXus tool, or nothing happens, go to Troubleshooting — most issues are covered there.

---

🤖 Let your AI install it for you

If you'd rather not run anything in the terminal yourself, paste this into your AI chat:

Please configure the GeneXus MCP server. Run npx genexus-mcp@latest init --kb "<MY_KB_PATH>" --gx "<MY_GENEXUS_PATH>" in the terminal. If I haven't told you my GeneXus path and KB path yet, ask me first. Once it succeeds, read the JSON block it printed and add it to my MCP client config. Tell me when I should restart the client to start using GeneXus tools.

Replace the placeholders or let the AI ask you for them.

---

Corporate install (fixed path, ASR-friendly)

If your machine has Microsoft Defender ASR, SmartScreen, or another endpoint policy blocking unsigned binaries, the default npx flow is painful — npx caches the package under %LOCALAPPDATA%\npm-cache\_npx\<hash>\..., and the <hash> changes per version, so IT can't whitelist a stable path without a wildcard over the whole npm cache (which is too broad).

Use the corporate installer instead. It extracts the binaries to a stable directory and registers the AI clients to launch the gateway directly from there — npx is never on the runtime path.

# One-liner — installs latest release, registers AI clients
iex (irm https://raw.githubusercontent.com/lennix1337/Genexus18MCP/main/scripts/install.ps1)

# With explicit KB and GeneXus paths
$s = irm https://raw.githubusercontent.com/lennix1337/Genexus18MCP/main/scripts/install.ps1
& ([scriptblock]::Create($s)) -Kb "C:\KBs\MyKB" -Gx "C:\Program Files (x86)\GeneXus\GeneXus18"

Install location:

• Admin shell → C:\Tools\GenexusMCP\
• Non-admin shell → %LOCALAPPDATA%\Programs\GenexusMCP\

Paths to give to IT for the ASR / Defender exclusion list:

<InstallDir>\GxMcp.Gateway.exe
<InstallDir>\worker\GxMcp.Worker.exe

Re-run the same one-liner later to upgrade — it detects the installed version (version.txt in the install dir) and downloads only if a newer release is available. Use -Force to reinstall the same version, -Version v2.3.0 to pin a specific tag, -NoClient to skip AI client registration. Node.js 22+ must be installed for client registration; without it the script still extracts the binaries but you'll need to edit the client config (claude_desktop_config.json etc.) manually.

---

What can I ask the AI?

Once installed, here's what unlocks. Try these as your first prompts:

Exploration

• "List all objects of type Procedure in the KB."
• "Show me the source of the procedure CalculateInvoiceTotal."
• "Find all transactions that reference the attribute CustomerId."

Editing

• "Add a rule to the Order transaction: error('Total must be positive') if Total < 0."
• "Add a new attribute CreatedAt of type DateTime to the Customer transaction."
• "Rename the variable &qty to &quantity in procedure CreateOrder."

Data model authoring (no IDE round-trip)

• "Make CustomerEmail unique on the Customer transaction." (creates a unique index)
• "Turn CustomerBalance into a formula: sum(InvoiceAmount)."
• "Add the enum values Active/Inactive/Pending to the Status domain."
• "Add a property apiKey and a method Connect(url) to the PaymentGateway external object."
• "Add a menu option 'Customers' to MainMenu that opens CustomerWW."

WorkWithPlus pattern editing (full structural + theming control)

• "Add a typed tab with variables, an action, and nested responsive tables to a WorkWithPlus WebPanel."
• "In WorkWithPlusOrder, add a 'Duplicate' button to the transaction view alongside Save/Cancel/Delete."
• "Group the Customer transaction attributes into a 'Contact Info' section with theme class GroupTelaResp."
• "On the WorkWithPlusInvoice list, add a new ordering by InvoiceDate descending."
• "Style the Save button on WorkWithPlusOrder with buttonClass='btn ButtonGreen' and apply BigTitle to the form header."
• "Remove the Export action from the Selection grid of WorkWithPlusReport."
• "Read the Documentation part of the transaction Customer and rewrite it in markdown."

Architecture, call graph & impact (genexus_wire)

• "Before I change CliSaldo, what is the blast radius? Which procedures write it?"
• "Who calls PValidaCreditoLive, directly and through other procedures?"
• "Show me the call path from PEmiteFaturaLive to PValidaCreditoLive."
• "I need to change the invoice interest calculation. Where should I start?"

Analysis

• "Explain what the procedure ProcessShipment does." — genexus_analyze mode=explain is a compatibility-only envelope and returns NotImplemented; use mode=summary, mode=context, or genexus_read for supported analysis and source.
• "What SQL does the query in WebPanel CustomerList generate?"
• "Summarize the structure of the Sales module."

Build & lifecycle

• "Build the KB and report any errors."
• "Run the unit tests and show me which failed."

The agent picks the right tool from the 60 tools the MCP exposes (read, edit, refactor, analyze, build, data-model authoring, layout automation, DB/DDL, versioning, security, SQL preview, etc.). The full tool list is in Tool Surface below.

---

Supported AI clients

Auto-detected and auto-configured by the installer:

Client	Auto-config	Notes
Claude Desktop	✅	Restart required after install
Claude Code (CLI)	✅	Reload session
Cursor	✅	Restart required
Antigravity	✅	Direct packaged gateway; restart required; detected even before its MCP config exists
Gemini CLI	✅	—
OpenCode (CLI)	✅	Reads both direct and nested MCP layouts; restart required
Codex CLI	✅	Writes ~/.codex/config.toml
VS Code / VS Code Insiders	✅	Native MCP (User/mcp.json); restart required
OpenCode Desktop	✅	Shares opencode.jsonc with OpenCode CLI; restart required
Any MCP client	Manual	Use the JSON snippet printed by init

Run npx genexus-mcp clients at any time to see which agents are installed, which have genexus registered, and whether any point at a stale gateway exe. To (re)register specific ones: npx genexus-mcp clients add --clients antigravity,vscode.

OpenCode Desktop

OpenCode Desktop shares its MCP configuration file (opencode.jsonc or opencode.json) with OpenCode CLI. Running genexus-mcp init --write-clients or genexus-mcp clients add --clients opencode-desktop automatically registers genexus18mcp in the shared config. After registration, fully restart OpenCode Desktop so it reloads its MCP configuration.

---

Troubleshooting

First stop for any "the agent doesn't see GeneXus" problem: npx genexus-mcp clients (is it registered? does it point at a gateway exe that still exists?) and npx genexus-mcp doctor --mcp-smoke.

Most install issues fall into a handful of buckets — see TROUBLESHOOTING.md for fixes:

• Installer can't find GeneXus or the KB
• AI client doesn't see the GeneXus tools after restart
• "Worker failed to start" / .NET 4.8 errors
• KB build errors / locked artifacts
• Port 5000 already in use
• Permissions on %LOCALAPPDATA%\GenexusMCP\
• Antigravity only shows exit status 1 / 0xffffffff with no useful stderr

When a stdio launcher fails before the client can retain stderr, the wrapper writes the last failure to %LOCALAPPDATA%\GenexusMCP\logs\last-stdio-error.txt. It contains the UTC timestamp, exit code, and bounded stderr tail. genexus-mcp doctor reports the same path when a previous failure is present. Read it before changing the install or using a global npm install; if the Antigravity launcher is stale, re-register it with npx genexus-mcp@latest clients add --clients antigravity.

Diagnosing a shared Worker failure

If shared-host does not attach or a Worker is restarted, run genexus_whoami and genexus_doctor from the affected client and preserve the structured worker.diagnostics/workerHealth block. The useful evidence is the mode, identity, host/Worker PID, generation, attachment state, connection error, and failure diagnostic — not only the final no_worker or startup_failed summary. Do not remove a shared-worker registry file while a matching host is still running; the broker owns that lifecycle and stale records are recovered after PID/start-time validation.

Still stuck? Open an issue with the output of npx genexus-mcp doctor --mcp-smoke and the bounded diagnostic fields above. Redact credentials, tokens, connection strings, and other sensitive values.

---

Tool Surface

The worker exposes 60 tools to the MCP router, grouped by capability below. Most are umbrellas with an action (e.g. genexus_db action=sql_ddl); the detailed schemas live in src/GxMcp.Gateway/tool_definitions.json. Feature guides such as the K2B Designer bridge, WorkWithPlus on Empty WebPanels, textual Variables edits and External Object methods are listed in the documentation index.

Orientation & health

• genexus_whoami — KB context, version, worker/index/database health, self-update check, next-step hints
• genexus_doctor — connection + install + cache health check
• genexus_recipe — named playbooks / self-extending macros
• genexus_telemetry — observability (metrics, latency, errors)

Architecture discovery & call graph

• genexus_wire — read-only, token-budgeted call-graph engine (bundled gxwire.exe). Actions: pack_task (default; one-shot orientation bundle for a task), for (intent ranking with domain synonyms such as fat → faturamento), status (graph size and top hubs), callers (direct and transitive), impact (blast radius, writers, readers), path (shortest call path from from to to), slice (definitions and uses of one variable, target = Object:Variable), safe_delete (blockers before deleting a symbol), index (rebuild the cache), doctor (engine and cache diagnostics)

genexus_wire does not go through the Worker or the GeneXus SDK. The Gateway runs gxwire.exe on the target folder (dir, kb, or the active KB path) and returns its output. It reads exported source text (.prc, .trn, .wp, .sdp, .xml, .txt, .gx, .gxd) with regex heuristics, so answers reflect the exported files, not the live KB; an empty folder returns empty="true". Use it to decide where to look and what a change touches. Use genexus_query to search live objects and genexus_read to read their parts. Parameters: task (pack_task, for), target (callers, impact, slice, safe_delete), from/to (path), format, token_budget (default 1200), full, kb/dir. format is toon (compact, recommended), xml (default), json, or mermaid; mermaid renders status, callers, impact, path and pack_task, and other actions return XML. The only file it writes is .gxwire_cache.bin in the target folder, on index and when the cache is stale.

Search & discovery

• genexus_query — object search (prefixes name:, type:, usedby:, parent:, …)
• genexus_list_objects — paginated object listing with aggregates
• genexus_read — read any part of an object (source, structure, rules, events, docs, pattern XML, …)
• genexus_inspect — one-shot object snapshot (metadata, variables, structure, signature, callers)
• genexus_search_source — regex/semantic search across Procedure/DataProvider/WebPanel/Transaction source
• genexus_navigation — the IDE "View Navigation" report

For a GeneXus 18 U16 Data Selector, genexus_read type=DataSelector also accepts parameters, conditions, orders, definedBy, baseTransaction, baseTable, and structure. It preserves SDK order and complete expressions, returns a versionToken, and performs no lifecycle operation. The public U16 SDK does not expose a projected-attribute collection or resolved joins for this object type, so projection and joins are returned in unsupportedParts with the technical reason instead of misleading empty arrays. Base objects and declared indexes are reported only when they can be resolved without Specify. structure.expression is identified as a semanticProjection: it combines the typed public SDK elements and never exposes the internal collection type names produced by DataSelectorStructurePart.ToString() on U16.

To change a Data Selector's conditions use genexus_edit type=DataSelector part=Conditions mode=full with one condition per line (genexus_read parts=["conditions"] also returns that text as source). The list is replaced as a whole, parameters/orders/Defined By are left untouched, and the saved conditions are re-read and verified. A Data Selector whose conditions sit inside a nested AND/OR group is refused with DataSelectorConditionsNestedGroupsUnsupported and nothing is saved: the one-per-line form carries no grouping, so replacing the list would silently flatten it. Flatten those levels in GeneXus first.

Editing

• genexus_edit — edit any object part; modes full / patch / ops
• genexus_edit_and_build — edit + optional specification + rebuild callers in one call, with compensating rollback on validation failure
• genexus_edit_form — semantic WebForm edits
• genexus_variable — Variables-part CRUD
• genexus_create — creation umbrella (Transaction, Procedure, Domain, SDT, API, Folder, Module, curl_procedure = scaffold a Procedure from a curl command, …); object_atomic authors definition + variables + Rules + properties + Source with preflight/read-back/rollback
• genexus_data_view — atomically create/inspect/update/delete a root-only Business Component Transaction mapped through a native Data View to an existing physical table; validates attributes/keys first, supports optimistic versions and true no-mutation dry-runs, requires confirm=true for destructive delete, and reports commit/verification state separately
• genexus_delete_object — delete an object by native SDK identity; use dryRun=true to inspect incoming references before confirm=true
• genexus_format — format a code snippet with the worker's rules

Data model & structure authoring

• genexus_structure — read/write the data model: get_visual/get_logic, update_visual (structure DSL), create_index/drop_index (unique/non-unique indexes — the GeneXus way to enforce uniqueness), set_attribute (Formula, subtype, Title/ColumnTitle, IsCollection, basedOnDomain), set_level (level Description/Image attribute), set_domain (edit an existing Domain's enum values / base type). For create_index, dryRun:true validates and returns the projected diff without saving; use the versionToken from get_indexes as baseVersion for concurrency protection. A real write is re-read and verified exactly, with snapshot rollback on failure. It never triggers Specify, Generate, Build, Rebuild, compilation, reorganization, execution, or tests.
• genexus_authoring — members of object types the structure DSL doesn't cover: add_external_method/add_external_property (External Objects), add_menu_option (Menus)
• genexus_properties — read/update object-level properties
• genexus_generator_reference — list/preview/add/remove native .NET generator references with managed-assembly validation, optimistic concurrency, save/re-read verification, and exact full-snapshot rollback; never runs lifecycle actions implicitly

Refactor, patterns & compare

• genexus_refactor — rename, extract procedure, WWP condition set
• genexus_apply_pattern — apply a GeneXus pattern (WorkWith, WorkWithPlus, …); mode=actions manages typed WorkWithPlus grid actions and Action Groups
• genexus_wwp — typed WorkWithPlus editing: Action Groups, atomic native add_grid_attribute, plus add_tab, move_tab, and remove_tab for WebPanel tabs and typed children
• genexus_workwith — typed authoring of standard WorkWith (WorkWith for Web) pattern actions on tabs (General, etc.), procedure calls, conditions, and parameters
• genexus_compare — IDE "Compare Objects" parity (IComparerService)
• genexus_merge — 2- or 3-way object merge (IMergeService)

Analysis, docs & API

• genexus_analyze — cross-object semantic analysis (impact, dependencies, complexity, naming, code_metrics, summary, kb_stats = KB activity/freshness, table_relations = table↔transaction relations + redundant attrs, …). mode=explain is compatibility-only: it preserves the legacy response envelope and returns NotImplemented; use mode=summary, mode=context, or genexus_read instead.
• genexus_dfd - read-only ER diagram of a Transaction/Table (extends/subordinates edges + Mermaid erDiagram) built only from the SDK table relations
• genexus_impact - read-only affected set of an object over the caller graph: counts by type, a dependencies-first rebuild order, cycles and the cap that truncated it (no risk score)
• genexus_object_context - read-only identity + callers/callees (with coverage) + data model of one object; a name shared by several objects is refused with their guids and paths
• genexus_doc — generate wiki / dependency graphs / health reports
• genexus_api — introspect REST endpoints exposed by HTTP procedures
• genexus_security — audit KB security: audit_gam (env/GAM props), scan_secrets (regex over Source), scan_native (the SDK's own Security Scanner, ISecurityScannerService)

Lifecycle, build, test & DB

• genexus_lifecycle — directed build (incl. compile_check), incremental global build_all, forced global rebuild, validate, index, reorg, and poll status
• genexus_test — run native GXtest tests
• genexus_db — DB umbrella: schema-drift, sql_ddl/sql_navigation, static index advisor, sample_data, typed Transaction record query/insert/update with dry-run, optimistic versioning, reread and verified rollback, Domain/SDT type introspection, translation import, reorg_impact, and non-mutating reorg_preview with exact DDL only from a current Impact Analysis artifact
• genexus_deploy — deploy application (IDeploymentService): list_targets (read) / deploy (destructive, confirm=true)
• genexus_run_object / genexus_browser — resolve runtime URL and headless-browser verification

Native layout / UI

• genexus_layout — SDK layout/WebForm ops (get_tree, find_controls, set_property, add_printblock, get_preview, list_controls = control/theme-class catalog, design_system = DSO tokens/classes/images, …)

KB pool, versioning & team dev

• genexus_kb — multi-KB pool (list/open/close/set_default)
• genexus_module — Module Manager (IModuleManagerService)
• genexus_kb_version — model version/branch management (Create/Activate/Revert)
• genexus_versioning — versioning umbrella (git-style history over the KB)
• genexus_gxserver — GXserver / Team Development sync, incl. pipeline_* (CI pipelines via IContinuousIntegrationService)
• genexus_transfer — real XPZ export/import (IKnowledgeManagerService, dependency-aware): export / inspect / import (import previews by default: pass dryRun:false and confirm:true to actually import)
• genexus_memory — per-KB fact store for the agent

Security provisioning, IO & meta

• genexus_gam — GAM / integrated-security provisioning (IIntegratedSecurityService)
• genexus_io — assets, part-text exchange, screenshots, OCR
• genexus_sdk_probe — dump the live SDK surface (types/methods/props) for capability discovery
• genexus_worker_reload — hot-swap the worker without restarting the client