Where to look first
| What | Where |
|---|---|
| Is the plugin loaded? | The status bar at the bottom-right of the level editor. MCP off: loaded, native HTTP off. MCP :3000 (N): native HTTP on with N clients. No indicator: the plugin didn't load. |
| Plugin log | Window › Output Log, filtered by LogMcp. The native HTTP server logs as LogMcpNativeTransport. The same lines are in <YourProject>/Saved/Logs/<YourProject>.log. |
| stdio server log | stderr, shown in your client's MCP log. Claude Desktop: %APPDATA%\Claude\logs\ or ~/Library/Logs/Claude/. Claude Code: claude --debug or /mcp. Set LOG_LEVEL=debug for connection details. |
| The failing call | The reply's errorCode, message and nextCall. Its receipt.correlationId matches log lines. |
The plugin doesn't build or load
| You see | Fix |
|---|---|
| "Missing Modules … Engine modules cannot be compiled at runtime. Please build through your IDE." | Generate project files, build the Editor target in Visual Studio, Rider or Xcode, then open the project. |
| "The following modules are missing or built with a different engine version: McpAutomationBridge" | Answer Yes to rebuild. Binaries built for another engine minor or platform won't load; rebuild from source for your engine (reported in #195 and #166). |
| No way to compile at all | The project is Blueprint-only. Add a C++ class (Tools › New C++ Class) or use prebuilt binaries. |
| "Plugin 'McpAutomationBridge' failed to load" on the first open | Close the editor and open the project again; it loads once the build has finished. |
| Compile errors after an update | Delete Plugins/McpAutomationBridge/Binaries and Intermediate, then rebuild. Make sure the plugin folder was replaced, not merged with the old one. |
| Compile errors on your engine version | Open an issue with the engine version and the first errors from the build log. Known version issues are listed on engine versions. |
| The build runs out of memory | The plugin has many source files. Close other programs, or lower UnrealBuildTool's parallel job count. |
| A capability says its engine plugin is missing | Enable that engine plugin. PCG is compiled in only when the project itself enables PCG: enable it and rebuild. |
A native HTTP client can't connect
Work down the list:
Is the editor running with the project open? The native server lives inside the editor, so a client started first simply fails. Reconnect it once the editor is up (in Claude Code, through
/mcp).Does the status bar read
MCP :3000? If it readsMCP off, tick Enable Native MCP Server and restart the editor.Is the port free?
Failed to start Native MCP server on port 3000in the Output Log means another program holds it. Change Native MCP Port (or setMCP_NATIVE_PORTfor the editor process) and update the client URL.Is the URL right?
http://127.0.0.1:3000/mcp, including/mcp, using the client's Streamable HTTP transport (Claude Code calls ithttp). Clients limited to the old SSE-only transport won't work.
Then match the HTTP status:
| Status | Meaning | Fix |
|---|---|---|
401 Invalid capability token | The X-MCP-Capability-Token header is missing or wrong | Copy Saved/MCP/capability-token again, without a trailing newline. Deleting the file or changing Capability Token changes the token. |
401 Capability token does not match this session | The token changed mid-session | Reconnect the client |
| 400 | Unsupported MCP protocol version | Update the client, or use the stdio route |
403 Invalid Origin | The request came from a web page | Browser origins are only accepted while token auth is on |
| 503 | More than 32 simultaneous connections | Close clients you don't use |
The native server keeps at most 16 sessions. When all are taken, one idle for two minutes gives up its slot, and any session expires after an hour without activity. Reconnect after an expiry.
Every call answers NOT_CONNECTED (stdio)
The stdio server starts without the editor and connects on the first call, so the tool appears even when nothing is running. Calls then answer something like Unreal Engine is not connected: no bridge listener responded at ws://127.0.0.1:8090.
Start the editor with the plugin and check the status bar indicator is there.
Check the port. The server dials
MCP_AUTOMATION_PORT, else the first Listen Ports entry of the project inUE_PROJECT_PATH, else 8090. IfUE_PROJECT_PATHpoints at a different project from the one that's open, the port can be wrong.Is 8090 taken? The plugin skips a busy port and still listens on 8091. Set
MCP_AUTOMATION_PORT=8091, or change Listen Ports.Was the handshake refused? A
UE_PROJECT_PATH is not set; cannot locate the capability-token fileorToken file not readablewarning means the server had no token. FixUE_PROJECT_PATH, or setMCP_AUTOMATION_CAPABILITY_TOKEN.Always Listen must be on in the plugin settings (it is by default).
Running the stdio server in Docker? The editor's WebSocket listens on 127.0.0.1, so the container needs host networking (practical on Linux) and the token passed as MCP_AUTOMATION_CAPABILITY_TOKEN. Use -i without -t: a TTY corrupts the MCP stream. Handshake failures with Docker on Windows are reported in #232.
The wrong tools show up
- 23 tools instead of
unreal: that's the 0.5.30 server, which npm's default tag still installs. Useunreal-engine-mcp-server@beta. unreallisted twice: the client has both routes configured. Keep one.- The stdio server doesn't start:
node --versionmust be 20.19 or later. On Windows, launch throughcmd:"command": "cmd","args": ["/c", "npx", "-y", "unreal-engine-mcp-server@beta"].
Calls fail or time out
| Code | Why | Fix |
|---|---|---|
UNKNOWN_CAPABILITY, UNDECLARED_PARAMETER (repeatedly) | The model guesses names instead of following the workflow | Add to your prompt or project instructions: "Use the unreal tool: search, then describe, then execute, and copy each nextCall." |
CONSENT_REQUIRED | Expected for deletes and some writes | The model should send the consentGrant from describe as consent |
PATH_NOT_PERMITTED | Path outside /Game, /Engine, /Script, /Temp, /Niagara | Add plugin mount points to MCP_ADDITIONAL_PATH_PREFIXES on the stdio route |
COMMAND_BLOCKED | Chained or blocked console command | Send one command per call |
RESULT_TOO_LARGE | Reply over about 100,000 characters (6,000,000 for images) | Narrow it with a filter, folder or limit |
EDITOR_BLOCKED | The game thread hasn't ticked for 15+ seconds, almost always a modal dialog | Dismiss the dialog in the editor and retry |
Long operations (lighting builds, imports, packaging, renders) can outlast your client's per-call limit; in Claude Code raise MCP_TOOL_TIMEOUT. The editor keeps working after a timeout, so read the state again before retrying, or retry with the same options.idempotencyKey so the work can't run twice.
Slow editor or Play-In-Editor at a few frames per second? Unreal throttles a background editor. Turn off Editor Preferences › General › Performance › Use Less CPU when in Background, and don't minimise the editor.
FAQ
What should I include when asking for help?
Plugin and server versions, engine version and OS; the route (native HTTP or stdio) and client; the failing request and its full reply; and the relevant LogMcp lines. Remove your capability token from anything you paste. Post in Issues or Discussions.
Can I reach the editor from another machine?
Only deliberately: both routes are loopback-only by default. See security for the LAN settings.
My token stopped working.
It changes if the token file is deleted or the Capability Token setting is edited. Copy the current file again and reconnect.