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. Pick CLI or TOML and toggle Community/Pro:

   Community Pro

   ~/.claude/mcp.json or via CLI bash Copy

   claude mcp add godotiq -- env GODOTIQ_PROJECT_ROOT=<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH> uvx godotiq

   ~/.claude/mcp.json or via CLI bash Copy

   claude mcp add godotiq -- env GODOTIQ_PROJECT_ROOT=<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH> GODOTIQ_LICENSE_KEY=GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX uvx godotiq

   Option A, CLI bash Copy

   codex mcp add godotiq -- env GODOTIQ_PROJECT_ROOT=<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH> uvx godotiq

   Option B, ~/.codex/config.toml toml Copy

   [mcp_servers.godotiq]
   command = "uvx"
   args = ["godotiq"]
   
   [mcp_servers.godotiq.env]
   GODOTIQ_PROJECT_ROOT = "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"

   Option A, CLI bash Copy

   codex mcp add godotiq -- env GODOTIQ_PROJECT_ROOT=<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH> GODOTIQ_LICENSE_KEY=GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX uvx godotiq

   Option B, ~/.codex/config.toml toml Copy

   [mcp_servers.godotiq]
   command = "uvx"
   args = ["godotiq"]
   
   [mcp_servers.godotiq.env]
   GODOTIQ_PROJECT_ROOT = "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"
   GODOTIQ_LICENSE_KEY = "GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

   .cursor/mcp.json json Copy

   {
     "mcpServers": {
       "godotiq": {
         "command": "uvx",
         "args": ["godotiq"],
         "env": {
           "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"
         }
       }
     }
   }

   .cursor/mcp.json json Copy

   {
     "mcpServers": {
       "godotiq": {
         "command": "uvx",
         "args": ["godotiq"],
         "env": {
           "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>",
           "GODOTIQ_LICENSE_KEY": "GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
         }
       }
     }
   }

   ~/.codeium/windsurf/mcp_config.json json Copy

   {
     "mcpServers": {
       "godotiq": {
         "command": "uvx",
         "args": ["godotiq"],
         "env": {
           "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"
         }
       }
     }
   }

   ~/.codeium/windsurf/mcp_config.json json Copy

   {
     "mcpServers": {
       "godotiq": {
         "command": "uvx",
         "args": ["godotiq"],
         "env": {
           "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>",
           "GODOTIQ_LICENSE_KEY": "GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
         }
       }
     }
   }

   .vscode/settings.json json Copy

   {
     "mcp.servers": {
       "godotiq": {
         "command": "uvx",
         "args": ["godotiq"],
         "env": {
           "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"
         }
       }
     }
   }

   .vscode/settings.json json Copy

   {
     "mcp.servers": {
       "godotiq": {
         "command": "uvx",
         "args": ["godotiq"],
         "env": {
           "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>",
           "GODOTIQ_LICENSE_KEY": "GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
         }
       }
     }
   }

   macOS/Linux: pwd · Windows PowerShell: (Get-Location).Path

   Omit GODOTIQ_LICENSE_KEY to use Community. Add your license key to unlock the 14 Pro intelligence tools.

   The tab ships two payloads for Codex (CLI + ~/.codex/config.toml). The CLI and VS Code extension share the same config file.

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.

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

Toggle Pro in the snippet above. Both the CLI and TOML payloads add a GODOTIQ_LICENSE_KEY env to the existing config. Paste your key from the purchase email in place of GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.

If activation doesn’t take, see Manage to deactivate old devices or Troubleshooting.

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.

Bought Pro?

1. Toggle Pro in the snippet above and paste your license key.
2. Restart Codex (or your VS Code Codex extension).
3. Run godotiq auth status: expected: license: pro (active).
4. If activation fails, visit Manage or Troubleshooting. Or email [email protected].

Installation Full installation guide with all client options.

Workflows Common workflow patterns for AI-assisted game development.