Rules for agents driving the Unreal editor over MCP
Read this before your first MCP call. The background and measurements are in prep/MCP-RUNBOOK.md.
Setup
-
Connection. The editor is started with
prep/scripts/start-editor-mcp.ps1. The server ishttp://localhost:8000/mcp, local only, with no auth. Never expose it, proxy it, or point it at another host. -
Check before working. Run
python prep/scripts/mcp_client.py ping. If it is unreachable, the editor is closed, still loading (19 to 70 s), crashed, or showing a dialog. Say which one; do not retry in a loop. -
The tools. Three native tools:
list_toolsets,describe_toolset(toolset_name)andcall_tool(toolset_name, tool_name, arguments).-
tool_nameis the short name, for exampleadd_to_scene_from_asset. - Describe only the toolsets you need, once per session. Each description is 10 to 25 KB.
-
On 5.9 the surface is renamed (MCP-RUNBOOK, "Engine choice"): four native tools,
list_toolsets,describe_toolsets(toolset_names),describe_tools(tool_names)andcall_tool. Actors and levels areEditorToolset.ActorToolsetandEditorToolset.LevelToolset, assetsEditorToolset.AssetToolset. Tool names are PascalCase (AddToSceneFromAsset,SaveAsset), arguments camelCase (assetPath). Python iseditor_toolset.toolsets.python_scripting.PythonScriptingTools: callread_meonce, thenexecute_pythonwithscript: {"language": "Python", "content": "..."}. The check isprep/scripts/mcp_smoke59.py. - 5.9 busy reply. "Not run: the Unreal Editor is running a slow task" means nothing changed. Wait a few seconds and retry; it often follows a save or a compile.
-
One call at a time
- Calls run one by one on the editor's game thread. Never send calls in parallel.
-
Keep every call short. Claude Code gives up on a call after about 120 s.
-
Long work (cooking, packaging, video capture, mass imports) goes through scripts in
prep/scripts, not through one MCP call.
-
Long work (cooking, packaging, video capture, mass imports) goes through scripts in
-
Batching. For many small edits, use
ProgrammaticToolset.execute_tool_script. Callget_execution_environmentonce first, and keep each script to one logical step.
Never open a modal
- A modal dialog freezes MCP for everyone until a human clicks it. That includes Save prompts, "Are you sure", import option windows and the Plugins restart prompt. Avoid every action that opens one.
- If calls start timing out, stop. Report it and ask for a screenshot or a human.
- Never close the editor with unsaved changes. Save first (rule 11); closing a dirty level opens the Save dialog.
Save often, and only what you meant
-
Before a change:
-
Note the current level:
SceneTools.get_current_level. -
Note whether it is dirty:
AssetTools.is_dirty.
-
Note the current level:
-
After each finished step, save the assets you changed:
AssetTools.save_assetswith explicit paths. Do this at least every 10 minutes.- An empty list saves everything dirty. Use it only when you know what is dirty.
-
Commit through git by explicit paths after saving. Never use
git add -A,git add .orgit commit -a. - Don't fight other writers. Do not edit a level another agent is editing. Never save someone else's work-in-progress asset.
Verify everything you change
-
Read state back after every change:
-
Spawned:
find_actorsby label returns exactly one. -
Moved:
get_actor_transformmatches within 0.01. -
Deleted:
find_actorsreturns none. - Property set: get it again.
-
A tool's
returnValue: trueis not proof.
-
Spawned:
-
Look when it matters, not every step:
EditorAppToolset.CaptureViewport.-
Pass every parameter. Use
annotationsonly when you need the grid and labels. - Each image is about 0.5 MB of base64 text. Use it at milestones.
-
Pass every parameter. Use
-
Check the log after risky steps:
LogsToolset.GetLogEntrieswith a narrowpattern, for exampleError|Warning. -
Before saying a gameplay change works, run it:
-
Play:
EditorAppToolset.StartPIEthenStopPIE, or -
Package and smoke test:
prep/scripts/package.ps1thenprep/scripts/smoke.ps1.
-
Play:
What to avoid
-
Pass exactly what tools return. Do not guess object paths or property names; use the
refPathyou got back. For widgets and objects,list_propertiesbeforeset_properties. - No engine or editor settings changes without the lead agent's say. Never touch plugins, project settings, renderer settings, or anything that asks for a restart.
- No deleting assets or folders except ones you created in this session, by exact path. No wildcard deletes.
-
No third-party assets pulled in by an agent. No Fab, no Megascans, no web downloads. Sourced assets need Don and a line in
prep/SOURCED-ASSETS.md. -
Respect the jam rules.
-
Before Nov 12 00:00 ET: no game content at all. Only the
ToolCheckproject with engine primitives. - From Nov 12: everything players see or hear is Teen-rated and in English.
- No logos or trademarks except the Unreal Engine logo.
-
Before Nov 12 00:00 ET: no game content at all. Only the
- Live Coding does not pick up new UFUNCTIONs. After adding one, the editor must restart, and that is a human-approved step.
Level building
Method from Epic's article "Exploring AI-assisted level design in Unreal Engine" (Chris Cook, Nov 11, 2026).
-
Load
prep/LEVEL-CONTRACT.mdfirst, every time. Use its metrics; DEFAULT rows are placeholders, say so if the game has no value yet. - Block out from primitives before final assets. Name actors for what they are. Describe the space by purpose and relationships and leave room to propose.
-
Capture and inspect after each step with
python prep/scripts/scene_capture.py --args '{...}'(top-down, four corners, eye height, plus bounds, gaps and capsule clearance). It uses its own temporary cameras, so the editor viewport stays the user's. NeedsbRemoteExecution=True(runbook section 1). - Fix what the captures show: left and right reversals, gaps and slivers, doorway and landing clearances. One fix, then re-capture.
- Review at player scale from several angles and walk the routes (checklist in the contract). Furnish, terrain, vegetation and lighting come after the blockout passes.
-
Write what worked and what failed into the jam's lessons (
LESSONS.mdentry, with the numbers) so it can become a skill afterwards.
Your report back
- List what you changed (assets and actors by path), what you verified and how, and what you saved and committed. Give the exact error text of any failure.