Troubleshooting

Fix common Unreal MCP problems - plugin not loading, bridge missing, connection stuck, AI agent without Unreal tools, stale builds and tool errors.

Updated November 4, 2026 View as Markdown

This page lists the problems people hit most often with Unreal MCP and how to fix them. Start with the quick checks, then jump to the matching section.

Quick checks

  1. Is the plugin loaded? The Output Log should contain [Unreal-MCP] plugin loaded after the editor starts.
  2. What does the window say? Open Tools, AI Game Developer and read the status line (Connected, Connecting, Reconnecting, Disconnected or No MCP bridge).
  3. What does the CLI see? Run unreal-mcp-cli status --path ./YourProject.
  4. Read the log. Use Open log file in the window, filter the Output Log by the LogUnrealMcp category, or ask the agent for console | where Verbosity == "Error".

The plugin does not load

If there is no [Unreal-MCP] plugin loaded line, the editor module failed to start.

  • Look in the Output Log for a start-up error from the plugin or a broken .uplugin.
  • Make sure the project is a C++ project with a working compiler toolchain. See Installation.
  • If Unreal says modules are missing or the plugin is incompatible, let it rebuild, or open the project with unreal-mcp-cli open ./YourProject, which builds the native modules first and dismisses those prompts.

An update has no effect

Unreal's incremental build can keep old plugin code when the plugin's source changes but its old Intermediate/ folder survives.

  • Update with unreal-mcp-cli update ./YourProject, which cleans the build cache by default.
  • After a manual copy: close the editor, delete Plugins/UnrealMCP/Intermediate/ and the C++ files in Plugins/UnrealMCP/Binaries/ (keep Binaries/ThirdParty/), then reopen.

"No MCP bridge" or the bridge keeps restarting

The plugin needs its bridge process, unreal-mcp-bridge. The window shows the bridge state and a restart count.

  • If the log says no sidecar binary resolved for rid <rid>, no bridge was found.
    • App or CLI install: the bridge is bundled. Re-install with unreal-mcp-cli install-plugin ./YourProject (or from the app); the package may be missing your platform.
    • Source checkout: build one with unreal-mcp-cli bootstrap-local ./YourProject, or set UNREAL_MCP_BRIDGE_PATH.
  • Click Restart bridge in the window footer after fixing the cause.

Stuck on "Connecting" or "Reconnecting"

  • Cloud mode: check you are signed in. If the window shows "Sign in required", your saved sign-in expired; click Authorize and approve the new code.
  • Check that the machine can reach ai-game.dev (proxy or firewall rules).
  • Custom mode: make sure the local server is running (Start in the MCP server card, or --start-server) and that the Server URL points at it.
  • Use Disconnect, then Connect, or Restart bridge.

Local server says "No connected clients"

If a local gamedev-mcp-server logs No connected clients. Retrying and then answers with HTTP 500, the editor is still in Cloud mode and connected to ai-game.dev instead of your local server. Switch to Custom in the window, set UNREAL_MCP_CONNECTION_MODE=Custom, or pass --connection-mode Custom (or --host) to unreal-mcp-cli open.

The AI agent has no Unreal tools

  • Check the agent's config: run unreal-mcp-cli setup-mcp <agent> --path ./YourProject --dry-run and compare, or click Configure (or Reconfigure) in the AI agent section.
  • Restart or reload the agent after the config changes. Many clients read MCP configs only at start-up.
  • Claude Code reads .mcp.json from the folder you start it in; start it in the project folder.
  • If you configured with setup-mcp before ever opening the editor, the config may point at localhost instead of the cloud. Open the project once, then run setup-mcp again, or pass --url.
  • Check the AI agents row in the Connection section. If your agent is not listed, it is not connected to the same server as the editor.
  • If you hid tools in the MCP Tools window or set UNREAL_MCP_TOOLS, the agent sees fewer tools.

The agent reaches the wrong editor

With several editors on one account, use the project-pinned URL (/mcp/p/<pin>), which setup-mcp writes by default. Re-run setup-mcp without --no-pin. See Connecting AI clients.

401 errors in the agent

  • In Cloud mode, a URL-only config needs the agent to sign in itself. Either let it run its OAuth sign-in, or sign the machine in (unreal-mcp-cli login) and run setup-mcp again so the config carries a project key.
  • If the project key was revoked, use Regenerate key in the editor or setup-mcp --regenerate-key.
  • In Custom mode with token auth, the config must carry the same token as the editor. Use Reconfigure after generating a new token.

Tool calls time out

One tool call may run for 5 minutes by default. Raise UNREAL_MCP_TOOL_TIMEOUT (milliseconds) for long Python scripts or big imports. python-execute also has its own timeout (default 30 seconds) that the agent can set per call.

Screenshot tools return an error

Pixel capture needs a GPU-backed editor. Under -nullrhi the screenshot tools return a structured error. unreal-mcp-cli exec and open --headless start editors that render off-screen, so captures still work there.

Python tools fail

python-execute uses Unreal's Python Editor Script Plugin, which Unreal MCP enables. If Python is unavailable, check that the plugin is enabled in Edit, Plugins. Errors point at lines of snippet.py, which is the code the agent sent.

Extension does not show up

  • Extensions need Unreal Engine 5.7 or later and Unreal MCP 0.26.0 or later.
  • After installing, the extension must be compiled: reopen the editor, use --build, or Compile (Live Coding) in the Extensions section.
  • Check that the extension is enabled in the Extensions section.

Still stuck?

  • See the FAQ and the general FAQ.
  • Use Help / Talk in the window to ask on Discord, or Bug Report to open a GitHub issue. Include the Unreal version, your OS, the window's status line and the relevant log lines (never your tokens).