Connect your AI IDE (MCP)

• New projects are already connected for Cursor. File → New Project and hexaliz project init write a .cursor/mcp.json with this install’s paths into the project.
• In the app: Settings → MCP Servers → Connect external agent shows the exact entry for Cursor, Codex and Claude Code with your paths, with Copy config, and Add to Active Project for Cursor.

The same entries by hand. Each one binds the server to one project folder.

{
  "$schema": "https://json.schemastore.org/mcp.json",
  "mcpServers": {
    "hexaliz-engine": {
      "type": "stdio",
      "command": "/home/<you>/.hexaliz/runtime/py/bin/python",
      "args": [
        "-m",
        "hexaliz.mcp_server",
        "--transport",
        "stdio"
      ],
      "cwd": "/home/<you>/games/my-game",
      "env": {
        "PYTHONPATH": "/home/<you>/.local/share/hexaliz-engine/app/scripts/python",
        "PYTHONIOENCODING": "utf-8",
        "HEXALIZ_PROJECT": "/home/<you>/games/my-game",
        "HEXALIZ_USER_DATA": "/home/<you>/.hexaliz",
        "HEXALIZ_DISABLE_VAULT": "0"
      }
    }
  }
}

Print the exact entry from a terminal

This prints a JSON object; its content field is the entry, and configPath is where it goes.

PYTHONPATH=~/.local/share/hexaliz-engine/app/scripts/python \
  ~/.hexaliz/runtime/py/bin/python -m hexaliz.mcp_setup preview --client cursor --project ~/games/my-game

$env:PYTHONPATH = "<install folder>\scripts\python"
& "$env:USERPROFILE\.hexaliz\runtime\py\Scripts\python.exe" -m hexaliz.mcp_setup preview --client cursor --project C:\Games\MyGame

Use --client claude or --client codex for the others. python -m hexaliz.mcp_setup doctor --project <dir> checks that the server starts and lists its tools.

Cursor

1. Put the entry in <project>/.cursor/mcp.json and open that folder in Cursor.
2. Turn the hexaliz-engine server on in Cursor’s MCP settings. With the Cursor CLI, approve it once: cursor-agent mcp enable hexaliz-engine. Until then cursor-agent mcp list shows it as needing approval.

Claude Code

1. Put the entry in <project>/.mcp.json and start claude in that folder.
2. Approve the project’s hexaliz-engine server when Claude Code asks; /mcp shows its status.

Codex

1. Add the entry to ~/.codex/config.toml (or the project’s .codex/config.toml). tool_timeout_sec = 900 gives long generations and builds time to finish.
2. Start codex; /mcp lists the server and its tools.

The server has 23 grouped tools. An agent should start with list_hexaliz_tools() (the primer), read a group’s signatures with <group>(action="actions"), and read the matching bundled guide before a creation task:project(action="get_skill", args={"name": "build-game-scene"}). See Bundled guides.

For play-testing, the agent opens its own isolated game session (game session op=open) and passes itssession_id on. Without one, game and scene actions reach the game open in your Hexaliz window.

Every MCP action is also a shell command that prints one line of JSON, for agents and scripts without MCP:

hexaliz --help                                  # groups, actions, flags, exit codes
hexaliz project --help                          # one group's signatures
hexaliz status
hexaliz game session --op open --project-path ~/games/my-game

On Linux the command is ~/.local/bin/hexaliz. On Windows it is scripts\python\bin\hexaliz.cmd in the install folder (scripts/python/bin/hexaliz from Git Bash).

Local models are free and stay on your PC. Whether MCP and command-line agents may use Hexaliz Cloud media is your choice in the app: Settings → Plan & Usage → External agents, for all projects or only the ones you list. With it on, they generate within your monthly allowance without asking each time. See pricing.