| name | 02-unreal-mcp-driving |
| description | Operating the UE 5.8 Unreal MCP server from Claude Code — enabling the plugin, generating client config, discovering toolsets, and the safety rules for agent-driven editor work. Use whenever automating Unreal Editor (spawning actors, editing levels, materials, running tests) via MCP. |
Driving Unreal Editor through MCP
UE 5.8 ships an experimental Unreal MCP plugin: an embedded MCP server in
the editor that exposes engine operations as tools over local HTTP. This is
the primary way agents build levels and content in this project.
Official docs: https://dev.epicgames.com/documentation/unreal-engine/unreal-mcp-in-unreal-editor
One-time setup (per machine)
- Edit → Plugins → search "Unreal MCP" → enable → restart editor.
Deliberately not enabled in
UETPFCore.uproject — this is a public
template and MCP is a local dev tool, not a project dependency. Do not
"fix" that by committing the plugin flag.
- Edit → Editor Preferences → Model Context Protocol → enable
Auto Start Server. Default endpoint:
http://127.0.0.1:8000/mcp.
- In the editor console:
ModelContextProtocol.GenerateClientConfig ClaudeCode
This writes .mcp.json into the project root. It is gitignored —
per-machine, never committed.
- Launch Claude Code from the project root so it picks up
.mcp.json.
Discovering tools
The server is self-describing. Always start with the meta-tools:
list_toolsets — enumerate available toolsets (SceneTools, ActorTools,
MaterialInstanceTools, ObjectTools, and experimental ones like
AttributeSetToolset).describe_toolset — get the tools and schemas inside one toolset.call_tool — invoke a specific tool.
Toolsets evolve every engine release; discover, don't memorize.
Safety rules (non-negotiable)
- Serial calls only. The server executes on the game thread, serially.
Never issue overlapping/parallel MCP calls — queue them.
- Localhost only, no auth. Never bind it to a non-loopback address,
never tunnel it. Anyone who can reach the port owns your editor.
- Save deliberately. Agent edits dirty the level/assets like hand edits.
Review what changed (File → Save All shows the dirty list) before saving;
don't leave a half-mutated level for the next session.
- Verify with automation tests. The MCP surface can run automation
tests — after any scripted content build, run the relevant
Scripts\test.bat filter or the in-editor test before declaring success.
- Content is binary.
.umap/.uasset changes can't be diffed in
review. Prefer regenerable content: PCG graphs, data assets, and scripted
construction over hand-tuned one-offs, so a reviewer can re-run the recipe.
Project workflow pattern
For repeatable scene construction (e.g., city blocks):
write the construction as a sequence of MCP calls driven from a checked-in
recipe (JSON/data asset), not as an unrecorded interactive session. The
recipe is the artifact; the level is its output.
