Codex

Codex supports MCP servers through a shared TOML configuration. GodotIQ integrates with both the Codex CLI and the VS Code extension to give your AI spatial, code, and runtime understanding of your Godot project.

Running godotiq install-addon automatically creates AGENTS.md with development rules for this client. No manual configuration needed.

Setup

1. Install GodotIQ:

   pip install godotiq

2. Add the MCP server:

   Option A — CLI command:

   codex mcp add godotiq -- uvx godotiq

   Option B — Edit config file:

   Create or edit ~/.codex/config.toml:

   config.toml

   [mcp_servers.godotiq]
   command = "uvx"
   args = ["godotiq"]
   [mcp_servers.godotiq.env]
   GODOTIQ_PROJECT_ROOT = "/path/to/your/godot/project"

   Replace the path with your Godot project root (the directory containing project.godot). uvx auto-installs godotiq on first use.

3. Verify the connection:

   Run /mcp inside Codex or codex mcp in your terminal. GodotIQ should appear in the list of active MCP servers.

Note

Codex uses TOML format (config.toml), not JSON. The config lives at ~/.codex/config.toml globally, or .codex/config.toml in a trusted project directory. The CLI and VS Code extension share the same config file.

Tips for Codex

Start with Project Context

Begin each session by asking Codex to understand your project:

“Use godotiq_project_summary to understand this project, then help me with…”

This gives Codex full project awareness (architecture, file relationships, conventions) before you start working.

Use Natural Language

You don’t need to specify tool names. GodotIQ tools are designed to be invoked naturally:

• “What’s the layout of my dungeon level?” → godotiq_scene_map
• “What would break if I rename PlayerManager?” → godotiq_impact_check
• “Place torches along the corridor walls” → godotiq_placement
• “Why is the health bar not updating?” → godotiq_trace_flow + godotiq_signal_map

Codex will select the right tool based on your question.

Multi-Tool Chains

Codex can call multiple GodotIQ tools in sequence. Common patterns:

• Debug flow: godotiq_project_summary → godotiq_trace_flow → godotiq_signal_map
• Safe refactor: godotiq_impact_check → godotiq_signal_map → make changes → godotiq_validate
• Level review: godotiq_scene_map → godotiq_spatial_audit → godotiq_placement (for fixes)

Project-Scoped Config

For per-project configuration, create .codex/config.toml in the project directory instead of the global ~/.codex/config.toml. Codex uses the local config when you run from that directory.

Activate Pro

After purchasing GodotIQ Pro, add your license key:

Option A — CLI (quickest):

codex mcp add godotiq -- env GODOTIQ_PROJECT_ROOT=/path/to/your/godot/project GODOTIQ_LICENSE_KEY=GODOTIQ-XXXX-XXXX-XXXX-XXXX uvx godotiq

Option B — Edit config file:

config.toml

[mcp_servers.godotiq.env]
GODOTIQ_PROJECT_ROOT = "/path/to/your/godot/project"
GODOTIQ_LICENSE_KEY = "GODOTIQ-XXXX-XXXX-XXXX-XXXX"

Troubleshooting

Tools not appearing

1. Check config.toml syntax — TOML is strict about quoting and brackets
2. Verify with codex mcp in your terminal
3. Ensure godotiq is installed: pip show godotiq

MCP server not responding

1. Check that the project path exists and contains project.godot
2. Update to the latest version: pip install --upgrade godotiq
3. Try the CLI command: codex mcp add godotiq -- uvx godotiq

Bridge tools not working

Bridge tools (godotiq_screenshot, godotiq_run, godotiq_node_ops, etc.) are free but require the GodotIQ addon installed in your Godot project and the editor to be running. The addon communicates via WebSocket on port 6007.

Installation Full installation guide with all client options.

Workflows Common workflow patterns for AI-assisted game development.