# Configuration

Configure Unity MCP in the AI Game Developer window - Cloud and Custom modes, local server, port, transport, authorization, tools, overrides and CI.

_Last updated: 2026-11-04_

Most projects need no configuration: install the plugin, sign in, click **Configure** for your agent. This page explains what each setting in the AI Game Developer window does, where the settings are stored, how to override them for automation, and how the plugin behaves in CI and in player builds.

## The AI Game Developer window

Open it with **Window > AI Game Developer — MCP** (Ctrl+Alt+A, or Cmd+Option+A on macOS) or the **AI** button in the Scene View toolbar. From top to bottom it contains:

- **Log Level**, **Timeout (ms)** and **Tool timeout (ms)**, plus the plugin **Version**.
- **Connection**: the **Custom** / **Cloud** switch and the settings for the chosen mode.
- A connection timeline: **Unity** (with a **Connect** / **Disconnect** button), **MCP server** and **AI agent**.
- The **AI agent** dropdown with the configurator for each client: **Model Context Protocol (MCP)** with **Configure** / **Remove**, and **Skills** with **Auto-generate** and **Generate**.
- **Tools**, **Prompts** and **Resources** counters, each with an **Open** button.
- **Extensions**: install optional tool packs (see [Extensions](https://ai-game.dev/docs/wiki/unity/extensions)).
- Help links: **Help / Talk** (Discord), **Bug Report** (GitHub issues) and a **Check** button for serialization diagnostics.

## Connection modes

### Cloud (default)

The plugin connects to the hosted server at `https://ai-game.dev/mcp`. No local server is started and the URL is not editable. Cloud mode needs a sign-in: click **Authorize** next to **Cloud Token** and approve the device code in your browser, or sign in once with `unity-mcp-cli login` or the AI Game Dev app. **Revoke** signs out every AI Game Dev tool on the machine.

### Custom (local or your own server)

The plugin connects to the URL in **Server URL**. By default that is a local server at `http://localhost:<port>`, and the plugin downloads, starts and stops the server (`gamedev-mcp-server`) for you. You can also enter the URL of a remote MCP server you host. **Server URL** is editable only while Unity is disconnected from the server.

Custom mode adds these settings:

- **MCP server**: a **Start** / **Stop** button and status (Running, Starting, Stopping, Downloading, or External when another process already serves the port). **Download / Retry server** appears if the binary download failed.
- **Transport**: `http` (recommended) or `stdio`. With `http` the agent connects to the running server, several agents can share it, and the server can run on another machine. With `stdio` the agent launches the server as its own child process, only one agent can connect, and the Start / Stop button is disabled.
- **Authorization Token**: `none`, `oauth` or `token`.
  - `none`: the server accepts any connection. Safe only when the port is not reachable from other machines.
  - `oauth`: agents sign in with their ai-game.dev account; the server checks tokens online.
  - `token`: a shared secret, fully offline. Click **New** to generate a token, then **Configure** (or copy the token into the agent's config by hand).

## The port

The local port is not a fixed value like 8080. It is derived from your project folder: the SHA-256 hash of the normalized project path, mapped into the range **20000 to 29999**. The same project always gets the same port, and different projects get different ports, so several Unity instances can run side by side. The CLI uses the same formula, so its commands find the right server without flags.

To use another port, disconnect, then type it into **Server URL** (for example `http://localhost:25000`). The configurators write the port you typed into agent configs.

## The config file

Settings are stored per user in `UserSettings/AI-Game-Developer-Config.json`, created on first launch. Notable keys:

| Key | Meaning | Default |
| --- | --- | --- |
| `connectionMode` | `Cloud` or `Custom` | `Cloud` |
| `host` | Server URL for Custom mode | `http://localhost:<port>` |
| `token` | Shared token for the `token` authorization mode | generated |
| `transportMethod` | `streamableHttp` or `stdio` | `streamableHttp` |
| `authOption` | `none`, `oauth` or `token` | `none` |
| `keepConnected` | Connect to the server automatically | `true`, `false` in CI |
| `keepServerRunning` | Start and keep the local server running | `true`, `false` in CI |
| `logLevel` | `Trace`, `Debug`, `Information`, `Warning`, `Error`, `Critical` | `Warning` |
| `timeoutMs` | Plugin-to-server timeout | `10000` |
| `toolTimeoutMs` | How long one tool call may run | `300000` |
| `tools`, `prompts`, `resources` | Per-item visibility | defaults |

Cloud credentials are not stored here; they live in `~/.ai-game-dev/credentials.json`. To start over, use **Tools > AI Game Developer > Reset Config**, which restores defaults and reloads scripts.

## Tools, prompts and resources

The **Tools** counter shows how many of the installed tools the agent sees, and an estimate of the tokens they take in the AI's context. Click **Open** to show or hide individual tools; the **MCP Prompts** and **MCP Resources** windows work the same way.

A hidden tool is not deleted: it disappears from the agent's tool list but still runs when called by name. Fewer visible tools leave more context for reasoning. You can also change visibility with the `tool-set-visibility` tool or from a terminal:

```bash
unity-mcp-cli configure ./MyUnityProject --enable-tools screenshot-scene-view,script-read
unity-mcp-cli configure ./MyUnityProject --list
```

## Environment and command-line overrides

For CI and scripted launches the plugin reads these variables (or the matching Unity command-line arguments) at startup. Overrides apply in memory only and are never written to the config file.

| Variable | Command-line argument | Values |
| --- | --- | --- |
| `UNITY_MCP_CLOUD_URL` | `-url` | Server URL (`UNITY_MCP_HOST` is a legacy alias) |
| `UNITY_MCP_CONNECTION_MODE` | `-UNITY_MCP_CONNECTION_MODE` | `Cloud` or `Custom`; a loopback URL implies `Custom` |
| `UNITY_MCP_KEEP_CONNECTED` | `-UNITY_MCP_KEEP_CONNECTED` | `true` or `false` |
| `UNITY_MCP_AUTH_OPTION` | `-auth` | `none`, `oauth` or `token` |
| `UNITY_MCP_TOKEN` | `-token` | Local server token |
| `UNITY_MCP_TRANSPORT` | `-UNITY_MCP_TRANSPORT` | `stdio` or `streamableHttp` |
| `UNITY_MCP_START_SERVER` | `-UNITY_MCP_START_SERVER` | `true` or `false` |
| `UNITY_MCP_TOOLS` | `-UNITY_MCP_TOOLS` | Comma-separated tool ids to show; all others are hidden |

Command-line arguments win over environment variables. Example for a batch-mode Editor connected to a local server:

```bash
Unity -batchmode -projectPath ./MyUnityProject \
  -UNITY_MCP_CLOUD_URL=http://localhost:8080 \
  -UNITY_MCP_KEEP_CONNECTED=true \
  -UNITY_MCP_AUTH_OPTION=token \
  -UNITY_MCP_TOKEN=my-secret-token
```

`unity-mcp-cli open` sets these variables for you; see the [CLI reference](https://ai-game.dev/docs/wiki/unity/cli#open).

## Disabling Unity MCP in CI

The plugin detects CI environments and then skips the server download and auto-connect. To turn it off completely for ordinary CI test jobs, use one of two opt-outs:

- **`UNITY_MCP_DISABLE=1`** (or `true`) in the environment of the process that launches Unity. The plugin skips startup, tool registration, the server download, NuGet resolution and its editor hooks. Its code still compiles, so the project must still compile.
- **`UNITY_MCP_EXCLUDE_FROM_COMPILATION`** as a Scripting Define Symbol in **Project Settings > Player > Other Settings**. This excludes all plugin assemblies (and updated first-party extensions) from compilation. Your own code that references plugin types needs `#if !UNITY_MCP_EXCLUDE_FROM_COMPILATION`.

Neither is enabled automatically for `-batchmode` or `-runTests`, because headless MCP sessions need the plugin.

## Player builds and runtime

The plugin's runtime assembly compiles for every platform, so it is part of your player builds unless you exclude it with the define above. A build never connects on its own: in a game you opt in from code with `UnityMcpPluginRuntime.Initialize(...)`, which is how you expose in-game tools to an AI (for example an AI chess opponent). See [Custom tools](https://ai-game.dev/docs/wiki/unity/custom-tools#runtime).

## Self-hosting the MCP server

The server is the shared [GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server), also published as the Docker image `aigamedeveloper/mcp-server`:

```bash
docker run -p 8080:8080 aigamedeveloper/mcp-server
```

Then set the plugin to **Custom** with **Server URL** `http://localhost:8080` (or your host), and point your agent at the same address. The server accepts settings such as `--port`, `--client-transport`, `--authorization` and `--idle-timeout-seconds`, or the matching `MCP_PLUGIN_*` environment variables; the [server documentation](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/mcp-server.md) lists them all.

## Related pages

- [Connecting AI clients](https://ai-game.dev/docs/wiki/unity/connecting-ai-clients) for agent configs and sign-in.
- [Troubleshooting](https://ai-game.dev/docs/wiki/unity/troubleshooting) for connection problems.

---

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