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.

Updated November 4, 2026 View as Markdown

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 <agent> ., 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.

The local MCP server does not start (Custom mode)

  • The binary has not downloaded. It goes to Library/mcp-server/<platform>/. 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:

netstat -ano | findstr :<port>
lsof -i :<port>

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.

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 or the site-wide FAQ.