Genexus MCP
About
GeneXus 18 MCP server for Claude, Cursor, and AI agents — read, edit, analyze KB objects (transactions, web panels, procedures, SDTs) over the Model Context Protocol.
Explore
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Genexus MCPCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
If your machine hasMicrosoft Defender ASR,SmartScreen, or another endpoint policy blocking unsigned binaries, the defaultnpxflow is painful —npxcaches 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 —npxis 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 & (](https://github.com/lennix1337/Genexus18MCP/blob/HEAD/TROUBLESHOOTING.md)[scriptblock]::Create($s)) -Kb "C:\KBs\MyKB" -Gx "C:\Program Files (x86)\GeneXus\GeneXus18"
- 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 toupgrade— it detects the installed version (version.txtin the install dir) and downloads only if a newer release is available. Use-Forceto reinstall the same version,-Version v2.3.0to pin a specific tag,-NoClientto skip AI client registration. Node.js 18+ 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.jsonetc.) manually.
Once installed, here's what unlocks. Try these as your first prompts:
- "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."
- "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)
- "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."
- "Explain what the procedure ProcessShipment does, step by step."
- "What SQL does the query in WebPanel CustomerList generate?"
- "Summarize the structure of the Sales module."
- "Build the KB and report any errors."
- "Run the unit tests and show me which failed."
The agent picks the right tool from the40+ toolsthe MCP exposes (read, edit, refactor, analyze, build, data-model authoring, layout automation, DB/DDL, versioning, security, SQL preview, etc.). The full tool list is inTool Surfacebelow.
Auto-detected and auto-configured by the installer:
Runnpx genexus-mcp clientsat any time to see which agents are installed, which havegenexusregistered, and whether any point at a stale gateway exe. To (re)register specific ones:npx genexus-mcp clients add --clients antigravity,vscode.
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?) andnpx genexus-mcp doctor --mcp-smoke.
Most install issues fall into a handful of buckets — seeTROUBLESHOOTING.mdfor 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\
Still stuck?Open an issuewith the output ofnpx genexus-mcp doctor --mcp-smoke.
The worker exposes49 toolsto the MCP router, grouped by capability below. Most are umbrellas with anaction(e.g.genexus_db action=sql_ddl); the detailed schemas live insrc/GxMcp.Gateway/tool_definitions.json.
- 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)
- genexus_query— object search (prefixesname:,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=DataSelectoralso acceptsparameters,conditions,orders,definedBy,baseTransaction,baseTable, andstructure. It preserves SDK order and complete expressions, returns aversionToken, and performs no lifecycle operation. The public U16 SDK does not expose a projected-attribute collection or resolved joins for this object type, soprojectionandjoinsare returned inunsupportedPartswith the technical reason instead of misleading empty arrays. Base objects and declared indexes are reported only when they can be resolved without Specify.structure.expressionis identified as asemanticProjection: it combines the typed public SDK elements and never exposes the internal collection type names produced byDataSelectorStructurePart.ToString()on U16.
- genexus_edit— edit any object part; modesfull/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_atomicauthors 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, requiresconfirm=truefor destructive delete, and reports commit/verification state separately
- genexus_delete_object— delete an object by native SDK identity; usedryRun=trueto inspect incoming references beforeconfirm=true
- genexus_format— format a code snippet with the worker's rules
- 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). Forcreate_index,dryRun:truevalidates and returns the projected diff without saving; use theversionTokenfromget_indexesasbaseVersionfor 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
- genexus_refactor— rename, extract procedure, WWP condition set
- genexus_apply_pattern— apply a GeneXus pattern (WorkWith, WorkWithPlus, …);mode=actionsmanages typed WorkWithPlus grid actions and Action Groups
- genexus_wwp— WorkWithPlus Action Group / grid-action editing:list,add_action,update_action,move_action,remove_action
- genexus_compare— IDE "Compare Objects" parity (IComparerService)
- genexus_merge— 2- or 3-way object merge (IMergeService)
- genexus_analyze— cross-object semantic analysis (impact, dependencies, complexity, naming, code_metrics, summary, explain,kb_stats= KB activity/freshness,table_relations= table↔transaction relations + redundant attrs, …)
- genexus_doc— generate wiki / sequence diagrams / 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)
- genexus_lifecycle— build (incl.compile_check), validate, index, reorg, poll status
- genexus_test— run native GXtest tests
- genexus_db— DB umbrella: schema-drift,sql_ddl/sql_navigation, static index advisor,sample_data, Domain/SDT type introspection, translation import,reorg_impact, and non-mutatingreorg_previewwith 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
- 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, …)
- 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 viaIContinuousIntegrationService)
- genexus_transfer— real XPZ export/import (IKnowledgeManagerService, dependency-aware):export/inspect/import
- genexus_memory— per-KB fact store for the agent
- 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
Multi-KB (v2.3.0+):every non-meta tool takes an optionalkbargument (alias or absolute path). The gateway can hold up toServer.MaxOpenKbs(default 3) KBs open at once, each in its own Worker process — calls to different KBs run truly in parallel. SeeAdvanced Configurationfor theKBs[]schema.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"genexus mcp": {
"server": {
"command": "npx",
"args": [
"-y",
"genexus-mcp"
]
}
}
}
}McpServers
{
"server": {
"command": "npx",
"args": [
"-y",
"genexus-mcp"
]
}
}Transport
"stdio"Package
"genexus-mcp"Registry
"npm"¿Hablás español?→Guía de inicio en españolFala português?→Guia de início em portuguêsStuck?→Troubleshooting guide
GeneXus MCP Serverlets AI agents — Claude Desktop, Claude Code, Cursor, Antigravity, and any MCP-compatible client — read, edit, analyze, and refactor objects inside a GeneXus 18 Knowledge Base. It talks to thenative GeneXus SDK, so the agent works with therealKB, 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.
A quick map of what the agent can do against your real KB through the49 tools(details inTool Surface):
It works through thenative GeneXus SDK— the same code paths the IDE uses — so edits are real and validated, not text hacks on KB files.
- ✅Windows(GeneXus is Windows-only)
- ✅GeneXus 18installed locally (default path:C:\Program Files (x86)\GeneXus\GeneXus18)
- ✅A GeneXus 18 Knowledge Baseopened at least once in the IDE (so it's initialized)
- ✅Node.js 18+— check withnode --versionin a terminal; install fromnodejs.orgif missing
- ✅An MCP-compatible AI client—Claude Desktop,Claude Code, Cursor, Antigravity, etc.
You donotneed to clone this repo or install anything globally —npxhandles it.
Never used a terminal before?PressWin+R, typepowershell, hit Enter. That's your terminal.
Before running the installer, note these down:
- GeneXus install folder— whereGeneXus.exelives. UsuallyC:\Program Files (x86)\GeneXus\GeneXus18.
- Your KB folder— the root folder of your Knowledge Base (contains the.gxfile and subfolders likeModel/,WebSpa/).
Not sure where your KB lives? Open it in GeneXus and check the title bar, or look inFile → Recent.
Open a terminal and run, replacing the paths withyourKB folder andyourGeneXus install:
npx genexus-mcp@latest init --kb "C:\KBs\YourKB" --gx "C:\Program Files (x86)\GeneXus\GeneXus18"
Prefer the wizard? Runnpx genexus-mcp@latest init --interactiveand answer the prompts.
What you'll see (takes ~30 seconds first time, faster on re-runs):
- npxdownloads the package.
- The installer verifies the paths exist and GeneXus is present.
- Itauto-detectswhich AI clients you have installed and adds the MCP config to each one.
- Prints a JSON snippet at the end — keep it in case you need to configure a client manually.
- Finishes with🎉 You are all set!.
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 theclient setup guideif unsure where that file lives.
Step 3 — Restart your AI client, then test
This part trips most people:fully closeyour 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 reloadsopencode.json/opencode.jsonc.
- Gemini CLI / Codex CLI: start a new process or session.
"Using the GeneXus MCP, list the first 5 objects in my KB and show name + type."
- The AI invokes thegenexus_list_objectstool (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 toWhat 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.
If you'd rather not run anything in the terminal yourself, paste this into your AI chat:
Please configure the GeneXus MCP server. Runnpx 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.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
