Docs · Best Practices · Unreal Engine
Effective AI requests in Unreal Engine
Actors, levels, and the Blueprint authoring surface with a compile feedback loop the AI can read and act on.
What it is
Unreal-MCP (branded "AI Game Developer — Unreal") is a C++ editor plugin for the Unreal Editor. It exposes Unreal Editor operations — spawning actors and components, editing levels and maps, authoring and compiling Blueprints, managing Content-Browser assets, reading/scaffolding/editing/compiling C++, and capturing viewport screenshots — as AI Tools, so an MCP-compatible AI client can drive the Unreal Editor through natural language. Because Unreal’s editor is C++, the .NET MCP host runs as an auto-managed sidecar process (unreal-mcp-bridge) the plugin spawns and talks to over localhost IPC.
Unreal Engine 5.5+ (tested on 5.7), a C++ Unreal project. Install via unreal-mcp-cli (npm).
Tool-family map
You never call tool ids by hand — but knowing the families helps you frame requests and ask the agent "what can you do with X?". The full searchable catalog lives on the Unreal Engine tools page.
| Family | Tools | Purpose |
|---|---|---|
| Actor & Component | 13 | Spawn/destroy/duplicate/find/modify actors; set-parent; add/get/modify/destroy/list components; get/modify any UObject by path. |
| Blueprint | 11 | Create Blueprint classes; add components; add/modify variables; set CDO defaults; add functions & events; compile (structured error/warning loop); spawn into level. |
| Asset & Content | 11 | AssetRegistry find/get-data; create-folder, copy, move, delete, refresh; Material Instance create/modify/get-data; FBX/texture import. |
| Editor & Reflection | 9 | Play-In-Editor get/set; selection get/set; console get/clear logs; run console command/CVar; UFunction find + call. |
| Level / Map | 7 | Create, open, save, get-data; list loaded sublevels (World-Partition aware); set-current; unload streaming sublevel. |
| Source / C++ | 6 | Read (sliced), create-class (header+cpp), update, delete, list module files, compile (Live Coding or UBT, structured error report). Jailed to <Project>/Source/. |
| Screenshot | 4 | Viewport, game view, camera (SceneCapture2D), isolated-actor renders. |
| Ping | 1 | Liveness probe — round-trips plugin ⇄ sidecar ⇄ server. |
Unreal-MCP’s core plugin exposes 62 tools across the 8 families listed here. On top of that, 6 Unreal-AI-* extension packages (via the IUnrealMcpToolProvider contract) now add a further 28 tools — Control Rig, Enhanced Input, GAS, Landscape, Niagara, and PCG — each gated on its wrapped UE engine plugin. See /docs/extensions/unreal.
Example prompts
Copy-pasteable first requests. Start with one, verify in the editor, then build up.
Create a new Actor blueprint with a static mesh cube and place three of them in the level.Spawn a `StaticMeshActor` named `Crate` at the player start, then move it up by 200 units and rotate it 45 degrees.Create a new level called `Arena`, open it, and list every actor in it.Take a screenshot of the editor viewport so I can see the layout.Create a new C++ Actor class called `Pickup`, add a Tick override, then compile the C++ and report any build errors.Create a Blueprint named `BP_Door` that extends Actor, add a `StaticMeshComponent` called `Body`, then add a `BeginPlay` event.Add a `TakeDamage` function to `BP_Player`, then compile `BP_Player` and tell me about any errors or warnings.
Your first request
A tiny, verifiable loop to confirm everything works.
- Open the AI Game Developer window from the editor Tools menu, choose Cloud, click Authorize, and wait for the connection to go green.
- Ask your client: "Ping the Unreal plugin to check the connection."
- Ask: "Spawn a StaticMeshActor named `Crate` at the world origin, then take a viewport screenshot."
- Confirm the actor appears in the level and read back the screenshot.
- Move into Blueprints — "Create a Blueprint named `BP_Door` that extends Actor, add a StaticMeshComponent, then compile it and report any errors."
Discover what the agent can do
Discovery is conversational — ask the agent these in order to map its capabilities.
- Ping the Unreal plugin to check the connection. (ping)
- List every tool you can call, grouped by the 8 families.
- What can you do with Blueprints specifically? (surfaces the 11-tool Blueprint family)
- List every actor in the current level. (level-get-data)
- Is the editor currently in Play-In-Editor? (editor-application-get-state)
- Pick one family (e.g. Blueprint) and ask for a tiny concrete action plus a viewport screenshot.
Common pitfalls
- C++ project required. The plugin builds an Editor module, so the host project must compile C++. A Blueprint-only project will not load it.
- The sidecar is auto-managed but real. If the connection will not go green, it is usually the unreal-mcp-bridge sidecar / IPC or auth, not the tools. ping round-trips the whole chain.
- Compiles block and can be slow. blueprint-compile and source-compile run inline on the game thread; expect a pause. The payoff is a structured error/warning list — "compile and fix the errors" is the intended loop.
- C++ source edits are jailed to <Project>/Source/ — the Source/C++ tools never touch engine source.