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.

<!-- BEGIN GENERATED: gx-compatibility -->

Supported SDK majors: GeneXus 16, GeneXus 17, GeneXus 18, GeneXus Evolution 3 (native SDK). Basic legacy compatibility: 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.

<!-- END GENERATED: gx-compatibility -->

Contents

• What you can do with it
• Prerequisites · Quickstart · Corporate install
• What can I ask the AI? · Supported AI clients · Troubleshooting
• Multi-version GeneXus support
• Tool Surface · WorkWithPlus pattern editing · AXI CLI
• Advanced Configuration · Experimental gx-engine
• Development & building from source · Contributing
• Support the project · Acknowledgements · License

---

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; new installs expose a 20-tool standard profile by default, see Tool profiles):

| 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); pack_task also works directly on the open native KB | | ✏️ 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, Data View–backed Business Components | | 🧩 Author other objects | External Object methods & properties, Menu options, REST API objects, WorkWithPlus / WorkWith patterns, K2B Designer (through the IDE bridge), 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, KB activity/freshness, reorg/DDL impact preview, native security scan, schema-drift check, ER diagrams | | 🛠️ 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), compare two KB directories | | 🌿 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, disposable KB sandboxes | | 🔐 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)
• ✅ GeneXus 18, 17, or 16 installed locally for native SDK support (GeneXus 18 is the primary SDK), or a catalogued legacy installation for basic compatibility — see docs/generated/supported-versions.md
• ✅ 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 (it contains the <KBName>.gxw file and knowledgebase.connection).

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. Running init from inside a KB folder also works: the KB path is detected from the current directory.

What happens (takes ~30 seconds the first time, faster on re-runs):

1. npx downloads the package.
2. The installer checks that both paths exist and that the KB's GeneXus major (read from its .gxw) matches the selected installation and is supported. It stops before writing anything when they conflict.
3. It writes the MCP config.json.
4. It auto-detects which AI clients you have installed and registers the MCP in each one (pass --no-write-clients to skip, or --all-clients to write every known client).
5. It verifies the result with a short MCP smoke test and prints what to do next.

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 — Check the client registration

Step 1 auto-registers every supported client it detects, including Claude Desktop, Claude Code, Cursor, Antigravity, Gemini CLI, OpenCode, Codex CLI, and VS Code. Run npx genexus-mcp clients to confirm. If yours wasn't detected, register it manually — see the client setup guide.

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, run npx genexus-mcp clients to confirm my client is registered, and 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, creates a neutral runtime configuration (no hardcoded KB), 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 an explicit GeneXus installation
$s = irm https://raw.githubusercontent.com/lennix1337/Genexus18MCP/main/scripts/install.ps1
& ([scriptblock]::Create($s)) -Gx "C:\P