Unreal-MCP: Instructions file for Codex

AGENTS.md — Unreal-MCP

Unreal-MCP connects MCP clients (Claude, Cursor, Copilot, …) to Unreal Engine — the Unreal sibling of Unity-MCP and Godot-MCP. Editor mode (default) drives the Unreal Editor; opt-in runtime mode drives a running PIE / Standalone / packaged Development build. Status: beta. The MCP server is the shared GameDev-MCP-Server (gamedev-mcp-server); no server code lives here — server changes go to that repo.

docs/ARCHITECTURE.md is authoritative (defer to it on conflict; read the relevant section before non-trivial work): IPC §1, tool registration §2, schema §3, dispatcher §4, extensions §5, sidecar §6, UI §7, config §8, repo/CI §9, roadmap §10, risks §11, runtime §12, prompts & resources §A. Other docs: README.md (users; canonical tool inventory), docs/RELEASING.md, docs/EXTENSIONS.md (extension authors), docs/RUNTIME-E2E.md (in-game walkthrough).

Architecture

Unreal is C++ and cannot host the .NET McpPlugin/ReflectorNet/SignalR stack in-process, so it runs in an auto-managed .NET 9 sidecar (unreal-mcp-bridge, bridge/), a local child of whatever loads the plugin (Editor, or the game in an opt-in packaged build). The C++ plugin listens on loopback TCP; the sidecar dials it with a one-shot token sent over stdin (never argv, never logged — §1.4) and relays IPC ⇄ SignalR to the MCP server (cloud ai-game.dev by default, or a local gamedev-mcp-server).

Do not conflate the two child processes: unreal-mcp-bridge (always, when connected) and gamedev-mcp-server (Custom/local mode only; downloaded by the CLI, pinned by cli/src/lib/server-version.ts SERVER_VERSION, overridden by UNREAL_MCP_SERVER_PATH; the editor can Start/Stop it via FUnrealMcpServerManager, Custom + http only).

Runtime mode (§12). Locked decisions: reuse the sidecar (no in-process C++ server); runtime infra + ping live in UnrealMcpRuntime; a shipped game never auto-connects. UUnrealMcpRuntimeSubsystem (a UGameInstanceSubsystem) only arms the listener; a connection is an explicit Connect(Host, Token, Mode, bAllowRemoteHost) (C++, Blueprint, or UnrealMcp.Connect console command). The runtime built-in surface is ping only (a system tool, so tools/list is legitimately empty; the UnrealMcp.RuntimeSubsystem spec asserts the registry is exactly {ping}); all engine-development tools are editor-only, and games bring their own via IUnrealMcpToolProvider. Security gates, all in Connect() (§12.8): opt-in only; kill switch UUnrealMcpRuntimeSettings::bRuntimeMcpEnabled (Project Settings → Plugins → Unreal MCP (Runtime), DefaultGame.ini, default false); Shipping gate bUnrealMcpAllowShipping in *.Build.cs (default false → UNREAL_MCP_ALLOW_SHIPPING=0, also controls staging the sidecar into Shipping); loopback host unless bAllowRemoteHost=true; loopback IPC + stdin token. Desktop only (Win64/Mac/Linux). Consumers exclude the plugin from packaged games with a TargetDenyList: ["Game","Client","Server"] in their own .uproject plugin reference (not our .uplugin); any game-module dependency on an UnrealMcp* module overrides that.