This article describes the requirements and the steps needed to start, configure, and use the GeneXus MCP Server.
You must install either GeneXus Next Desktop or a Business Logic (BL) service layer.
By default, the GeneXus MCP Server is not started. You have three options to do it.
Go to the installation directory and run:
GeneXus.PIA.McpServer.exe
The process loads the BL, starts, and listens on http://localhost:1989/mcp. Close it when you no longer need it.
You can start the MCP Server directly from the IDE by selecting Tools > MCP Server > Start Server.
The services host on :1989 can automatically launch the MCP server at startup, but this option is disabled by default. To enable it, set the following value in the services host settings.json file:
{
"McpServer": {
"AutoStart": true
}
}
McpAutoStart property
- Set it to true to allow the host to start the child process at each startup.
- You can also configure this value using environment variables. See Configuration via environment variables (containers).
When this property is set to true, the services host performs the following steps at startup:
- Checks http://127.0.0.1:1989/mcp.
- If there is a response, it assumes that it is already running and does not starts anything.
- If there is no response, it starts GeneXus.PIA.McpServer.exe as a child process in fire-and-forget mode.
The MCP process continues running independently of the services host. When the host shuts down, the MCP process remains active. This behavior is intentional, allowing clients to remain connected even if the host is restarted.
Note: If you start the GeneXus Next Desktop IDE, which internally starts the services host, and McpAutoStart is set to false, the GeneXus MCP server does not start. This is the most common cause of connection issues.
The GeneXus MCP Server reads configuration in the following order (each step overrides the previous one):
- settings-overrides.json — Your local override file (optional). Edit this file when running it manually.
- Environment variables — Those that can be set by who launched it.
- settings.json — Default values included with the bundle.
This means that values defined in settings-overrides.json override both environment variables and base configuration values defined in settings.json. Environment variables take precedence over settings.json values.
{
"BL": {
"InstallationDirectory": "",
"PackagesDirectory": ""
},
"McpServer": {
"Url": "http://127.0.0.1:1989",
"SessionIdleTimeoutMinutes": 30
},
"KnowledgeBases": {
"ProjectsFolder": "C:\\KBs",
"SqlUserName": "",
"SqlUserPassword": ""
}
}
If you run it manually: edit McpServer:Url in the MCP settings.json file.
{
"McpServer": {
"Url": "http://127.0.0.1:5050"
}
}
If you use auto-start: configure the McpServer section in the services host settings.json file, or set it using environment variables (see below).
{
"McpServer": {
"AutoStart": true,
"Port": 5050
}
}
Environment variables can be used to override any setting defined in the configuration file.
Environment variables use the standard Section__Key naming convention, where __ (double underscore) maps to the : section separator in the configuration file.
Given this configuration:
{
"McpServer": {
"Url": "http://localhost:1989",
"AutoStart": false
},
"Host": {
"ServicesPort": 8001
}
}
It can be overridden using environment variables:
McpServer__Url=http://0.0.0.0:1989
McpServer__AutoStart=true
Host__ServicesPort=9000
By default, MCP Server logs are written using the configuration defined in settings.json.
Log output location is resolved in the following order:
- If the GENEXUS_LOG_DIR environment variable is defined, logs are written to that directory.
- Otherwise, logs are written to /GeneXus.PIA.McpServer/logs.
The MCP server logging configuration is defined in the Serilog section of the settings.json file.
Note: The mcplog.config file (located next to the .exe) is a legacy configuration used for BL logging when the system was based on log4net. It is kept only for compatibility with existing BL traces.
The generated log files use the following format:
McpServer-YYYYMMDD.log
A new log file is created each day and reused during the same day.
Log levels are configured in the Serilog section of the settings.json file.
{
"Serilog": {
"MinimumLevel": {
"Default": "Information",
"Override": {
"Microsoft": "Warning",
"BL": "Information",
"GeneXus.PIA.McpServer.Requests": "Information"
}
}
}
}
Available levels are:
- Verbose
- Debug
- Information
- Warning
- Error
- Fatal
To log incoming MCP requests and JSON-RPC payloads, set:
{
"GeneXus.PIA.McpServer.Requests": "Information"
}
in the Serilog section of the settings.json file.
- Check that GENEXUS_LOG_DIR points to a writable directory.
- If not set, logs are written to /logs/ next to the executable.
- The settings.json file is only read at startup. Restart the server after making any changes.
- Make sure you are editing the settings.json file in the directory where the server is actually running (not the repository version).
- If a settings.json file also exists in the same directory, keep in mind that it is loaded after the template and may override your changes.
To verify that the GeneXus MCP Server is running:
curl http://localhost:1989/mcp
- Any HTTP response (including 4xx) indicates that the server is running.
- connection refused indicates that the server did not start.
- If you start it manually, check the .exe console output. If the BL fails during startup, the following message is displayed and the process exits: ERROR BL startup failed: ....
- If you expected the services host to start it:
- Verify that AutoStart is enabled in the MCP Server configuration (settings.json or environment variables).
- Check the services host logs. McpProcessHost logs messages using the MCP prefix (spawn, PID, errors).
- Verify that the bundle exists in the McpBundlePath directory (or, if it’s empty, next to the services host executable).
The /version endpoint returns the version of the GeneXus Business Logic (BL) initialized by the MCP Server. It indicates the GeneXus version currently in use by the server.
To get this information, use:
curl http://localhost:1989/version
Example response:
{
"productName": "GeneXus",
"versionName": "",
"version": "19.2.175",
"versionNumber": "19.2.0.175",
"fullVersionName": "GeneXus",
"mcpServerAssembly": "11.0.0.0"
}
Since GXWEB_BL_VERSION = bl-185-services1.2.80 (May 8, 2026), the GeneXus MCP Server is no longer hosted inside the GeneXus services host (port 8001).
The GeneXus MCP Server runs as an independent process, GeneXus.PIA.McpServer.exe, on port 1989 by default, with its own /mcp endpoint.
The 404 error on :8001/mcp is expected because that route no longer exists there.