Integration Guides - Unreal Master Agent

Hosts

Choose Your Host

Each guide includes prerequisites, config file location, a ready-to-paste snippet, and a verification step.

CLI

Claude Code

Node.js ≥20 · Claude Code CLI

Setup

Create or open .mcp.json in your project root (or ~/.claude/mcp.json for global scope).
Paste the config snippet on the right, then save. Alternatively run npx unreal-master-mcp-server init --host=claude-code to write it automatically.
Open your UE project, then start a new Claude session with claude in the terminal.

Verification

Run /tools in the Claude Code session — the tool list should include unreal-master-agent entries.

Troubleshooting

If tools don't appear, verify .mcp.json is in the project root (not a subdirectory). Restart the Claude Code session after editing the config.

.mcp.json

{
  "mcpServers": {
    "unreal-master-agent": {
      "command": "npx",
      "args": ["-y", "unreal-master-mcp-server"]
    }
  }
}

App

Claude Desktop

Node.js ≥20 · Claude Desktop app

Setup

Locate claude_desktop_config.json — see the config paths on the right for your OS.
Paste the mcpServers block into the file, or run npx unreal-master-mcp-server init --host=claude to auto-write it.
Quit and reopen Claude Desktop so it picks up the new config.

Verification

A hammer icon should appear in the Claude Desktop toolbar. Click it to confirm the MCP server list includes unreal-master-agent.

Troubleshooting

If the MCP icon doesn't appear, fully quit Claude Desktop (check system tray) and relaunch. Verify the config file path matches your OS — Windows: %APPDATA%\Claude\, macOS: ~/Library/Application Support/Claude/.

Windows%APPDATA%\Claude\claude_desktop_config.json

macOS~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "unreal-master-agent": {
      "command": "npx",
      "args": ["-y", "unreal-master-mcp-server"]
    }
  }
}

Editor

Cursor

Node.js ≥20 · Cursor editor

Setup

Create .cursor/mcp.json in your project root (per-project), or run npx unreal-master-mcp-server init --host=cursor to generate it.
Paste the config snippet on the right into that file and save.
Reload the Cursor window (Cmd/Ctrl+Shift+P → Reload Window) so the server is registered.

Verification

Open Cursor Settings → MCP. The unreal-master-agent server should appear with a green connected status.

Troubleshooting

If the server shows as disconnected, ensure .cursor/mcp.json is in the workspace root. Restart Cursor after config changes. Check the Output panel (MCP channel) for error messages.

.cursor/mcp.json

{
  "mcpServers": {
    "unreal-master-agent": {
      "command": "npx",
      "args": ["-y", "unreal-master-mcp-server"]
    }
  }
}

Editor

Windsurf

Node.js ≥20 · Windsurf editor

Setup

Open or create ~/.codeium/windsurf/mcp_config.json. Run npx unreal-master-mcp-server init --host=windsurf to write the file automatically.
Paste the config snippet on the right and save the file.
Restart Windsurf or click Refresh in the MCP panel for the server to connect.

Verification

Open Windsurf's MCP panel from the sidebar. The server connection status for unreal-master-agent should show as active.

Troubleshooting

If the server doesn't connect, verify the config at ~/.codeium/windsurf/mcp_config.json is valid JSON. Restart Windsurf after editing. Ensure Node.js 20+ is in your system PATH.

Config~/.codeium/windsurf/mcp_config.json

mcp_config.json

{
  "mcpServers": {
    "unreal-master-agent": {
      "command": "npx",
      "args": ["-y", "unreal-master-mcp-server"]
    }
  }
}

Extension

VS Code + GitHub Copilot

Node.js ≥20 · VS Code · Copilot v0.3+

Setup

Install the GitHub Copilot extension (v0.3+) from the VS Code Marketplace if not already present.
Create .vscode/mcp.json in your workspace root, or run npx unreal-master-mcp-server init --host=vscode. Note: VS Code uses a servers key with "type": "stdio".
Reload the VS Code window. The MCP server starts automatically when Copilot Chat is opened.

Verification

Open Copilot Chat and type @unreal — MCP tools from the server should autocomplete in the chat input.

Troubleshooting

If MCP tools don't appear, ensure GitHub Copilot extension is v0.3+ and agent mode is enabled. Verify .vscode/mcp.json uses the servers key (not mcpServers). Reload VS Code window after config changes.

.vscode/mcp.json

{
  "servers": {
    "unreal-master-agent": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "unreal-master-mcp-server"]
    }
  }
}

Note: VS Code uses "servers" (not "mcpServers") and requires "type": "stdio"

Prerequisites

Common Requirements

All integrations share these baseline requirements regardless of which host you choose.

Node.js 20 or later

The MCP server runs via npx. Node.js 20+ is required for native fetch, ESM support, and the --experimental-vm-modules flag used internally. Check with node --version.

Unreal Engine 5.4–5.7

The UnrealMasterAgent plugin requires UE 5.4 or later. Open your project, go to Edit → Plugins, and enable both UnrealMasterAgent and the built-in Python Editor Script Plugin.

WebSocket port 9877

The MCP bridge connects to the UE plugin over WebSocket on port 9877. Ensure this port is free on your machine. Override it by setting the UE_WS_PORT environment variable in the config.

Plugin installed in project

Copy the UnrealMasterAgent/ folder from the repository into your project's Plugins/ directory. Rebuild the project in your IDE so the C++ plugin compiles against your engine version.

One AI Host at a Time

Each MCP server instance opens a WebSocket connection to Unreal Engine on port 9877. Because each AI host (Claude Code, Cursor, VS Code, etc.) spawns its own server process, only one AI host can be connected to a given UE instance at a time. Starting a second host will fail with EADDRINUSE.

To switch hosts: Close or disconnect the current AI host first, then start the new one.
To use a different port for testing: Set "UE_WS_PORT": "9878" in the env block of your host config — but note the UE plugin must also connect to that same port.

Support

Troubleshooting

Common issues and their fixes. If a problem persists, open an issue on GitHub with your host name and Node.js version.

Symptom	Likely cause	Fix
Server not connecting	Wrong Node.js version or config file in wrong location	Run `node --version` and confirm it is 20+. Double-check that the config file is in the path expected by your host (see each guide above). Restart the editor after saving.
Tools not appearing	Unreal Engine is not running or the plugin is not enabled	Launch your UE project first, then start your AI session. Confirm UnrealMasterAgent shows as enabled in Edit → Plugins. The server only exposes tools once the UE WebSocket handshake succeeds.
WebSocket errors	Port 9877 is already in use or the plugin failed to load	Check that nothing else is listening on port 9877 (`netstat -an \| grep 9877`). If occupied, set `"UE_WS_PORT": "9878"` in the `env` block of your config and restart both UE and the AI host.
npx command not found	Node.js is installed but not on the system PATH seen by the editor	Use an absolute path in the config: replace `"command": "npx"` with the full path from `which npx` (macOS/Linux) or `where npx` (Windows). Alternatively, add Node.js to your system PATH and restart the editor.
Permission denied on macOS	Gatekeeper blocking the npx binary on first run	Run `npx unreal-master-mcp-server` once manually in the terminal to trigger the Gatekeeper approval dialog, then relaunch the host.
`EADDRINUSE` on port 9877	Another AI host's MCP server is already running and holding the WebSocket port	Only one AI host can connect to a UE instance at a time. Close the other host first, or find and kill the old process: `netstat -ano \| grep 9877` then `taskkill /PID <pid> /F` (Windows) or `kill <pid>` (macOS/Linux).

Advanced

SSE Transport

By default the MCP server uses stdio transport — the host process spawns the server as a child process and communicates over stdin/stdout. This works for all five hosts listed above and is the recommended setup for local development.

For remote or web-based setups (e.g. a shared dev server, a containerised UE instance, or a host that only supports HTTP), switch to SSE (Server-Sent Events) transport. The server listens on an HTTP port and the host connects over HTTP instead of spawning a subprocess.

Start the server in SSE mode and point your host config at the HTTP endpoint. The SSE server also accepts a UE_WS_PORT environment variable for the upstream UE WebSocket connection.

Terminal — start SSE server

# Start server in SSE mode on port 3000
npx unreal-master-mcp-server --transport=sse --port=3000

Host config — SSE endpoint

{
  "mcpServers": {
    "unreal-master-agent": {
      "transport": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}