Troubleshooting

Find your symptom, follow the steps. The logs usually name the problem, so the first section says where they are.

Symptom	Go to
🌐 The client can't connect over HTTP, or gets 401 / 400 / 403 / 503	Native HTTP client cannot connect
🔌 Every call answers NOT_CONNECTED	NOT_CONNECTED from the stdio server
🔢 The client lists 23 tools, or unreal twice	Wrong tool list
🟩 The stdio server doesn't start	The stdio server doesn't start
🧱 The plugin doesn't compile or load	The plugin does not build or load
🤖 The model keeps inventing names	The assistant invents names
✋ CONSENT_REQUIRED, PATH_NOT_PERMITTED, COMMAND_BLOCKED, RESULT_TOO_LARGE	Calls fail
⏳ Timeouts, or EDITOR_BLOCKED	Calls time out
🐢 The editor is slow, or Play-In-Editor runs at a few frames per second	Background throttling

Where to look

What	Where
Is the plugin loaded?	The status bar at the bottom-right of the level editor: MCP off means loaded with native HTTP off; MCP :3000 (N) means native HTTP is on with N clients connected. No indicator means 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, which your client shows in its MCP server log. Claude Desktop writes it under %APPDATA%\Claude\logs\ (Windows) or ~/Library/Logs/Claude/ (macOS); in Claude Code, use 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.

Connecting

Native HTTP client cannot connect

Work down the list:

1. Is the editor running with the project open? The native server lives inside the editor, so a client started first simply fails to connect. Reconnect the client once the editor is up (in Claude Code, through /mcp).
2. Does the status bar read MCP :3000? If it reads MCP off, tick Enable Native MCP Server in the plugin settings and restart the editor.
3. Is the port free? Failed to start Native MCP server on port 3000 in the Output Log means another program holds it. Change Native MCP Port (or set MCP_NATIVE_PORT) and update the client URL.
4. Is the URL right? It's http://127.0.0.1:3000/mcp, including /mcp, using the client's Streamable HTTP transport (Claude Code calls it http). 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. If you deleted the file or changed Capability Token, the token changed.
401 Capability token does not match this session	The token changed mid-session	Reconnect the client
400	The client asked for a protocol version the native server doesn't support	Update the client, or use the stdio route (protocol versions)
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

Note

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.

NOT_CONNECTED from the stdio server

The stdio server starts without the editor and connects on the first call, so the tool appears even when nothing is running. Every execute then answers like this:

Unreal Engine is not connected: no bridge listener responded at ws://127.0.0.1:8090.

1. Start the editor with the plugin, and check that the status bar indicator is there.
2. Check the port. The server dials MCP_AUTOMATION_PORT; otherwise the first Listen Ports entry of the project in UE_PROJECT_PATH; otherwise 8090. If UE_PROJECT_PATH points at a different project from the one that is open, the port can be wrong.
3. Is port 8090 taken by another program? The plugin skips a busy port and still listens on 8091. Set MCP_AUTOMATION_PORT=8091, or change Listen Ports.
4. Was the handshake refused? A UE_PROJECT_PATH is not set; cannot locate the capability-token file or Token file not readable warning means the server had no token to present, so the plugin refused it. Fix UE_PROJECT_PATH (the project folder or its .uproject), or set MCP_AUTOMATION_CAPABILITY_TOKEN.
5. Always Listen must be on in the plugin settings (it is by default).

The client lists 23 tools instead of unreal

That is the 0.5.30 server: npm's default tag still installs it. Use unreal-engine-mcp-server@beta (⬆️ Upgrading).

If the client shows the unreal tool twice, it has both routes configured. Keep one.

The stdio server doesn't start

• node --version must be 20.19 or later.
• On Windows, some clients can't launch npx directly. Use "command": "cmd" with "args": ["/c", "npx", "-y", "unreal-engine-mcp-server@beta"].
• Run the same command in a terminal to see its error: npx -y unreal-engine-mcp-server@beta. Started by hand, it sits waiting for MCP messages on stdin. That's normal; stop it with Ctrl+C.

The plugin does not 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
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
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
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 (list). PCG is compiled in only when the project itself enables PCG: enable it and rebuild.

Calls fail

The assistant invents names

UNKNOWN_CAPABILITY, UNKNOWN_TOOL, UNKNOWN_ACTION or UNDECLARED_PARAMETER, again and again, means the model guesses instead of following the workflow. The tool description and the server instructions both explain it, but not every client passes the instructions to the model.

Tip

Add one line to your prompt or project instructions: "Use the unreal tool: search, then describe, then execute, and copy each nextCall." Smaller models benefit most.

Refusals

Code	Why	Fix
CONSENT_REQUIRED	Expected for deletes and some other writes	The model should send the consentGrant from describe as consent; if it doesn't, tell it to (Security › Consent)
PATH_NOT_PERMITTED	The path isn't under /Game, /Engine, /Script, /Temp or /Niagara	Content from a plugin with its own mount point (e.g. /MyPlugin/...) needs that prefix in MCP_ADDITIONAL_PATH_PREFIXES on the stdio route. With a scoped token, the path must also be inside its allowed prefixes.
COMMAND_BLOCKED	The console command chains commands (;, &&, |, …) or is blocked, such as quit	Send one command per call
RESULT_TOO_LARGE	The reply would exceed about 100,000 characters (6,000,000 for images)	Narrow it with a filter, a folder or a limit

Calls time out, or the client gives up

• Long operations (lighting builds, imports, packaging, renders) can outlast your client's limit per tool call. In Claude Code, raise MCP_TOOL_TIMEOUT.
• Either route stops waiting for a single call after 5 minutes (a native Movie Render Queue render can wait longer). See ⚙️ Configuration › Timeouts.
• EDITOR_BLOCKED means the editor's game thread hasn't ticked for over 15 seconds, almost always because a modal dialog (save prompt, restore packages, an error) is waiting in the editor. Dismiss it and retry.

Important

The editor keeps working after a timeout. Read the state again before retrying, or retry with the same options.idempotencyKey so the work can't run twice.

The editor is slow, or Play-In-Editor runs at a few frames per second

Unreal throttles an editor that isn't the foreground window. Automation mostly runs while you're in another window, so everything slows down, and timing-sensitive Play-In-Editor checks (movement, physics) give nonsense results.

1. Turn off Edit › Editor Preferences › General › Performance › Use Less CPU when in Background.
2. Don't minimize the editor. A minimized editor is throttled even with that setting off.

Asking for help

Open an issue or a discussion with:

• plugin and server versions, engine version, operating system
• the route (native HTTP or stdio) and the client
• the failing request and its full reply (errorCode, message)
• the relevant LogMcp lines from the Output Log, and the stdio server log at LOG_LEVEL=debug if you use that route

Caution

Remove your capability token from anything you paste.

---

← 🔐 Security  ·  🏠 Home  ·  💬 FAQ →