Configuration

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).
• 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:

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:

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.

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

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.

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.

Self-hosting the MCP server#

The server is the shared GameDev-MCP-Server, also published as the Docker image aigamedeveloper/mcp-server:

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 lists them all.

Related pages#

• Connecting AI clients for agent configs and sign-in.
• Troubleshooting for connection problems.