Configuration
Configure Godot MCP in the AI Game Developer dock, choose which tools AI agents see, and override settings with GODOT_MCP_* environment variables.
Most people never change a setting: the addon starts in Cloud mode, connects after you sign in, and exposes all its tools. This page describes what you can change when you need to, in the AI Game Developer dock, in saved settings, and through environment variables for CI and scripted runs.
The AI Game Developer dock
The addon adds a dock named AI Game Developer to the upper-right dock area of the Godot editor. From top to bottom it has these sections.
Header
The header shows the addon version and a Log Level selector. The log level controls how much the addon and its connection print to the Output panel (Trace, Debug, Info, Warning, Error, None; default Info). Raise it to Debug or Trace when you are diagnosing a connection problem. When GODOT_MCP_LOG_LEVEL is set, the selector is disabled and a note says so.
Connection
- Cloud / Custom: the connection mode. Cloud connects to ai-game.dev; Custom connects to a server URL you choose.
- Connect / Stop: start or stop connecting to the MCP server. The addon keeps retrying in the background until it connects.
- In Cloud mode: your sign-in status with Authorize (starts the browser device sign-in) and Sign out.
- A line of three points, Godot, MCP server and AI agent, that shows what is connected. The AI agent row lists the connected clients by name, or says "(connects on demand)" when none is connected yet.
In Custom mode an MCP server card adds:
- Server URL: the server to connect to, default
http://localhost:8080. - Authorization Token:
none,oauth(your ai-game.dev account token, sent only to a localhost server) ortoken(a bearer token; New generates one). - Start Server / Stop Server: download, start and stop a local server that matches the addon's pinned server version. See Connecting AI clients.
If an environment variable forces the mode or host, a yellow note reads "Overridden by environment (GODOT_MCP_*)" and changes in the dock do not take effect.
AI agent
Choose the AI client you use (Claude Code is the default). The section then shows:
- Skills: where the agent's skill files go, an Auto-generate switch that refreshes them when the addon loads, and a Generate button. Agents without skills support show "Skills not supported by this agent".
- Model Context Protocol (MCP): whether the agent's MCP config is set up, with Configure / Reconfigure and Remove. A Reconfiguration Required notice appears when the server settings changed after you configured the agent.
MCP features
Three rows, Tools, Prompts and Resources, each with a count of visible items out of the total (tools also show an estimated token cost) and an Open button. The window that opens lists every item with a Visible switch and a filter field.
Visible only decides whether MCP clients see the item in their tool list. Hiding tools you do not need keeps the agent's context smaller. It is not access control: a hidden tool still runs if a client calls it by name.
Extensions
The list of optional Godot MCP extensions with Install and Update buttons. It reads the extension catalog embedded in your .csproj; if the list is empty, see Extensions.
Footer
Links for help and reporting issues, and a Serialization Check window that shows how a selected node or object is serialized for the AI (useful when reporting a bug).
Where settings are saved
The dock saves its settings to user://godot-mcp-config.json, in Godot's per-user data folder for the project (not inside the project). It holds the connection mode, custom host, authorization option, log level, selected agent, tool visibility and the tokens you used.
Cloud sign-in credentials live separately in the machine store ~/.ai-game-dev/credentials.json, shared with the other AI Game Developer tools. Project keys for agent configs are in ~/.ai-game-dev/project-keys.json.
From a terminal, godot-cli configure lists and changes tool, prompt and resource visibility in the project file .godot-mcp/features.json:
godot-cli configure ./MyGodotProject --list
godot-cli configure ./MyGodotProject --disable-tools script-delete,script-execute
godot-cli configure ./MyGodotProject --enable-all-toolsEnvironment variables
Environment variables override the saved settings without editing any file, which is handy for CI, headless runs and local development. The addon also reads them from a .env file in the project; the process environment wins over .env.
| Variable | Values | Purpose |
|---|---|---|
GODOT_MCP_CONNECTION_MODE | Cloud, Custom | Force the connection mode. Default Cloud. |
GODOT_MCP_CLOUD_URL | URL | Override the cloud base URL. Default https://ai-game.dev. |
GODOT_MCP_HOST | URL | The Custom-mode server URL. Default http://localhost:8080. |
GODOT_MCP_AUTH_OPTION | none, oauth, token | Custom-mode authorization. |
GODOT_MCP_TOKEN | string | Bearer token for the active mode. Overrides the saved one and is never written back. |
GODOT_MCP_LOG_LEVEL | Trace to None | Log verbosity. |
GODOT_MCP_CREDENTIALS_DIR | absolute path | Use a separate credential store, for isolated testing. |
GODOT_MCP_TOOL_FORMAT | Rql, Json | How tools take arguments and return results. Default Rql (compact text); Json keeps JSON schemas and results. |
GODOT_MCP_SERVER_PATH | absolute path | Editor only: start this existing server binary instead of downloading the pinned release. |
GODOT_MCP_RUNTIME_FROM_EDITOR | 1 | Let a game started with Play connect its own in-game MCP runtime too. |
Example: start the editor against a local server.
export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:8080
godot --editor --path ./MyGodotProjectgodot-cli open sets these for you with --mode, --url, --cloud-url, --token, --auth and --log-level. See the godot-cli reference.
Tool format
With the default Rql format, tools take RQL values as arguments (a node path such as "Level/Player", or godot.find("Name")) and return compact text that costs fewer tokens. The Json format, set with GODOT_MCP_TOOL_FORMAT=Json or the toolFormat key, keeps full JSON schemas and structured results for clients that prefer them. More on RQL: Tools.