Persistent "socket hang up" and "handshake failed" issues with Unreal Engine 5.7.3 and Docker

[victorien-code]

What happened?

When trying to use the McpAutomationBridge plugin with Unreal Engine 5.7.3 and Docker, I consistently encounter a "socket hang up" error when executing MCP commands, such as control_actor to spawn an actor. The connection between the MCP server and Unreal Engine is established, but the handshake validation fails, causing the commands to fail.

What did you expect to happen?

I expected the MCP server to successfully connect to Unreal Engine and execute commands without errors. Specifically, the control_actor command should spawn an actor in the Unreal Engine scene, and there should be no "socket hang up" or handshake validation errors in the logs.

Unreal Engine Version

UE 5.7

MCP Client

Claude Desktop

Environment Information

MCP Server: ghcr.io/chiR24/unreal-engine-mcp-server:latest (used via Docker)
MCP Plugin: McpAutomationBridge version 0.1.1
OS: Windows 11 (Version 22H2, Build 26200.7840)
Node.js Version: 18.x (LTS)
MCP Server Version: ghcr.io/chiR24/unreal-engine-mcp-server:latest
Docker Version: Docker Desktop 24.0.7
Visual Studio Version: Visual Studio 2022 (Version 17.8)
Architecture: x64
Python Version: 3.9.x

Steps to Reproduce

1. Install MCP using Docker Desktop Tool:

Open Docker Desktop and use the MCP tool to pull the ghcr.io/chiR24/unreal-engine-mcp-server:latest image.
Configure the connection to Unreal Engine Remote Control API with the following settings:

unreal-engine-mcp-server.log_level: debug
unreal-engine-mcp-server.ue_host: host.docker.internal
unreal-engine-mcp-server.ue_rc_http_port: 8090
unreal-engine-mcp-server.ue_rc_ws_port: 8091

Download the Repository and Set Up the Plugin:

Download the Unreal_mcp repository as a .zip file from ChiR24/Unreal_mcp.
Extract the .zip file and copy the McpAutomationBridge plugin folder into your Unreal Engine project's Plugins/ directory:
Copier

C:\Users<user>\Documents\Unreal Projects<project_name>\Plugins\

Open Unreal Engine and Compile the Plugin:

Open your Unreal Engine project (version 5.7.3).
Enable the McpAutomationBridge plugin via Edit > Plugins.
Configure the plugin settings:

Listen Host: 0.0.0.0
HTTP Port: 8090
WebSocket Port: 8091
Check Allow Non Loopback.

Enable the Python plugin and check "Allow Remote Execution".
Close Unreal Editor.
Generate project files by double-clicking on your .uproject file.
Open the generated .sln file in Visual Studio 2022.
Build the McpAutomationBridge project in Development Editor and Win64 configuration.
Restart Unreal Editor.

Verify Open Ports and Docker Configuration:

Ensure the ports 8090 and 8091 are open and correctly mapped in Docker.
Check the Docker container logs to ensure the MCP server is running correctly:
bash
Copier

docker logs <container_id>

Test MCP Connection via LM Studio:

Use LM Studio to send MCP commands.
Try to spawn an actor using the following command:
bash
Copier

mcp_control_actor spawn /Script/Engine.Character '{"x": 100, "y": 200, "z": 100}' '{"pitch": 0, "roll": 0, "yaw": 0}'

Observe the WebSocket error:
json
Copier

[
{
"type": "text",
"text": "Failed to execute control_actor: Failed to spawn actor via Python: Error: socket hang up"
}
]
2.
3.

Relevant Logs

LogMcpAutomationBridgeSubsystem: Accepted automation client from 127.0.0.1:53559
LogMcpAutomationBridgeSubsystem: Warning: Server handshake validation failed (upgrade=false, connection=false, version=false, hasKey=false).
LogRemoteControlWebInterface: [Success] Remote control web interface is running - WebApp started, 127.0.0.1:30000

Additional Context

Error Response:
[
{
"type": "text",
"text": "Failed to execute control_actor: Failed to spawn actor via Python: Error: socket hang up"
}
]

The issue occurs consistently with the described setup.
The problem seems related to the handshake validation between the MCP server and Unreal Engine.
The WebSocket connection is established but fails during the handshake process.
I have tried disabling handshake validation in the plugin source code, but the issue persists.
I have also tested without Docker using npx, but the same error occurs.

[github-actions]

👋 Thanks for opening this issue! We appreciate your feedback and report. A maintainer will check this out soon.

[Kaen-SG]

I've tried using LM Studio and local models but failed due to the high amount of context tokens required by this mcp.
A hello prompt requires 46,228 context tokens... so make sure your machine and model settings can handle this.

[Kaen-SG]

Also there are some issues building the most current version of the mcp plugin. I'm not sure if that's been fixed yet but you can also try grabbing the version in the releases tagged v0.5.18.

[victorien-code]

I've tried using LM Studio and local models but failed due to the high amount of context tokens required by this mcp. A hello prompt requires 46,228 context tokens... so make sure your machine and model settings can handle this.
Nemotron 3 Nano with a standard graphic card let you go up to 130 000 tokens of context.

[ChiR24]

Hi @victorien-code! Thanks for the detailed bug report.

I see you're using the Docker MCP Hub image (mcp/unreal-engine-mcp-server). That image is outdated - it was built from commit 16f9fea (November 2025), which is ~3 months behind the current version (0.5.18, February 2026).

The outdated image uses a different architecture:

• It was designed to work with Unreal's built-in Remote Control API (no plugin needed)
• The current version uses the MCP Automation Bridge Plugin (requires installing the plugin in your UE project)

You have two options:

1. Use the old Docker image → Enable Remote Control API in UE instead of the MCP plugin
2. Use the latest version → Build your own Docker image or use npx unreal-engine-mcp-server with the MCP plugin installed

The handshake error you're seeing is a protocol mismatch between the old Docker image (Remote Control protocol) and the new MCP Automation Bridge plugin.

Let me know which approach you'd prefer and I can help you get set up!