How to: start, configure, and use the GeneXus MCP server

This article explains how to start, configure, and use the GeneXus MCP Server.

Who starts the MCP server?

By default, it is not started. You have three options.

Option A — Start it manually

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.

Option B — Start it from the IDE

You can start the MCP Server directly from the IDE by selecting Tools > MCP Server > Start Server.

Option C — Have the IDE services start it

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:

{
  "McpAutoStart": 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:

1. Checks http://127.0.0.1:1989/mcp.
2. If there is a response, it assumes that it is already running and does not starts anything.
3. 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.

Configuration

The GeneXus MCP Server reads configuration in the following order (each step overrides the previous one):

1. settings.json — Default values included with the bundle.
2. overrides-settings.json — Your local override file (optional). Edit this file when running it manually.
3. Environment variables — Those that can be set by who launched it.

When the services host launches the application, it passes information through environment variables, including BL paths, KBs folder, and SQL credentials. As a result, environment variables provided by the host take precedence over values defined in settings.json. This behavior is intentional and prevents sensitive information, such as SQL passwords, from being stored in files.

Typical settings.json

{
  "BL": {
    "InstallationDirectory": "",
    "PackagesDirectory": ""
  },
  "McpServer": {
    "Url": "http://127.0.0.1:1989",
    "SessionIdleTimeoutMinutes": 30
  },
  "KnowledgeBases": {
    "ProjectsFolder": "C:\\KBs",
    "SqlUserName": "",
    "SqlUserPassword": ""
  }
}

Change the port

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: edit McpChildPort in the services host settings.json file, or set environment variables (see below).

{
  "McpAutoStart": true,
  "McpChildPort": 5050
}

Configuration via environment variables (containers)

If you cannot or do not want to modify the services host settings.json file, you can configure it using environment variables.

The naming convention is GXM_, derived from the property name. For MCP:

In a Dockerfile:

ENV GXM_MCP_AUTO_START=true
ENV GXM_MCP_CHILD_PORT=1989

This convention applies to any setting (GXM_GENEXUS_BL_BASE_PATH, GXM_PROJECTS_FOLDER, GXM_SQL_USER_PASSWORD, etc.): PascalCase → SNAKE_CASE in uppercase with the prefix GXM_.

MCP server logs

By default, MCP Server logs are written using the configuration defined in settings.json.

Log output location is resolved in the following order:

1. If the GENEXUS_LOG_DIR environment variable is defined, logs are written to that directory.
2. 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.

Configure log levels

Log levels are configured in the Serilog section of the settings.json file.

Sample

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "BL": "Information",
        "GeneXus.PIA.McpServer.Requests": "Information"
      }
    }
  }
}

Available levels are:

• Verbose
• Debug
• Information
• Warning
• Error
• Fatal

Log each /mcp request

To log incoming MCP requests and JSON-RPC payloads, set:

{
  "GeneXus.PIA.McpServer.Requests": "Information"
}

in the Serilog section of the settings.json file.

Logging troubleshooting

If no log files are generated

• Check that GENEXUS_LOG_DIR points to a writable directory.
• If not set, logs are written to /logs/ next to the executable.

Log level changes are not taking effect

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

Quick check

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 the server did not start

1. 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: ....
2. If you expected the services host to start it:
3. Verify that McpAutoStart is set to true (in settings.json or through GXM_MCP_AUTO_START).
4. Check the services host logs. McpProcessHost logs messages using the MCP prefix (spawn, PID, errors).
5. Verify that the bundle exists in the McpBundlePath directory (or, if it’s empty, next to the services host executable).