Open the books

RAW FILE: MCP-RUNBOOK.md, as written during the jam

Source prep/MCP-RUNBOOK.md in the jam repo. Last git commit of this file: 2026-11-11. About 5,433 words. Scrubbed only for private details and one line about another entrant. Mistakes left in on purpose.

Unreal MCP and build runbook (MegaJam prep)

Pre-jam tooling, written 2026-11-09. Everything here was run on the laptop (Unreal 5.8.3, RTX 4090 Laptop) against the throwaway project prep/toolcheck/ToolCheck.uproject (engine primitives only). Tower 2 was used as the backup build machine.

Engine choice: Wednesday's gate (5.9.0 or 5.8.4; Don leans to 5.9)

Epic posted the "Unreal Engine 5.9 MegaJam Preview" (5.9.0-preview-1) on the forum on Nov 9: https://forums.unrealengine.com/t/unreal-engine-5-9-megajam-preview/2852840

Recommendation of 2026-11-09 morning, superseded by the update below: build the jam game on 5.8.3. It is proven end to end today on both machines: MCP, headless packaging, smoke test and capture. The 5.9 preview gains are agent comfort, not things the judges score. Its risks land where a 4-day jam can't absorb them: crashes, a stale-package bug, and an untested toolchain on tower 2. If Don wants a look, he can install 5.9 beside 5.8 from the launcher and try Unreal Assistant on a copy of ToolCheck on Nov 10 or 11. Don't switch the jam project.

Update 2026-11-09 evening: Don is installing 5.9 on the laptop and tower 2 and updating 5.8.3 to 5.8.4. The jam engine is now decided by a Wednesday morning gate, not by this section: 5.9 gets the same proof 5.8 passed (MCP drive, clean package, smoke, OBS take, tower 2 package) plus one test per new area below; if all pass, the jam runs on 5.9, else on 5.8.4 (smoke rerun after the update). The game folder is empty until midnight, so nothing is converted.

Gate result, Wed 2026-11-11, 08:40 to 09:22 ET

Jam engine: 5.9.0. Every check passed. Each agent check was built by headless Claude Code (Sonnet) through MCP, then read back by a second, independent script. The two 5.9 snags, the background throttle and the "slow task" replies, came down to a config file and a retry. The throttle fix applies to 5.8.4 too. 5.8.4 also passed its rerun, so it stays a tested fallback.

Laptop: D:\megajam\ue59test\ToolCheck59 on D:\Epic_Games\UE_5.9\UE_5.9. Tower 2: G:\ue59test\ToolCheck59. Gate outputs (zips, takes, logs, the MetaSound render): D:\megajam\gate1111\ on the laptop.

CheckResultTime (ET)Evidence
Editor start with MCPPASS08:4170 s on the first start, 15 to 19 s on later starts; 128 toolsets
MCP drive, script (mcp_smoke59.py)PASS08:48Spawn, move, read back, delete, re-save: 1.6 s, 9 to 40 ms per call (after fix 1 below)
mcp_client.py describe and schema on 5.9PASS08:50Detects the 5.9 surface; exit 2 on an unknown name
MCP drive, headless Claude CodePASS08:57claude -p (Sonnet, --mcp-config .mcp.json --strict-mcp-config): spawn, move, read back, delete, save in 27 s, 10 turns
Clean package, laptop (editor open)PASS08:49 to 08:52-Clean, Development: build 175 s, zip 37 s; staged 644.2 MB, zip 362.5 MB; 0 errors
Packaged smoke, laptop zipPASS08:53Map loaded at 12 s, 0 errors or ensures, total 86 s
Clean package, tower 2PASS08:41 to 08:42-Clean, Development: 81 s total (build 58 s, zip 23 s), 362.5 MB; copied to the laptop in 4 s, SHA-256 matched
Packaged smoke, tower 2 zip (on the laptop)PASS08:54Map loaded at 11 s, 0 errors, total 34 s
OBS take, laptopPASS08:55, 09:181920x1080, 60 fps, 30.6 s, the scene in frame (the 5.8 bar). Second take with a test tone: audio max -9 dB, RECORDING OK. See finding 6
Remote Python executionPASS09:00 to 09:02Agent ran execute_python twice and saved and read back an asset (31 s). Remote execution on (fix 3): Epic's remote_execution.py found the editor node and ran a script
Geometry Script callPASS09:02Agent: box plus sphere plus plane cut, saved /Game/GateCheck/Geo/SM_GateGeo (65 s). Read back: 210 triangles
Niagara burst, agent-builtPASS09:04/Game/GateCheck/FX/NS_GateBurst from a template, burst count 60 read back (105 s). Read back: compile UpToDate, no errors, no warnings
MetaSound, agent-builtPASS09:05 to 09:09/Game/GateCheck/Audio/MS_GateTone: sine, AD envelope, multiply, output (78 s). Rendered by the engine: 440 Hz, sounds 0.81 s, max -9.1 dB. A looping variant, placed in the map and packaged, was heard in the OBS take
PCG graph on a CC0 meshPASS09:07Kenney Car Kit cone.fbx (CC0) imported in the editor; grid into Static Mesh Spawner; 16 cones (75 s). Independent regenerate: 16 instances of the cone. Level left clean
5.8.4 fallback: clean package and smokePASS09:01 to 09:03Package 79 s, 354.5 MB; smoke map at 13 s, 0 errors, total 51 s
5.8.4 fallback: MCP smoke (mcp_smoke.py, port 8001)PASS09:050.5 s; 55 toolsets

Findings (fixed or worked around today):

  1. The background throttle switch was in the wrong file, on both engines. UEditorPerformanceSettings is config=EditorSettings, so bThrottleCPUWhenNotForeground=False in DefaultEditorPerProjectUserSettings.ini is ignored. With it there, 5.9 and 5.8.4 both answered every MCP call in about 330 ms. In Config/DefaultEditorSettings.ini it works: 12 to 40 ms with the editor in the background, on both. Section 1 now says so, and prep/toolcheck has the file.
  2. 5.9 busy reply. Right after a save or a compile, a call can return "Not run: the Unreal Editor is running a slow task" with isError. Nothing changed; wait and retry. mcp_smoke59.py retries for up to 60 s.
  3. Remote Python execution is bRemoteExecution=True under [/Script/PythonScriptPlugin.PythonScriptPluginSettings] in DefaultEngine.ini, not in the per-user file. It needs an editor restart. The engine default binds localhost with TTL 0, so it stays on this machine. MCP's own execute_python needs no setting.
  4. Headless Claude Code works now (Don's login). The project folder is not trusted, so Claude Code ignores .claude/settings.json allow lists. Pass --allowedTools with the four 5.9 tools (mcp__unreal-mcp__list_toolsets,mcp__unreal-mcp__describe_toolsets,mcp__unreal-mcp__describe_tools,mcp__unreal-mcp__call_tool) and < /dev/null for stdin. Each agent check cost $0.13 to $0.43 on Sonnet (API-equivalent figures from --output-format json).
  5. An unfocused editor or game mutes itself. To render audio in the editor, set au.DisableAppVolume 1 first, and give stop_recording_output a path relative to Saved, not an absolute one. An unfocused packaged game mutes too, which made the first take with sound silent. record-obs.ps1 now launches the game with -ini:Engine:[Audio]:UnfocusedVolumeMultiplier=1.0 for takes only. The shipped game's default is unchanged.
  6. An agent session cannot bring the game window to the front. SetForegroundWindow, even with the Alt-key handoff now in record-obs.ps1, fails from this session. The game then ran at about 8 to 20 fps during takes, measured from its log frame counter. That is the known background throttle (section 8), it is the same on 5.8, and it is not from the editor (20 fps with the editor closed) or from Windows power throttling (turning that off did not help). The script now prints Game window in front: True/False. Record the submission takes with the game in front: from Don's own desktop, or from a task started in his interactive session.
  7. Cooking with the editor open works on 5.9 (section 6, gotcha 7 holds). Copying the 362 MB zip from tower 2 to the laptop with scp took 4 s.
  8. Tower 2 has had a 5.9 editor open from the launcher since Nov 9 (Don's session). It was left alone; it did not get in the way of headless packaging.

Installed engines (checked 2026-11-10): laptop 5.8.4 at D:\Epic_Games\UE_5.8 and 5.9.0 at D:\Epic_Games\UE_5.9\UE_5.9; tower 2 5.8.4 at G:\Epic_Games\UE_5.8 and 5.9.0 at C:\Program Files\Epic Games\UE_5.9. package.ps1 and start-editor-mcp.ps1 look only in the 5.8 folders, and ue_import.ps1 defaults to the laptop's 5.8, so on 5.9 every call passes -EngineDir (or -Engine). The 5.9 MCP check is mcp_smoke59.py, and mcp_client.py describe and schema detect 5.9 (built for the gate, 2026-11-11). mcp_smoke.py stays the 5.8 check.

5.9 results so far (2026-11-09, tower 2, 5.9.0 at C:\Program Files\Epic Games\UE_5.9):

AreaCount, 5.8.4 to 5.9What's new
Niagara+92Edit API types: emitter handles, stateless emitters and templates, simulation stages
Widgets+87
Audio+59
PCG+34
Materials+31material and material instance toolsets
MetaSound+9authoring, discovery and inspection toolsets
Toolsets73 to 170

These are names only. Whether an agent can build a working Niagara burst or MetaSound is still the Wednesday gate test. A headless editor start took 23 min on 5.9's first run against 10 on 5.8, so warm the cache before the jam.

MachineFirst run (cold)Second run (warm)Exit codes
Tower 2 (G:\ue59test\ToolCheck59)2622 s (43.7 min)99 s0, 0
Laptop (D:\megajam\ue59test\ToolCheck59)4369 s (72.8 min)187 s0, 0

Areas 5.9 opens to agents, each with a 10 minute gate check and a fuller study after the jam:

One exception worth testing: AnimGenOffline (5.9 preview plugin, announced by Epic's John van der Burg on X, Nov 9). It generates animation in Sequencer from a spline path, keyframe poses, Control Rig poses or a text prompt, with NVIDIA Kimodo as the first backend, and retargets automatically. That would close our Kimodo to Manny retarget gap (ASSET-PIPELINES.md), and generated motion is ours, so it scores, unlike Manny's template animations. The plan: 5.9 runs as an animation side tool only. Generate clips there, export them as FBX and import them into the 5.8.3 jam project. (Written when the jam was planned on 5.8.3. If the gate picks 5.9, AnimGenOffline runs inside the jam project and the FBX hop is not needed; on 5.8.4 the hop stands. 5.9 was installed 2026-11-09.) Before the jam (Nov 10 or 11), test it on a copy of ToolCheck: a walk on Manny, the FBX hop into 5.8.3, and foot slide measured against the BODYLAB bar (sbm/docs/BODYLAB.md). Our Kimodo trial beat the CMU retarget by 2 to 3 times but missed that bar. Needs from Don: the 5.9 install (launcher, EULA), and a Hugging Face account with a read token, because the plugin downloads its weights itself. The text prompt mode needs Kimodo's gated Llama 3 encoder (about 16 GB, Meta's license, which Don must accept) and may not fit on the laptop's 16 GB GPU while the editor runs. Path and keyframe modes worked without it in our trial. The 5.8.4 hotfix (Oct 20) lists no MCP changes, so it isn't worth an engine change this week either.

1. Project setup that works (copy into the jam project on Nov 12)

ToolCheck.uproject plugins:

Config/DefaultEditorPerProjectUserSettings.ini:

[/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]
bAutoStartServer=True
ServerPortNumber=8000
ServerUrlPath=/mcp
bEnableToolSearch=True

Config/DefaultEditorSettings.ini (corrected at the 5.9 gate, 2026-11-11: the switch is config=EditorSettings, and in the per-user file above it was ignored on both 5.8.4 and 5.9):

[/Script/UnrealEd.EditorPerformanceSettings]
bThrottleCPUWhenNotForeground=False

This matters a lot. A background editor ticks a few times a second, and every MCP call waits for a tick. Measured: about 330 ms per call with throttling on, 12 to 40 ms with it off.

On 5.9, also: leave ModelContextProtocol out of the .uproject plugin list (5.9 turns it on by default; see the 5.9 results above), and for Epic's Python pattern add to DefaultEngine.ini:

[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
bRemoteExecution=True

Config/DefaultGame.ini needs this rule. AllToolsets pulls the GameFeatures plugin into the editor, and the editor then asks for an asset manager rule for GameFeatureData. The rule must be editor-only. A runtime rule makes the packaged game fire an ensure at startup ("Failed to load class /Script/GameFeatures.GameFeatureData"), which the smoke test caught.

[/Script/Engine.AssetManagerSettings]
+PrimaryAssetTypesToScan=(PrimaryAssetType="GameFeatureData",AssetBaseClass="/Script/GameFeatures.GameFeatureData",bHasBlueprintClasses=False,bIsEditorOnly=True,Directories=((Path="/Game/Unused")),SpecificAssets=,Rules=(Priority=-1,ChunkId=-1,bApplyRecursively=True,CookRule=Unknown))

Config/DefaultEngine.ini:

.claude/settings.json in the project pre-allows the three MCP tools. .mcp.json is generated by the editor (step 2).

2. Start the editor with MCP

powershell -NoProfile -ExecutionPolicy Bypass -File prep\scripts\start-editor-mcp.ps1 -Project <path>\Game.uproject

What it does:

Measured startup, from launch to MCP answering with toolsets:

LaunchSecondsNotes
First ever70New project, shaders compiling
Second55Throttle still on
Third29
Fully warm19

Toolsets are ready within 2 s of the server answering. 5.8.3 with All Toolsets exposes 55 toolsets.

3. Prove it end to end (no agent needed)

python prep\scripts\mcp_smoke.py      # 5.8
python prep\scripts\mcp_smoke59.py    # 5.9: same steps with the renamed tools, and retries on "slow task"

The script does this, reading state back after each step:

  1. initialize
  2. list_toolsets (checks SceneTools and ActorTools are present)
  3. Spawns /Engine/BasicShapes/Cube as MCP_SmokeCube
  4. Finds it
  5. Moves it to (250, -125, 300) and reads the transform back
  6. Deletes it and confirms find_actors no longer returns it
  7. Re-saves the level if it was clean before

Last run on 2026-11-09: all PASS, 0.5 s total, 11 to 41 ms per call.

For manual pokes, use python prep\scripts\mcp_client.py:

4. Claude Code connection

  claude -p "List the Unreal toolsets, then spawn /Engine/BasicShapes/Cube named CC_TestCube with SceneTools add_to_scene_from_asset, move it with ActorTools set_actor_transform, read it back, delete it, confirm with find_actors." --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__unreal-mcp__list_toolsets,mcp__unreal-mcp__describe_toolset,mcp__unreal-mcp__call_tool"

--mcp-config skips the approval prompt. The login is still needed.

5. How the MCP surface looks (5.8.3, tool search mode)

6. Gotchas found today

  1. A modal dialog blocks MCP completely. While the editor showed "Save Content", every call timed out. If calls suddenly time out, look at the screen. Most often the cause is a dialog, or the editor crashed (an HTTP 502 also means a crash).
  2. Spawn then delete still dirties the level, and the next editor close opens the Save dialog (gotcha 1). Save with AssetTools.save_assets before closing. The smoke script does this.
  3. "Optional" parameters are not optional. CaptureViewport without annotations fails with "input param needs a default value". Pass every parameter in the schema.
  4. Passing annotations: {} turns the grid and labels overlay on.
  5. CaptureViewport is expensive. It returns a 1310x557 PNG as base64 inside JSON text, about 557 KB per call. It also takes about 1.2 s. Use it sparingly.
  6. Descriptions are big. describe_toolset for SceneTools is 24 KB and for ActorTools 17 KB; list_toolsets is 13 KB. Agents should describe only the toolsets they need, once per session.
  7. Cooking with the editor open works on 5.8.3. A forum report on 5.8.0 said the cook fought the editor for port 8000. In 5.8.3 the commandlet skips config auto-start, and all of today's packages were built with the editor open.
  8. Claude Code times out MCP calls at about 120 s. Keep each call short. Run long work (packaging, capture) from scripts, not as one MCP call.
  9. One editor per port. A second editor on the same project fails to bind 8000. Use -Port 8001 with the start script for a second project.
  10. Fresh projects have no toolsets until All Toolsets is enabled (5.8.x forum reports, and 5.9 UE-412135). ToolCheck enables it in the .uproject.
  11. serverInfo comes back with empty name and version. This is harmless. The protocol version is 2025-06-18.

6b. Epic's own pattern: Claude Code, MCP, Python, Geometry Script and PCG (read 2026-11-10)

[line about a named third party removed]

7. Headless packaging

powershell -NoProfile -ExecutionPolicy Bypass -File prep\scripts\package.ps1 -Project <path>\Game.uproject -TeamName BYOKGames -GameName <GameName> [-Config Shipping]

What it runs:

Then it zips the archive to <OutDir>\TeamName_GameName.zip, with a top folder of the same name. It prints the largest files, the staged size, the zip size and the time of each phase, and writes a JSON summary. Exit codes: 10 = build failed, 12 = zip over -MaxMB (950).

Measured on ToolCheck, final config (SM6, no pdb, editor-only plugins):

MachineConfigBuild+cook+stageZip timeStagedZip
LaptopDevelopment62 s (195 s right after a renderer config change)29 s627.7 MB355.3 MB
LaptopShipping24 to 64 s20 to 22 s430.0 MB290.6 MB
Tower 2Development (first ever, empty shader cache)525 s41 s626.8 MB354.5 MB
Tower 2Shipping64 s14 s429.1 MB289.8 MB

Tower 2's Shipping zip was copied back (SHA-256 matched) and passed the smoke test on the laptop.

Earlier runs show what each setting costs:

Where a blank project's size goes (Shipping, 430 MB staged):

So an empty game is already about 290 MB zipped. That leaves about 650 MB for our content.

Keeping the build small:

Tower 2 as backup build machine:

8. Smoke test every build (minutes)

powershell -NoProfile -ExecutionPolicy Bypass -File prep\scripts\smoke.ps1 -Zip <...>\BYOKGames_Game.zip [-Seconds 15]
powershell -NoProfile -ExecutionPolicy Bypass -File prep\scripts\smoke.ps1 -Exe <...>\Game.exe -Mode Quit   # Development only

-Zip extracts to a temp folder, which also proves the zip is whole, and deletes that folder afterwards.

Run mode:

  1. Launches the player-facing exe windowed with a fresh -abslog.
  2. Waits for LoadMap in the log (Shipping writes no log, so it waits for a responsive window instead).
  3. Holds -Seconds.
  4. Checks the window is still responding, then sends WM_CLOSE (same as clicking X).
  5. Requires: exit code 0, no new Saved\Crashes folder, no fatal, assert or unhandled exception in the log, and the log past frame 1. Any other Error: or Ensure condition failed line also fails, unless it matches $AllowedErrors at the top of the script (empty today; add a pattern only with a reason in a comment).

It prints error and ensure counts and the time to the first frame, and exits 1 on any failure.

Quit mode passes -ExecCmds="quit". Shipping ignores ExecCmds, so the script falls back to Run mode there.

Measured on ToolCheck (SM6):

What the long cold times mean for the judges: on the first launch from a new folder, the game runs fine, but closing it waits for background PSO (shader pipeline) compiles. That took 30 to 120 s here. A judge who quits in the first minute will see the window hang before it closes. Fixes for the jam build:

Two more measured traps:

Files