Windsurf

Windsurf supports MCP servers through its global configuration. GodotIQ integrates with Windsurf’s Cascade AI to provide spatial, code, and runtime understanding of your Godot project.

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

Setup

1. Install GodotIQ:

   pip install godotiq

2. Add to Windsurf MCP config. Toggle Community or Pro and copy into ~/.codeium/windsurf/mcp_config.json:

   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.

   Swap in your project path (placeholder: <REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>). uvx auto-installs godotiq on first use.

3. Restart Windsurf to activate the MCP server.

4. Verify: Ask Cascade: “Ping GodotIQ”. It should confirm the connection.

Note

Windsurf uses a global MCP config, not per-project. If you switch between Godot projects, update the GODOTIQ_PROJECT_ROOT path accordingly, or use a wrapper script that detects the current project.

Tips for Windsurf

Cascade Flows

Windsurf’s Cascade (Cmd+L / Ctrl+L) can chain GodotIQ tool calls naturally. Start with broad context, then narrow down:

“Use godotiq_project_summary to understand this project, then analyze the signal flow for player damage.”

Write Mode

Use Windsurf’s Write mode for applying GodotIQ-informed changes. After the AI analyzes your code with tools like godotiq_dependency_graph or godotiq_signal_map, switch to Write mode to let it make the changes.

Terminal Integration

Windsurf can run terminal commands alongside MCP tool calls. This is useful for running your Godot project or checking build output while using GodotIQ’s analysis tools.

Activate Pro

Toggle Pro in the snippet above and paste your license key in place of GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. Save mcp_config.json and restart Windsurf.

If activation doesn’t take, see Manage or Troubleshooting.

Advanced Configuration

Multiple Projects

For multiple Godot projects, define separate MCP entries with different GODOTIQ_PROJECT_ROOT values inside the same mcp_config.json. Cascade will expose each as a distinct server (godotiq-project-a, godotiq-project-b, etc.).

Troubleshooting

MCP server not detected

• Verify the config file path: ~/.codeium/windsurf/mcp_config.json
• Check JSON syntax. A trailing comma or missing bracket will silently fail.
• Restart Windsurf completely

Permission issues

On macOS, ensure godotiq is accessible from the Windsurf process. If installed in a virtual environment, use the full path to the executable.

Bought Pro?

1. Toggle Pro in the snippet above and paste your license key.
2. Save mcp_config.json and restart Windsurf.
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.