# Troubleshooting Fix common Unity MCP problems - no tools in the AI client, sign-in and connection errors, server download failures, NuGet DLL errors and port conflicts. _Last updated: 2026-11-04_ This page collects the problems people hit most often with Unity MCP and how to fix them. Start with the quick checklist; if that does not help, find your symptom below. ## Quick checklist 1. Open **Window > AI Game Developer — MCP** and look at the timeline: **Unity**, **MCP server** and **AI agent** should all be green. 2. Check the Unity Console for errors. A compile error anywhere in the project stops the plugin's editor scripts from loading. 3. Run `unity-mcp-cli status ./MyUnityProject` to see whether Unity is running and which server is reachable. 4. Restart your AI client after any config change. 5. Make sure the plugin and your extensions are on current versions. ## The AI client shows no Unity tools - **The client connected before Unity was ready.** Reconnect the MCP server in the client (in Claude Code, `/mcp`), or restart the client after the window shows **Connected**. - **The client was not configured, or uses an old config.** Click **Configure** (or **Reconfigure**) for your agent in the window, or run `unity-mcp-cli setup-mcp .`, then restart the client. - **Cloud mode is not signed in.** The window shows "Authorization Required". Click **Authorize** and approve the code in the browser. - **Several projects are open.** An unpinned `https://ai-game.dev/mcp` URL may route to another Editor. Use the pinned URL that **Configure** writes. - **The agent is started from another folder.** Project-level configs such as `.mcp.json` or `.cursor/mcp.json` are only read when the client runs in the Unity project folder. - **In VS Code**, switch Copilot Chat to **Agent** mode. ## Cloud sign-in problems - **"Authorization Required" keeps coming back.** Your credential expired or was revoked. Click **Authorize** again, or run `unity-mcp-cli login --force`. - **"Connection Required".** Sign-in worked but Unity is not connected. Click **Connect**. - **Signed in as the wrong account.** Click **Revoke** (this signs out all AI Game Dev tools on the machine), then **Authorize** with the right account. `unity-mcp-cli login` asks before switching accounts. Session and device management for your account is described in [Authentication](https://ai-game.dev/docs/auth). ## The local MCP server does not start (Custom mode) - **The binary has not downloaded.** It goes to `Library/mcp-server//`. If the download failed (offline, firewall, proxy), the window shows "Server binary error" and a **Download / Retry server** button. You can also use **Tools > AI Game Developer > Server > Download Binaries**. - **Antivirus blocked the executable.** Allow `gamedev-mcp-server` in your security software, then retry. - **The transport is stdio.** With stdio the AI agent starts the server itself, so the **Start** button is disabled. Switch to `http` if you want Unity to run it. - **Read the server logs.** Use **Tools > AI Game Developer > Server > Open Logs** and **Open Log Errors**. - **Test the server directly.** **Tools > AI Game Developer > Server > Launch MCP Inspector** opens the MCP Inspector against the local server (HTTP transport only; needs Node.js). ## Port conflicts Each project gets a fixed port between 20000 and 29999 derived from its path. If something else already listens on it, the window shows the MCP server as **External**. Find the process: ```powershell netstat -ano | findstr : ``` ```bash lsof -i : ``` Stop that process, or disconnect and type another port into **Server URL** (for example `http://localhost:25000`), then click **Configure** again so the agent uses the new port. ## Disconnects during compilation Unity reloads scripts after every code change and when entering Play mode. The plugin disconnects before the reload and reconnects afterwards, so a short "Disconnected" or "Connecting..." is normal. A tool call that was in flight during the reload may fail; ask the agent to retry it. ## Compile errors or missing DLLs after install The plugin downloads its .NET dependencies from NuGet into `Assets/Plugins/NuGet`. - **Errors about missing types from McpPlugin, ReflectorNet or SignalR.** Wait for the first import to finish, then use **Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs**. - **"Path too long" on Windows.** Unity's runtime cannot open DLLs past Windows' 260-character path limit, even with long paths enabled. Move the project to a shorter folder, such as `C:/Projects/MyGame`. - **Clean reinstall.** Close Unity, delete `Assets/Plugins/NuGet` and its `.meta` file, and reopen the project. ## Project path with spaces If the Console shows "The project path contains spaces", move the project to a folder without spaces. The plugin warns because such paths may cause problems while using it. ## Tool calls fail or time out - **Errors such as "object not found".** Ask the agent to query first (for example with `rql-query`) instead of guessing names or paths. Asset paths start with `Assets/`. - **Long operations time out.** Raise **Tool timeout (ms)** in the window (default 300000) for slow bakes or large test runs. - **Screenshots fail in batch mode.** An Editor started with `-nographics` has no graphics device. Start headless without `-nographics`; `unity-mcp-cli open --headless` already does. - **A custom tool throws thread errors.** Wrap Unity API calls in `MainThread.Instance.Run`. See [Custom tools](https://ai-game.dev/docs/wiki/unity/custom-tools#main-thread). ## unity-mcp-cli problems - **`open` stops at "Enter Safe Mode?"** The CLI clicks **Ignore** automatically. On macOS grant your terminal Accessibility permission; on Linux install `xdotool`. - **`exec` waits and then gives up.** The project is open in an Editor the CLI did not start, and its plugin is not answering locally (for example it is connected to the cloud). Connect the plugin, switch it to Custom, or pass `--url`. - **`setup-skills` fails.** It needs a running Editor with the plugin connected. Run `open` and `wait-for-ready` first. - **Use `--verbose`** on any command for detailed logs. ## Full reset 1. Close Unity. 2. Delete `Library/mcp-server/` in the project. 3. Reopen Unity and choose **Tools > AI Game Developer > Reset Config**. 4. Sign in again (Cloud) or start the server (Custom), then click **Configure** for your agent. 5. Restart your AI client. ## Getting help Use **Help / Talk** (Discord) or **Bug Report** (GitHub issues) at the bottom of the AI Game Developer window. Include your Unity version, OS, plugin version (shown in the window), the error from the Console, and the steps to reproduce. You can also browse the [FAQ](https://ai-game.dev/docs/wiki/unity/faq) or the site-wide [FAQ](https://ai-game.dev/docs/faq). --- Source (HTML): https://ai-game.dev/docs/wiki/unity/troubleshooting