# Configuration

Configure Godot MCP in the AI Game Developer dock, choose which tools AI agents see, and override settings with GODOT_MCP_* environment variables.

_Last updated: 2026-11-04_

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](https://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) or `token` (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](https://ai-game.dev/docs/wiki/godot/connecting-ai-clients#custom-mode).

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](https://ai-game.dev/docs/wiki/godot/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.

**Warning**

This file stores tokens as plain JSON. Do not commit, sync or share it. To rotate a token, sign out or clear it in the dock (or delete the file) and connect again.

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`:

```bash
godot-cli configure ./MyGodotProject --list
godot-cli configure ./MyGodotProject --disable-tools script-delete,script-execute
godot-cli configure ./MyGodotProject --enable-all-tools
```

## Environment 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.

```bash
export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:8080
godot --editor --path ./MyGodotProject
```

`godot-cli open` sets these for you with `--mode`, `--url`, `--cloud-url`, `--token`, `--auth` and `--log-level`. See the [godot-cli reference](https://ai-game.dev/docs/wiki/godot/cli#open).

## 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](https://ai-game.dev/docs/wiki/godot/tools#rql).

---

Source (HTML): https://ai-game.dev/docs/wiki/godot/configuration