GeneXus MCP Server

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.

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.

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):

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:\Program Files (x86)\GeneXus\GeneXus18"

The KB is chosen at runtime: ask the agent to open it (genexus_kb action=open path=<KB root>, then action=select), or declare it in Environment.KBs (see Advanced Configuration).

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. Other switches: -Force reinstalls the same version, -Version v4.0.4 pins a specific tag, -InstallDir chooses the folder, -Clients claude-code,cursor limits registration, -NoClient skips AI client registration, -Repair wipes and reinstalls the installed version, and -Uninstall removes the install dir and its client entries. 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, on an exported text tree of the KB)

• "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 ones 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:

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 (legacy http-shared mode only)
• 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.

Multi-version GeneXus support

The same MCP distribution supports the official native SDK majors listed in the generated compatibility block at the top of this page. 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 ge