unreal-mcp

# Unreal Engine MCP Skill

Companion skill for the `unreal-engine` entry in the Hermes MCP catalog. The
MCP server (Epic's official, experimental "Unreal MCP" plugin, internal id
`ModelContextProtocol`) runs INSIDE the Unreal Editor process and exposes
editor functionality as typed tools. This skill teaches how to drive it well:
discovering the live tool surface, sequencing calls safely, translating
plain-English asks into scenes that actually look good, and verifying work
visually. The user should never need to touch the editor beyond launching it.

## When to Use

Use when the user wants anything done in Unreal Engine: build or dress a
level, spawn/move/delete actors, set up lighting and atmosphere, create or
tune material instances, frame a camera shot, capture screenshots or renders,
import assets, inspect the scene or UI, run automation tests, or script the
editor. Works for single actions ("make the sun golden hour") and for
complete multi-step projects ("build me a moody forest clearing with a
campfire and render a shot of it").

Don't use for: DCC-style mesh modeling/sculpting (model in Blender and
import the result), or for editing Unreal C++ project source (that's normal
code work — use the terminal; this skill is about the live editor).

## Prerequisites

Two halves, in this order: the editor side must be up before Hermes connects.

### One-time, editor side

1. Unreal Editor **5.8+** with a project open. (macOS: full Xcode must be
   installed and its license accepted — the editor exits on first launch
   without it; see pitfalls.)
2. **Edit > Plugins** — enable **Unreal MCP** (its Toolset Registry
   dependency auto-enables). Restart the editor when prompted.
3. The typed toolsets ship separately from the server: also enable the
   **AllToolsets** plugin in the same Plugins browser. Unreal MCP ships NO
   tools itself — AllToolsets provides the shipped toolsets (SceneTools,
   ActorTools, MaterialInstanceTools, ObjectTools, …); skip it and the
   server connects but the agent has nothing to call.
4. **Edit > Editor Preferences > General > Model Context Protocol** — enable
   **Auto Start Server**. Default bind is `http://127.0.0.1:8000/mcp`
   (port/path configurable in the same panel; server name is `unreal-mcp`).
   To start manually instead, run `ModelContextProtocol.StartServer` in the
   editor console (backtick key).

### One-time, Hermes side

    hermes mcp install unreal-engine

This writes the `mcp_servers.unreal-engine` HTTP entry pointing at
`http://127.0.0.1:8000/mcp` and probes the live server for its tools. Run it
while the editor + server are up so the probe sees the real surface. If the
user changed port/path in Editor Preferences, edit the `url` in
`~/.hermes/config.yaml` under `mcp_servers.unreal-engine` to match.

Do NOT use `ModelContextProtocol.GenerateClientConfig` for Hermes — that
writes `.mcp.json`-style files for Claude Code/Cursor/etc. Hermes connects
from `config.yaml` via the catalog entry.

### Every session

1. Launch Unreal Editor, wait for the project to finish loading; confirm the
   server started (Output Log shows the bind address, or run
   `ModelContextProtocol.StartServer` manually).
2. Start the Hermes session. Tools register as `mcp_unreal_engine_*`. If
   they're missing: editor wasn't up first — start it, then open a new
   Hermes session.
3. Sanity check: call `mcp_unreal_engine_list_toolsets` and confirm toolsets
   come back.

## The Tool Surface: Discovery, Not a Fixed List

By default the plugin runs in **tool-search mode**: `tools/list` returns only
three meta-tools, and every real tool is reached through them. Through Hermes
they appear as:

| Hermes tool | Purpose |
|---|---|
| `mcp_unreal_engine_list_toolsets` | Names + descriptions of every registered toolset |
| `mcp_unreal_engine_describe_toolset` | Full JSON schemas for one named toolset's tools |
| `mcp_unreal_engine_call_tool` | Invoke a named tool with arguments, get the result |

The discovery walk, always in this order:

1. `list_toolsets` → see what capability groups this project actually has
   (the surface is project-dependent: enabled plugins, Game Feature Plugins,
   and any custom toolsets all contribute). Names come back FULLY QUALIFIED
   (`editor_toolset.toolsets.scene.SceneTools`,
   `EditorToolset.EditorAppToolset`) — use them verbatim as `toolset_name`.
2. `describe_toolset` on the group you need → read the real parameter
   schemas. Never guess parameter names — schemas are the contract.
3. `call_tool` with the qualified toolset name, the SHORT tool name
   (`find_actors`, not the dotted form), and arguments matching the schema.

Cache what you learn for the session; re-list only after the editor side
changes (new plugin enabled, toolset authored, `RefreshTools` run).

The alternative eager mode (`Enable Tool Search` off in Editor Preferences)
advertises every tool as its own `mcp_unreal_engine_<tool>` entry. Discovery
then happens at `hermes mcp install`/`configure` time instead. Tool-search
mode is the default and what this skill assumes; it also keeps schema tokens
out of every API call, so prefer it.

See `references/tool-surface.md` for the shipped toolset catalog, authoring
custom toolsets, and the full plugin configuration/console-command reference.

## Operating Loop

Every Unreal task follows the same loop:

1. **Inspect first.** List toolsets, then query the scene/level state before
   touching anything. Never assume an empty or default level. In an
   unfamiliar project, also check for project-registered Agent Skills
   (`call_tool` → `AgentSkillToolset.ListSkills`): a matching project skill's
   instructions override this skill's generic defaults.
2. **Act in small, single-purpose calls.** One logical step per `call_tool`.
   The server executes tools **serially on the game thread** — a big
   monolithic operation freezes the editor UI until it finishes and risks
   client timeouts. Exception: for loops over 5+ homogeneous operations,