Connecting Clients

Two ways for an MCP client to reach the editor. Both expose the same single unreal tool, so pick whichever your client handles best, and give each client one of them, not both.

flowchart LR
    q["Can your client connect to an HTTP MCP server<br/>and send a custom request header?"]
    q -- "Yes" --> A["Route A · Native HTTP"]
    q -- "No, or not sure" --> B["Route B · stdio"]
    classDef ask fill:#30363d,stroke:#8b949e,color:#f0f6fc
    classDef route fill:#1f6feb,stroke:#58a6ff,color:#ffffff
    class q ask
    class A,B route

Loading

	🌐 Route A · Native HTTP	🧩 Route B · stdio
How	The plugin serves MCP at http://127.0.0.1:3000/mcp	The client launches unreal-engine-mcp-server, which talks to the plugin over a WebSocket on 127.0.0.1:8090
Node.js	❌ Not needed	✅ 20.19 or later
Capability token	You put it in the X-MCP-Capability-Token header	Read from the project automatically, given UE_PROJECT_PATH
Several clients at once	✅ Up to 16 sessions	Each client runs its own server process
Editor must be running when the client starts	✅ Yes: the server lives in the editor	❌ No: the server connects on the first call

The plugin must already be installed: 📦 Installation.

Route A: native HTTP

1. Switch it on

In Edit › Project Settings › Plugins › MCP Automation Bridge › Native MCP:

• tick Enable Native MCP Server (it's off by default);
• leave Native MCP Port at 3000 unless something else uses it.

Restart the editor. ✅ Checkpoint: the status bar shows MCP :3000 (0), and the Output Log contains:

LogMcpNativeTransport: Native MCP server started on http://127.0.0.1:3000/mcp

2. Get the capability token

With default settings, the endpoint answers 401 Invalid capability token to any request without your project's token. The plugin creates the token the first time the editor starts:

<YourProject>/Saved/MCP/capability-token

It is 64 hexadecimal characters. If you type your own Capability Token into the plugin settings, that value is used instead. Rotation, scoped tokens and turning the token off are covered in 🔐 Security.

3. Add the server to your client

Claude Code

claude mcp add --transport http unreal-engine http://127.0.0.1:3000/mcp --header "X-MCP-Capability-Token: <token>"

Or commit a project-scoped .mcp.json that reads the token from an environment variable, so the secret stays out of the repository:

{
  "mcpServers": {
    "unreal-engine": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "X-MCP-Capability-Token": "${UNREAL_MCP_TOKEN}"
      }
    }
  }
}

Long editor operations (lighting builds, imports, packaging) can outlast the client's limit per tool call. Raise it with the MCP_TOOL_TIMEOUT environment variable (milliseconds).

Cursor

~/.cursor/mcp.json, or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "unreal-engine": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "X-MCP-Capability-Token": "<token>"
      }
    }
  }
}

VS Code

.vscode/mcp.json. The inputs block makes VS Code ask for the token once and store it, rather than keeping it in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "unreal-mcp-token",
      "description": "Unreal MCP capability token (Saved/MCP/capability-token)",
      "password": true
    }
  ],
  "servers": {
    "unreal-engine": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "X-MCP-Capability-Token": "${input:unreal-mcp-token}"
      }
    }
  }
}

Other clients

Any client that supports Streamable HTTP and custom request headers works with the URL and header above. If yours can't send headers, use Route B instead, or switch off Require Capability Token. Read Security › Turning the token off first: that lets any program on your machine drive the editor.

4. Check it

• ✅ The status bar count goes up when the client connects: MCP :3000 (1).
• ✅ The client lists exactly one tool from this server: unreal.
• ✅ The Output Log, filtered by LogMcpNativeTransport, shows the session and then two lines per call. Each call is logged under the internal tool and action it was routed to:

LogMcpNativeTransport: MCP session initialized (active sessions: 1)
LogMcpNativeTransport: Received notification: notifications/initialized
LogMcpNativeTransport: tools/call: control_editor [play] (RequestId=DF2B071B48E19342B5BC1D92188B5605)
LogMcpNativeTransport: tools/call completed: DF2B071B48E19342B5BC1D92188B5605 (tool=control_editor, success=true)

Route B: stdio through Node.js

The package is unreal-engine-mcp-server on npm.

Warning

Use the @beta tag for the 0.6 line. Plain unreal-engine-mcp-server still installs 0.5.30, which doesn't match a 0.6 plugin.

Two environment variables matter:

• UE_PROJECT_PATH: your project folder or its .uproject file. The server reads the capability token from Saved/MCP/capability-token and the plugin's port from Config/DefaultGame.ini.
• LOG_LEVEL (optional): debug, info (default), warn or error. Logs go to stderr, never stdout.

Everything else is on ⚙️ Configuration.

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "unreal-engine": {
      "command": "npx",
      "args": ["-y", "unreal-engine-mcp-server@beta"],
      "env": {
        "UE_PROJECT_PATH": "C:/Path/To/MyGame"
      }
    }
  }
}

Claude Code

claude mcp add unreal-engine --env UE_PROJECT_PATH=C:/Path/To/MyGame -- npx -y unreal-engine-mcp-server@beta

On native Windows, put cmd /c before npx.

Cursor, Windsurf, VS Code and others

The same command / args / env block as Claude Desktop works in Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and most other clients. VS Code uses "servers" instead of "mcpServers" and needs "type": "stdio".

Tip

If a Windows client reports that it can't find npx, launch it through cmd: "command": "cmd" with "args": ["/c", "npx", "-y", "unreal-engine-mcp-server@beta"].

From a clone

After npm install and npm run build in the repository, point the client at the built server:

{
  "mcpServers": {
    "unreal-engine": {
      "command": "node",
      "args": ["C:/Path/To/Unreal_mcp/dist/cli.js"],
      "env": {
        "UE_PROJECT_PATH": "C:/Path/To/MyGame"
      }
    }
  }
}

Docker

The repository's Dockerfile builds an image that runs the stdio server:

docker build -t unreal-mcp .

The container has to reach the editor's WebSocket, which only listens on 127.0.0.1, so this is practical on Linux with host networking. The container can't read your project folder, so pass the token directly:

{
  "mcpServers": {
    "unreal-engine": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host", "-e", "MCP_AUTOMATION_CAPABILITY_TOKEN", "unreal-mcp"],
      "env": {
        "MCP_AUTOMATION_CAPABILITY_TOKEN": "<token>"
      }
    }
  }
}

Use -i without -t: a TTY corrupts the JSON-RPC stream.

Check it

• ✅ The client lists one tool from this server, unreal, even while the editor is closed.
• ✅ The first call connects to the editor. If the editor isn't running, calls answer NOT_CONNECTED and name the address they tried, for example ws://127.0.0.1:8090.
• 🔎 Run with LOG_LEVEL=debug to see the connection attempts and handshake in the client's server log.

Several editors, several clients

Setup	How
Two editors, native route	Give each editor its own port. Set MCP_NATIVE_PORT in the environment that launches the editor (it overrides Native MCP Port without touching the project's config), then point each client entry at its port.
Two editors, stdio route	Give each project different Listen Ports (for example 8092,8093) and set each client entry's UE_PROJECT_PATH to its project. The server dials the first port listed in that project's settings.
Several clients, one editor	The native route serves up to 16 sessions at once, for example Claude Code and Cursor side by side.

Starting a second editor on port 3001 from PowerShell:

$env:MCP_NATIVE_PORT = "3001"; & "C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor.exe" "C:\Path\To\OtherGame\OtherGame.uproject"

Tell the assistant about your project

Server Instructions, in the Native MCP settings, is free text that the plugin appends to the instructions native clients receive when they connect. Most clients add those instructions to the model's context once per session. Use it for conventions:

All gameplay Blueprints live under /Game/Core/Blueprints. Widgets are named WBP_*.

On the stdio route, put the same text in your client's own project instructions, for example CLAUDE.md for Claude Code.

Remote machines

Both routes listen on loopback only. Reaching the editor from another machine takes deliberate settings on both sides: see 🔐 Security › LAN access.

---

← 📦 Installation  ·  🏠 Home  ·  🧭 Using the Gateway →