GeneXus for Agents - Installation guide for macOS

Below are the requirements and steps to install and configure GeneXus for Agents on macOS.

This guide covers the macOS Native scenario, where the IDE runs locally, and the GeneXus MCP Server (BL) runs on Docker or Rancher.

Required components

1. A CLI, for example, Claude Code or CODA CLI
2. GeneXus Next for macOS
3. Connection to the GeneXus MCP Server (requires Docker Desktop or Rancher Desktop)
4. GeneXus skill: nexa

1. CLI

Choose the CLI of your preference:

1.1. Claude Code

Download and install it if you choose this option.

1.2. CODA CLI

Read the documentation for installation and configuration in Coding Agent.

2. GeneXus Next for macOS

In macOS, the GeneXus Next IDE runs as a native application. However, the GeneXus MCP Server (BL) runs on Docker.

2.1. Download and run

Download the GeneXus Next macOS from the Download Center and install it on your computer.

2.2. Configuration settings

In macOS, configuration is handled through a config.json file located in your user directory.

\~/.genexus/GeneXus Next/config.json

With the following content (example):

{  
  "bl": {  
    "env": {  
      "GX\_VOLUMES\_BASE\_PATH": "/Users/\/GeneXus/data"  
    }  
  }  
}

This setting defines the base path used by the backend containers to store:

• Knowledge Bases
• Databases

Notes:

• It is recommended to stop the containers before creating or modifying this file.
• This path corresponds to the host machine.
• Inside the containers, this path is mapped to: /app/kbs/

3. Connect GeneXus MCP Server to your CLI

The MCP Server runs via Docker and is available once the services are up.

See how to configure it depending on the CLI you are using:

3.1. Claude Code

Project-level configuration

To configure the GeneXus MCP Server in Claude Code at the project level, run the following command:

claude mcp add --transport http gxnext http://localhost:8001/mcp

To verify that the MCP Server is connected, run: /mcp

You should see:

gxnext - connected Genexus for agents

User-level configuration

You can also configure it at the user level (across all projects on the machine) by running:

claude mcp add --scope user --transport http gxnext http://localhost:8001/mcp

3.2. CODA CLI

In CODA CLI, the MCP Server can be added by running the /mcp command.

A list of options will be displayed for you to select from:

Select option 2: Add server (JSON). Follow the steps until you paste the MCP Server configuration.

GeneXus MCP Server configuration in JSON format:

{  
    "mcpServers": {  
    "gxnext":  {  
        "transport":  "http",  
        "url":  "http://localhost:8001/mcp"  
      }  
    }  
  }

3.3. Verify MCP Server

After starting the containers, verify that the MCP Server is running correctly.

For that, open a terminal and run:

curl -s http://localhost:8001/mcp | head -1

You should receive a response similar to:

GeneXus.Services.Host v…

This confirms that the MCP Server is up and responding.

Then, verify the connection from your CLI:

• In Claude Code, run: /mcp
• In CODA CLI, run: /mcp

The gxnext server should appear as connected.

4. GeneXus skill: nexa

The nexa skill is available in the public GitHub repository: https://github.com/genexuslabs/genexus-skills/

After cloning the repository, locate the nexa folder and identify the required files:

• nexa/references/
• nexa/SKILL.md

These files define the skill and are required for installation in your coding CLI.

For installation steps (for example, Claude Code, CODA CLI, Codex, or OpenCode), follow the instructions provided in the repository README.md.

Additional resources

You can install the GeneXus KB Text Support extension for Visual Studio Code to get syntax highlighting, diagnostics, and navigation for .gx files.