Part 8 — AI-assisted development: Unreal MCP + Claude Code

UE 5.8’s headline workflow change isn’t a rendering feature — it’s the Unreal MCP plugin, a first-party MCP (Model Context Protocol) server embedded inside the editor process. It lets any MCP-compatible AI agent — Claude Code, Cursor, the MCP Inspector — connect over a local HTTP link and actually drive the editor: spawn actors, set up lighting, create material instances, inspect UI widgets, run automation tests, and more. As a developer this should feel familiar: it’s the same tool-calling pattern as any MCP server, except the “tools” are editor operations and the live scene is the context.

8.1 The mental model (it’s an MCP server, the editor is the host)

• The plugin’s engine identifier is ModelContextProtocol; its friendly name in the Plugin Browser is Unreal MCP. It depends on the Toolset Registry plugin (auto-enabled).
• It runs an HTTP MCP server inside the editor, by default bound to http://127.0.0.1:8000/mcp.
• Tools = editor functions the agent can call (typed params/returns), discovered from toolsets — shipped ones include SceneTools, ActorTools, MaterialInstanceTools, ObjectTools (authored in Python).
• Tool calls run serially on the game thread, so a connected client shouldn’t fire overlapping calls — the engine processes them one at a time to stay thread-safe.

If you’ve written or consumed an MCP server before, nothing here is conceptually new. The novelty is that the “API surface” is your live game editor.

8.2 Prerequisites

1. Unreal Engine 5.8 installed.
2. Claude Code installed and authenticated. It’s the Anthropic agentic coding CLI; install it and sign in per the Claude Code docs (docs.claude.com). You run it from a terminal.
3. Node.js if you want to use the MCP Inspector for debugging (npx).

8.3 Setup, step by step

1) Enable the plugins. Edit → Plugins → search Unreal MCP → check Enabled. The Toolset Registry dependency enables automatically. Also enable AllToolsets — Unreal MCP ships no tools itself; the shipped editor toolsets (SceneTools, ActorTools, MaterialInstanceTools, ObjectTools) are provided by the AllToolsets plugin. Skip it and the server connects but the agent has nothing to call. Restart the editor when prompted.

2) Start the server. Edit → Editor Preferences → General → Model Context Protocol → turn on Auto Start Server. Now the server launches with the editor and binds to http://127.0.0.1:8000/mcp. (The same panel lets you change the port 8000 and path /mcp if something else owns that port.)

To start it on demand instead, leave auto-start off and run this in the editor console (backtick ` to open it):

ModelContextProtocol.StartServer

Confirm it’s up by checking the Output Log — the server logs its bind address/port on startup. A bind failure (port in use, missing dependency) shows up here too.

3) Generate the Claude Code config. From the editor console:

ModelContextProtocol.GenerateClientConfig ClaudeCode

This writes a .mcp.json to your project root. Supported client names are ClaudeCode, Cursor, VSCode, Gemini, Codex, or All. The JSON configs (Claude Code, Cursor, VS Code, Gemini) merge with existing entries, so re-running is safe. The generated file looks like:

{
  "mcpServers": {
    "unreal-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

That’s a standard Claude Code project-scoped MCP config — Claude Code reads .mcp.json from the directory you launch it in.

4) Launch Claude Code from the project root. Open a terminal, cd into the same folder where .mcp.json was written (your .uproject directory), and start claude. Launching from the wrong directory is the #1 reason the agent “can’t find” Unreal — the config is directory-scoped. If it still doesn’t connect, make sure the editor (and its server) started first, then restart Claude Code so it re-reads the config.

5) Confirm the connection. Ask Claude Code something that requires live editor context:

If it answers with your actual selection, the loop is closed: Claude Code → MCP over HTTP → editor → back. From here, try “What are a few things you can do in Unreal right now?” to see the available toolsets.

8.4 Optional: run Claude Code inside the editor (Terminal plugin)

You can keep everything in one window. Enable the Terminal plugin (Edit → Plugins → Terminal, restart). Then in Editor Preferences → General → Terminal, add Startup Commands in this order:

1. Set a capable terminal type (otherwise claude falls back to a degraded mode and may spew raw escape codes):
   • Windows cmd: set TERM=xterm-256color
   • macOS/Linux (bash/zsh): export TERM=xterm-256color
2. cd to the project root where .mcp.json lives (the embedded terminal often starts in the engine install dir, not your project, so this is required):
   • Windows: cd /d "<project root path>"
   • Unix: cd "<project root path>"
3. Launch the agent: claude

Now opening the Terminal panel drops you straight into Claude Code, already in the right directory, talking to the running editor.

8.5 What you can actually do with it

Realistic, useful prompts once connected — these map to the shipped toolsets:

• Scene assembly: “Spawn a 10×10 grid of the StarterContent rock mesh with random rotations across the floor.” (ActorTools/SceneTools)
• Lighting passes: “Add a warm directional light at sunset angle and a sky light, then list the lights in the scene.” Iterate by description instead of clicking.
• Material instances: “Create three material instances of M_Basic with red/green/blue base color and apply them to the selected meshes.” (MaterialInstanceTools)
• Inspection / cleanup: “List every actor tagged ‘Enemy’ and tell me which have no AIController set.”
• Automation: “Run the project’s automation tests and summarize failures.”
• Art-direction loops: with viewport-capture tooling, the agent can place something, look at the result, and adjust — the closed loop that makes this more than a fancy autocomplete.

The honest division of labor: agents are great at tedious, well-specified, repetitive editor work (bulk placement, renaming, wiring up boilerplate, test runs) and at scaffolding. They’re weak at taste, game feel, and architecture — the things that actually make a game good. Use it to remove busywork so you spend your time on design.

8.6 Tool Search and custom tools

By default the server runs in Tool Search mode: tools/list returns three meta-tools — list_toolsets, describe_toolset, call_tool — instead of dumping hundreds of schemas at once. The agent discovers tools on demand, keeping context small. You don’t need to manage this; just know that’s why the initial tool list looks tiny.

You can extend the server with your own tools, which is where your dev skills pay off. A toolset is a class grouping related tools:

• Python (easiest): a .py under any plugin’s Content/Python/ directory, a class decorated @unreal.uclass() deriving from unreal.ToolsetDefinition, with @staticmethod functions marked @toolset_registry.tool_call. Type hints and Google-style docstrings become the tool’s JSON Schema and description — so write them carefully, the agent reads them.
• C++: derive from UToolsetDefinition, mark the class UCLASS(BlueprintType, Hidden), and expose static UFUNCTION(meta = (AICallable)) methods. Reach for C++ when a tool needs engine functionality not exposed to Python or hits a hot path.

After authoring, run ModelContextProtocol.RefreshTools in the console to re-poll the registry (adding a brand-new C++ UFUNCTION needs a full editor restart; Live Coding won’t propagate new declarations). Claude Code users can scaffold a toolset with the create-toolset skill from the unreal-mcp Claude Code plugin.

8.7 Can the agent build the models too?

A natural question once the agent can place actors: can it create the geometry, not just arrange it? The honest answer has three tiers.

• Assembling existing meshes — yes, today. The shipped SceneTools / ActorTools spawn, place, instance, and transform meshes you already have: “scatter 25 motes,” “ring five beacons around the origin,” “Nanite-enable the selected meshes.” What the stock tools can’t do is author new geometry — the shipped toolsets contain no mesh-modelling tools.
• Procedural meshes — yes, via a custom toolset. UE ships Geometry Script, a Blueprint/Python API over a UDynamicMesh: you Append Box / Append Cylinder / Append Sphere, boolean and transform them, then bake the result into a new SM_ asset with Create New Static Mesh Asset from Mesh (the editor asset-creation node). Because you can author your own Python toolset (8.6), you can expose those functions as MCP tools and then ask Claude Code for parametric geometry — e.g. “make a faceted crystal beacon: a beveled cylinder with a cone cap, 1.5 m tall; bake it to SM_Beacon.” That is genuine agent-driven model creation (parametric, not hand-sculpted), and it fits WISP well: its “models” are mostly primitives — the Wisp is a glowing sphere, motes are small spheres, beacons are simple shapes.
• Free-form generative modelling — no, not from MCP. The Unreal MCP is a gateway to editor operations, not a generative-3D model. For an organic, novel mesh from a text prompt you’d run a separate text-to-3D service and import the result (FBX/glTF); the agent can then place, Nanite-enable, and material it.

8.8 Security — treat agent access like production credentials

This is not optional reading. The agent has real control over your editor and project.

• No auth, loopback only. The server binds to 127.0.0.1 with no authentication and rejects non-loopback origins. It is not safe to expose beyond your machine — don’t port-forward it or bind it to a public interface.
• Use a tool allowlist / agent profile. Decide which tools the agent may call unattended. “Read the scene” is safe; “delete asset” / “delete actor” is not. The cautionary tale that circulates in the community: an agent told to “clean up unused assets” cheerfully deletes the level file. Configure Claude Code’s permission prompts so destructive tools require explicit approval.
• Work on a branch under source control. Commit before you let an agent loose (see Part 10). If it makes a mess, git/Perforce revert is your undo. Never run an agent against an uncommitted, unbacked-up project.
• Review its changes like any PR. Agent edits to Blueprints/scene are still your responsibility.

8.9 Debugging the connection

• Output Log + raise verbosity: Log LogModelContextProtocol Verbose in the console.
• MCP Inspector — the official, agent-agnostic debugger. Launch npx @modelcontextprotocol/inspector, point it at http://127.0.0.1:8000/mcp over the Streamable HTTP transport, and it lists every advertised tool with its schema and a form to invoke it — bypassing any AI’s interpretation so you can tell whether a problem is the server or the agent.
• Console commands you’ll use: ModelContextProtocol.StartServer [port], .StopServer, .RefreshTools, .GenerateClientConfig <Client|All>.
• Known limits in 5.8: HTTP + Server-Sent Events only (no stdio/WebSocket), loopback only, no auth, experimental and changing, and new UFUNCTION tools need an editor restart.