FAQ

Short answers to the questions people ask most about Unity MCP, the AI Game Developer plugin for Unity. Each answer links to the page with the details.

General#

What is Unity MCP?#

A Unity Editor plugin that lets AI agents work in your project through the Model Context Protocol. The agent can read and change scenes, GameObjects, components, prefabs and assets, write and run C#, run tests and take screenshots. See the overview.

Is the plugin free and open source?#

The plugin is open source under the Apache-2.0 license, in the Unity-MCP repository. Custom mode runs a local server and needs no account. Cloud mode uses your ai-game.dev account; plans are on the pricing page.

Which Unity versions are supported?#

Unity 2022.3 and newer, including Unity 6.

Which AI clients work with it?#

The AI Game Developer window has configurators for Claude Code, Claude Desktop, Cursor, Visual Studio Code (Copilot), Visual Studio (Copilot), Rider (Junie), GitHub Copilot CLI, Gemini, Antigravity, Cline, Open Code, Codex, Kilo Code, Zoo Code and Unity AI, plus a custom entry for any other MCP client. See Connecting AI clients.

Do I need my own AI client?#

No. The AI Game Dev desktop app includes the agent, installs the plugin and connects it. Bring your own client if you already use Claude Code, Cursor or another MCP client.

Setup#

What is the easiest way to install it?#

The desktop app. Without it, run unity-mcp-cli install-plugin, or use OpenUPM or the .unitypackage installer. See Installation.

Where is the plugin window?#

Window > AI Game Developer — MCP, shortcut Ctrl+Alt+A (Cmd+Option+A on macOS), or the AI button in the Scene View toolbar.

What is the difference between Cloud and Custom mode?#

In Cloud mode, the default, the Editor and your AI client connect to https://ai-game.dev/mcp and you sign in once. In Custom mode the plugin runs a local MCP server on a port derived from your project path, and everything stays on your machine. See Configuration.

Do I need to choose a port?#

No. The port is derived from the project path (range 20000 to 29999), so it is stable per project and different between projects. You can override it in Server URL.

Where are the settings stored?#

In UserSettings/AI-Game-Developer-Config.json inside the project. The ai-game.dev sign-in is stored once per machine in ~/.ai-game-dev/credentials.json.

Can I use several Unity projects at once?#

Yes. Each project has its own port, and pinned URLs (https://ai-game.dev/mcp/p/<pin>) route each agent to the right Editor.

Using it#

Where did tools like gameobject-create go?#

Version 1.0.0 replaced the one-tool-per-action tools with RQL: rql-query, rql-mutate and rql-schema cover scenes, GameObjects, components, assets, the Console and Editor state. See Tools and RQL.

Can the AI undo its changes?#

Each rql-mutate call is recorded as one Undo step, so Ctrl+Z (Cmd+Z) reverts it. Use version control for anything larger.

Why does the agent see only a few tools?#

To save context. Seven tools are visible by default; the rest are installed but hidden and still run when called by name. Show more in the window under Tools > Open.

Can I add my own tools?#

Yes. Mark a class with [AiToolType] and a method with [AiTool]. See Custom tools.

How do I add support for Cinemachine, ProBuilder or Tilemaps?#

Install the matching extension from the window's Extensions section or with unity-mcp-cli install-extension. See Extensions.

Does it work in Play mode?#

Yes. The agent can enter and exit Play mode through RQL (editor members such as isPlaying). The connection reconnects after the domain reload.

Builds, CI and privacy#

Does the plugin end up in my game build?#

The runtime part compiles into player builds, but a build never connects on its own. You opt in from code with UnityMcpPluginRuntime.Initialize(...) to give an AI tools inside your game. To exclude the plugin entirely, add the UNITY_MCP_EXCLUDE_FROM_COMPILATION scripting define. See Configuration.

How do I keep it out of CI test runs?#

Set UNITY_MCP_DISABLE=1 in the environment of the Unity process, or use the UNITY_MCP_EXCLUDE_FROM_COMPILATION define. See Configuration.

Can I script it without an AI client?#

Yes. unity-mcp-cli run-tool calls any tool from a terminal, and unity-mcp-cli exec runs C# in the Editor. See the CLI reference.

What data leaves my machine?#

In Custom mode with none or token authorization, nothing goes through ai-game.dev: the agent and Unity talk through the local server. Your AI client still sends your conversation to its own model provider. In Cloud mode, tool calls and results pass through the ai-game.dev server on their way between your agent and the Editor.

How do I turn off the update popup for my team?#

Enable Disable update notifications for the entire team in Edit > Project Settings > AI Game Developer and commit ProjectSettings/AI-Game-Developer-UpdateSettings.asset.

More help#

• Troubleshooting for errors.
• The site-wide FAQ and Unity best practices.