Architecture & tools

ClaudeUnreal exposes Unreal Engine to AI agents through a hybrid surface: a small typed MCP layer for the hot path, plus a Bash CLI (cu) for the long tail. Both share the same TCP bridge into the editor.

Why hybrid

Eager-loading 450 MCP tool schemas at session start costs ~144K tokens — about 72% of an Opus 4.7 context window before the user types a word. The hybrid split keeps the always-loaded surface tiny while preserving every capability behind a one-step lookup.

Metric	Before	After
MCP schema at session start (chars)	~504K	~25K
Eager-load context cost (tokens)	~144K	~7K
Tools always typed	~450	17

The three transports

                        ┌──────────────────────────────────┐
                        │   AI agent (e.g. Claude Code)    │
                        └──────────────────────────────────┘
                                    │           │
                  MCP stdio ────────┘           └──── Bash subprocess
                          │                                │
                          ▼                                ▼
        ┌──────────────────────────────┐    ┌──────────────────────────┐
        │   Python MCP server          │    │   cu CLI                 │
        │   (claude_unreal_server.py)  │    │   (Resources/MCP/cli/    │
        │   17 typed tools             │    │   cu.py)                 │
        │                              │    │   450 long-tail commands │
        └──────────────────────────────┘    └──────────────────────────┘
                          │                                │
                          └────────────┬───────────────────┘
                                       │
                                  TCP / JSON
                                127.0.0.1:55557
                                       │
                                       ▼
                  ┌──────────────────────────────────────┐
                  │   UClaudeUnrealBridge (C++)          │
                  │   DispatchSingleCommand              │
                  └──────────────────────────────────────┘
                                       │
                                       ▼
                  ┌──────────────────────────────────────┐
                  │   Per-category handlers (C++)        │
                  │   FClaudeUnrealEditorCommands etc.   │
                  └──────────────────────────────────────┘
                                       │
                                       ▼
                  ┌──────────────────────────────────────┐
                  │   UE5 engine APIs                    │
                  │   UEditorActorSubsystem, FBlueprint- │
                  │   EditorUtils, UAssetRegistry, ...   │
                  └──────────────────────────────────────┘

The bridge is unchanged from the original architecture — both MCP and CLI clients send the same JSON to the same TCP port. The split lives entirely on the client side.

The 17 always-loaded tools

Hot-path actions (13)

Common operations that appear in nearly every session, kept as typed MCP tools so the AI client’s schema-aware tool calling stays accurate:

ping, get_actors_in_level, get_selected_actors, find_actors_by_name, spawn_actor, delete_actor, get_actor_properties, set_actor_transform, set_actor_property, set_actor_component_property, take_screenshot, focus_viewport, exec_console_command.

Discovery meta tools (3)

The bridge into the long-tail surface:

• unreal_categories() — landscape view of all 21 categories.
• unreal_search(query, category?, limit?) — keyword-rank search of the manifest.
• unreal_doc(command) — full reference for a single command.

Helper (1)

• unreal_session_brief() — one-call session bootstrap (current level + selected actors).

The long tail

The other ~450 commands (Blueprint nodes, UMG widgets, Niagara modules, PCG graphs, sequencer keys, …) are not loaded as MCP tools. They live in the cu CLI and the bundled manifest.json. Find and run one in three steps:

1. unreal_search("<keyword>") — find candidates.
2. unreal_doc("<command>") — read params and example.
3. cu exec <command> --params-json '<json>'.

In practice, from any Bash prompt:

cu ping                                   # probe the bridge
cu search "focal length camera"           # find candidates (no TCP)
cu help set_camera_focal_length           # full reference (no TCP)
cu exec set_camera_focal_length --params-json '{"camera_name":"Cam01","mm":50.0}'

Note

cu help <command> equals unreal_doc(<command>), and cu search mirrors unreal_search — stay in MCP or switch to Bash, same answer. cu list / cu help / cu search even work with the editor closed (they read the bundled manifest; no TCP needed).

On Claude Code the plugin writes a cu wrapper at <ProjectDir>/.claude/cu and allows Bash(cu *) automatically. On other MCP clients, call cu directly — see Use with any MCP client.

MCP Mode: standalone or mount on official (UE 5.8)

On UE 5.8, Unreal ships its own MCP server (Epic’s ModelContextProtocol plugin) with a Toolset Registry that any plugin can register tools onto. ClaudeUnreal can plug into it. Project Settings → Plugins → Claude Unreal exposes an MCP Mode selector:

Mode	What it does
Standalone (default)	Runs ClaudeUnreal’s own MCP server + the cu CLI over the TCP bridge — the full hybrid surface described above. Works on UE 5.7 and 5.8.
Mount on official (UE 5.8 only)	Registers ClaudeUnreal’s tools onto Epic’s built-in MCP server via the Toolset Registry, and removes the claude-unreal entry from .mcp.json so your agent sees exactly one MCP server — no duplicate tools.

Under the hood, “Mount on official” reuses the same C++ handlers: each registered tool packs its typed args into the same JSON the TCP bridge already dispatches and runs it in-process on the game thread.

For the step-by-step setup (enabling Epic’s plugins, the console commands to start the server and write the config), see Mount on UE 5.8’s official MCP server.

Scope

“Mount on official” registers a toolset (ClaudeUnreal.ClaudeUnrealOfficialToolset) onto Epic’s Toolset Registry; the server exposes a gateway — list_toolsets, describe_toolset, call_tool — not top-level tools. The toolset contains SpawnActor, GetActorsInLevel, and TakeScreenshot, reached via call_tool. This mode is UE 5.8-only. For the complete surface, stay on Standalone (the default) and use the cu CLI for the long tail. The cu CLI is unaffected by the mode — it always talks to the bridge directly.