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

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 GeneXus SDK. It talks to the native GeneXus SDK, so the agent works with the real KB, not a copy or a parsed approximation.

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 SDK support

The same MCP distribution supports the SDK majors listed in the generated compatibility document. Each configured MCP process selects one installed SDK with --gx; no separate MCP installation is required. The commands below are examples of switching the existing configuration, not running two majors in the same process:

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.

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. 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 SDK majors from the version catalog
• 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 17, GeneXus 18. Primary SDK: GeneXus 18. Source of truth: config/gx-versions.json.

To add another GeneXus major in the future, add it to the explicit version 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 compatibility based only on a version string.

What you can do with it

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

It 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.

Prerequisites

Before you start, make sure you have:

• ✅ Windows (GeneXus is Windows-only)
• ✅ A supported GeneXus SDK installed locally (see docs/generated/supported-versions.md; pass another install path explicitly when needed)
• ✅ A Knowledge Base created with a supported GeneXus major and opened at least once in the IDE (so it's initialized)
• ✅ Node.js 18+ — 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: