DEV Community

GameDevToolLab
GameDevToolLab

Posted on

Using Unreal MCP in UE 5.8 from Codex: Setup, Toolsets, and Safe Editor Automation

#unrealengine #gamedev #ai #mcp

Introduction

Unreal Engine 5.8 adds Unreal MCP, an experimental plugin that exposes Unreal Editor operations to AI agents through the Model Context Protocol. Once Codex is connected, it can inspect or edit actors, configure lighting, create material instances, run automation tests, and invoke project-specific editor tools from natural language.

That does not mean you should hand a production project to Codex and hope it figures everything out.

In UE 5.8, Unreal MCP is still experimental. Epic Games notes that APIs and data formats may change. Its HTTP server has no authentication layer, and tool calls are executed serially on Unreal Engine's game thread. Without guardrails, an agent can edit the wrong level, save an asset to the wrong folder, duplicate an object after a timeout, or conflict with another connected client.

This guide builds the integration in stages: understand the architecture, connect Codex, verify reads, allow one sandboxed write, then add approval, recovery, source-control, and custom-tool rules.

Version note: This article is based on UE 5.8 and Codex documentation checked on July 21, 2026. It is an implementation and operations guide, not a repeated benchmark. Verify the plugin settings, Output Log, and actual schemas in your installed build before adoption.

Understand the three Unreal-side layers 

Codex CLI / Codex IDE extension
        │ MCP over Streamable HTTP
        ▼
http://127.0.0.1:8000/mcp
        │
        ▼
Unreal Editor
  ├─ Unreal MCP (ModelContextProtocol)
  │    └─ Server, connection, Tool Search
  ├─ Toolset Registry
  │    └─ Toolset discovery and schemas
  └─ AllToolsets / individual toolsets
       └─ Actor, scene, material, and other operations
Enter fullscreen mode Exit fullscreen mode

The Plugin Browser name is Unreal MCP; its identifier and console-command prefix are ModelContextProtocol.

Unreal MCP mainly provides the server and protocol endpoint. The Toolset Registry discovers executable operations and generates schemas. AllToolsets enables the toolsets bundled with UE 5.8.

Enabled state Meaning
Unreal MCP only The server exists, but expected editor tools may be absent.
Toolset Registry Unreal can discover toolsets; it is enabled as a dependency.
AllToolsets Bundled UE 5.8 toolsets are enabled together.
Selected toolsets only Smaller exposure, but you manage features and dependencies.

Use AllToolsets for initial connectivity testing. For regular work, disable unnecessary toolsets and narrow permissions on both Unreal and Codex.

Unreal MCP can expose actor editing, lighting, material-instance creation, Slate inspection, automation tests, and custom project tools. It is not a UI macro. Codex can call only tools published by the server, and vague instructions do not reliably identify the correct asset, level, coordinate space, save location, or overwrite policy.

UE 5.8's bundled implementation focuses on MCP Tools rather than Resources or Prompts. A connected server showing no Resources is not necessarily broken. Tool calls also run serially on the game thread, so do not let multiple Codex sessions or MCP clients issue overlapping writes to one editor.

Prepare a disposable sandbox

Do not begin in a production map. Use:

  1. a UE 5.8 test project or production-project copy;
  2. a dedicated source-control branch;
  3. a level such as MCP_Sandbox;
  4. a folder such as /Game/MCPTest;
  5. Codex CLI or the Codex IDE extension;
  6. a commit or checkpoint before the first write.

Keep the level simple. A floor, one light, and one static mesh are enough. Avoid World Partition, active Sequencer work, or anything that makes diffs harder to understand.

Before expanding the scope, prove that Codex connects to the intended editor, reads the selected actor accurately, and discovers tool schemas. It must also limit writes to the requested level and folder, re-read saved results, and stop on unexpected state. Check for actors left in another level, duplicate assets, extra components, and unsaved packages.

Install Codex

Skip this section if Codex CLI is already available.

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Enter fullscreen mode Exit fullscreen mode

macOS or Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

Node.js and npm:

npm install -g @openai/codex
Enter fullscreen mode Exit fullscreen mode

The first two are official installation paths but execute a remote script directly. If pipe-to-shell installation is prohibited, inspect the script first, use npm or Homebrew, install an official GitHub release, or follow your internal distribution process.

Configure Unreal Editor

Open Edit > Plugins, enable Unreal MCP, and restart when prompted. The Toolset Registry dependency should be enabled automatically. Then enable AllToolsets and restart again if required.

Open Edit > Editor Preferences > General > Model Context Protocol. The UE 5.8 documentation lists these defaults:

Setting Default
Auto Start Server false
Server Port Number 8000
Server URL Path /mcp
Enable Tool Search true

After an engine update, treat the values shown by your editor and Output Log as authoritative.

Keep Auto Start disabled during early testing and start the server manually:

ModelContextProtocol.StartServer
Enter fullscreen mode Exit fullscreen mode

To specify a port:

ModelContextProtocol.StartServer 8000
Enter fullscreen mode Exit fullscreen mode

The default endpoint is:

http://127.0.0.1:8000/mcp
Enter fullscreen mode Exit fullscreen mode

Search Output Log for LogModelContextProtocol and confirm the bind address, port, and path. Stop the server when finished:

ModelContextProtocol.StopServer
Enter fullscreen mode Exit fullscreen mode

The server has no authentication layer, so leaving it running indefinitely is a poor default.

Generate the Codex configuration

Run this in the Unreal Editor console:

ModelContextProtocol.GenerateClientConfig Codex
Enter fullscreen mode Exit fullscreen mode

Codex uses ~/.codex/config.toml for user-level settings and can read .codex/config.toml from a trusted project. Check Output Log for the generated destination.

The Codex TOML generation step is effectively write-once: the generator does not overwrite an existing TOML. The file itself remains editable. If other MCP servers are already configured, merge the Unreal entry manually.

UE 5.8's Unreal MCP uses HTTP and Server-Sent Events, not stdio or WebSocket transport. Register a Streamable HTTP url:

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8000/mcp"
required = false
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"
Enter fullscreen mode Exit fullscreen mode

required = false prevents an unavailable editor from blocking unrelated Codex work. The default tool timeout is 60 seconds; 120 is only an initial adjustment for operations that consistently exceed it. After a timeout, inspect the editor before retrying because an operation may have completed or partially changed state.

Keep default_tools_approval_mode = "prompt" while learning the exposed schemas. The writes mode allows tools marked read-only and prompts for others, but Unreal's default Tool Search funnels inner operations through call_tool. Codex may not classify each inner operation independently, so writes is not automatically a fine-grained safety boundary.

Important: Codex's filesystem sandbox and MCP operations inside Unreal Editor are different boundaries. Limiting workspace writes does not necessarily stop an approved MCP tool from changing a level or asset. Combine approval, limited toolsets, sandbox levels, dedicated content folders, and source control.

Start Codex from the project root 

cd C:\Work\Unreal\MCPExample
codex
Enter fullscreen mode Exit fullscreen mode

In the Codex TUI, inspect servers active in the current session with:

/mcp
Enter fullscreen mode Exit fullscreen mode

From a terminal, list configured servers with:

codex mcp list
Enter fullscreen mode Exit fullscreen mode

codex mcp list confirms configuration registration; it does not prove the Unreal endpoint is reachable. /mcp shows the current-session state. End-to-end verification requires a response from list_toolsets or describe_toolset, or a successful MCP Inspector connection.

Project-local .codex/config.toml is loaded only for a trusted project. If a user-level entry works but the project entry does not, check the launch directory and trust state.

Why only three tools may be visible

With Enable Tool Search enabled, Unreal MCP initially exposes three meta-tools instead of hundreds of schemas:

Tool Purpose
list_toolsets Lists available toolsets.
describe_toolset Returns schemas inside a toolset.
call_tool Invokes an inner tool by toolset, name, and arguments.

These are the UE 5.8 documented names; confirm them with /mcp or MCP Inspector after an update.

This design affects allowlists. Codex's enabled_tools filters names exposed by the server. When Tool Search collapses operations behind call_tool, allowing that outer tool does not create a separate permission rule for every inner tool.

For schema discovery only:

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8000/mcp"
enabled_tools = ["list_toolsets", "describe_toolset"]
default_tools_approval_mode = "prompt"
Enter fullscreen mode Exit fullscreen mode

Add execution only when ready:

enabled_tools = ["list_toolsets", "describe_toolset", "call_tool"]
Enter fullscreen mode Exit fullscreen mode

Keep approval enabled and reduce active Unreal toolsets. Disabling Tool Search exposes individual tools and permits a more precise Codex allowlist, but increases the initial schema payload and ongoing maintenance for renamed schemas, stale allowlists, and accidental over-permission.

Verify reads before writes

First, discover schemas without invoking an inner operation:

Check the Unreal MCP connection without changing any editor state.

1. Use list_toolsets to list available toolsets.
2. Identify candidates for actors, scenes, and material instances.
3. Use describe_toolset and separate read operations from writes.
4. Do not invoke call_tool. Report only the tools and arguments you would use next.
Enter fullscreen mode Exit fullscreen mode

After review, add call_tool to enabled_tools, restart Codex, select a cube in MCP_Sandbox, and request a read:

Read the actor currently selected in Unreal Editor.
Report Actor Label, Class, Object Path, world Transform, and owning Level.
Do not modify, save, or change the selection.
Inspect the schema first, then perform only the read operation.
Enter fullscreen mode Exit fullscreen mode

Compare the response with the editor. Move the cube and read again to detect stale data. A successful check identifies the intended editor state, distinguishes Actor Label from Object Path, reports the correct world transform, causes no side effects, and names the toolset and tool used.

Do not proceed to writes until this is reliable.

Make the first write small and observable

Add one point light to the sandbox rather than generating a complex Blueprint:

Use Unreal MCP to edit only the open MCP_Sandbox level.

Goal:
- Add one Point Light named MCP_TestPointLight.
- Location: X=0, Y=0, Z=300.
- Intensity: 5000.

Rules:
- Show the toolset, tool, arguments, and target before execution.
- Wait for approval before call_tool.
- If the actor already exists, stop instead of duplicating it.
- Do not modify another level, asset, or Project Setting.
- Re-read the result before saving.
- Never use Save All; save only the target level.
- Re-read the Object Path and values after saving.
- Stop if any unexpected actor or component appears.
Enter fullscreen mode Exit fullscreen mode

The completion criterion is not a confident chat message. Use this sequence: plan and approve → execute one operation → re-read → save only the target package → re-read again → inspect the editor and source-control diff.

Do not split writes across multiple Codex subagents. A second agent can invalidate the assumptions of an already approved plan.

Fix material and test inputs explicitly

For a Material Instance, define the parent, destination, asset name, allowed parameters, overwrite behavior, and verification:

Create one Material Instance through Unreal MCP.

Parent: /Game/MCPTest/Materials/M_Master
Output: /Game/MCPTest/Materials/Instances/MI_MCP_Red
BaseColor: R=1, G=0, B=0, A=1
Roughness: 0.6

Stop if the asset already exists, the output folder is missing, or either parameter is absent.
Do not modify the parent or anything outside /Game/MCPTest.
Inspect the tool schema first. After creation and after saving, re-read the parent,
parameter values, and Object Path. Save only the new asset.
Enter fullscreen mode Exit fullscreen mode

Never leave overwrite policy to the tone of natural language. Choose stop, another name, or explicit approval.

Automation Tests are often a lower-risk starting point, although tests can still load maps or create assets:

Run only the Automation Test Project.MCP.Smoke.
Confirm an exact name match first.
Do not modify code, Blueprints, or config, and do not auto-fix failures.
Report the result, failed test names, important log lines, and duration.
Enter fullscreen mode Exit fullscreen mode

Keep observation and modification in separate turns.

Put persistent rules in AGENTS.md

Store repeated project rules in AGENTS.md at the project root:

# Unreal MCP Working Agreement

## Scope
- Writes are limited to `/Game/MCPTest` and `MCP_Sandbox`.
- Do not modify other levels, assets, plugins, or Project Settings.

## Workflow
- Inspect schemas before execution.
- Show toolset, tool, arguments, and targets before every write.
- Execute `call_tool` one at a time; never parallelize writes.
- After a timeout, re-read state instead of resending the write.
- Check for duplicates before creation.
- Re-read after creation and after saving.
- Never use `Save All`.

## Stop conditions
- The target is outside the allowed scope.
- An existing asset has no overwrite policy.
- The schema changed, the editor is unresponsive, or an unexpected diff appears.
- The target editor instance cannot be identified unambiguously.
Enter fullscreen mode Exit fullscreen mode

AGENTS.md is not an authorization system. Continue using MCP approval, limited toolsets, source control, and the sandbox. Start a new project-root session after changing it when you need the new instructions loaded.

Troubleshooting and MCP Inspector

If unreal-mcp does not appear or respond, check in this order:

  1. Start the server and confirm its endpoint in Output Log.
  2. Compare that endpoint with .codex/config.toml.
  3. Confirm the project root and trust state.
  4. Restart Codex; use codex mcp list for registration.
  5. Use /mcp for current-session state.
  6. Call list_toolsets or connect with MCP Inspector for live traffic.

Only seeing the three meta-tools is normal with Tool Search enabled. If list_toolsets is empty, confirm Unreal MCP, Toolset Registry, and AllToolsets, then restart the editor.

After adding or changing a toolset, run:

ModelContextProtocol.RefreshTools
Enter fullscreen mode Exit fullscreen mode

Reconnect Codex afterward. A new C++ UFUNCTION declaration may require an editor restart rather than Live Coding alone.

If the port changes, update both Unreal and Codex:

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8123/mcp"
Enter fullscreen mode Exit fullscreen mode

A timeout does not prove nothing happened. Do not resend the same write. Check editor responsiveness, Output Log, the target object, and source-control diff, then plan only the remaining work.

To separate Codex issues from server issues, run MCP Inspector:

npx @modelcontextprotocol/inspector
Enter fullscreen mode Exit fullscreen mode

The first run may download a package and require Node.js, npm, network access, and execution approval. Choose Streamable HTTP and connect to:

http://127.0.0.1:8000/mcp
Enter fullscreen mode Exit fullscreen mode

Inspector shows exposed tools, schemas, argument forms, and protocol errors. It can also execute tools, so prefer discovery and reads while troubleshooting. If Inspector fails too, investigate Unreal. If Inspector works but Codex fails, focus on Codex configuration, approval, or prompt interpretation.

For more Unreal-side detail, temporarily use:

Log LogModelContextProtocol Verbose
Enter fullscreen mode Exit fullscreen mode

Restore normal verbosity afterward and treat project logs as potentially sensitive.

Localhost is not authentication

Unreal MCP binds to loopback by default and rejects non-loopback origins, but it has no authentication layer. Do not casually bind it to 0.0.0.0, forward the port for remote use, expose it to a LAN without authentication, let several people control one editor, or use it as a production-build endpoint.

A VPN, office LAN, or localhost proxy is not a substitute for authentication. This article assumes Codex and Unreal Editor run on the same developer machine.

Repeated work belongs in narrow custom tools

Generic actor and scene tools are useful for exploration. Repeated workflows are safer as project-specific operations with fewer valid failure modes:

CreateValidatedEnemyActor(
  enemyDefinition,
  targetLevel,
  transform,
  outputFolder,
  overwritePolicy,
  dryRun
)
Enter fullscreen mode Exit fullscreen mode

The implementation should validate scope and duplicates, return planned changes from dryRun, and verify source-control checkout or locks. It should group undoable editor changes in a transaction, run post-validation, track dirty packages, save only intended packages, and return structured state before and after saving.

MCP does not automatically wrap a tool call in an Unreal transaction. C++ FScopedTransaction and Python unreal.ScopedEditorTransaction help only with operations the editor can undo. Imports, saved packages, external files, and source-control state may need explicit compensation and checkpoints.

A practical flow is:

dryRun
→ validate input, permissions, and source control
→ execute undoable work in a transaction
→ post-validate
→ save target packages only
→ re-read state
→ return a structured result
Enter fullscreen mode Exit fullscreen mode

On failure, report separately what was undone, cleaned up, and left for a human. In UE 5.8, custom toolsets can derive from unreal.ToolsetDefinition in Python or UToolsetDefinition in C++. After adding one, run ModelContextProtocol.RefreshTools and reconnect Codex.

The value of a custom tool is not merely convenience. Moving natural-language constraints into implementation reduces the choices through which the AI can fail.

PCG requires references and a reviewed plan

Epic also documents using Unreal MCP and LLMs with PCG graphs. PCG is a poor first connectivity test because a graph can be technically valid while its data flow is wrong or needlessly complex.

Some official examples assume Claude Code-specific supporting material. With Codex, place equivalent instructions in a Codex Skill, AGENTS.md, or a project reference document and require them to be read before planning. Have a human choose the reference graph and assets, ask Codex to explain the intended data flow, review the plan, and generate small sections in stages. A working MCP connection does not imply correct domain design.

Measure safety before adoption

Repeat the same tasks and record first-pass success, human intervention, out-of-scope changes, duplicate creation, and persistence after reload. Also track tool-call count, duration, recovery time, and schema stability after restarts or plugin updates.

Prioritize zero out-of-scope changes, understandable failures, and reliable recovery over a small speed improvement. Blueprints, materials, PCG graphs, and Sequencer content also require in-editor validation; a text diff alone rarely proves a visual asset is correct.

Conclusion

A safe UE 5.8 Unreal MCP workflow from Codex is:

  1. Enable Unreal MCP and AllToolsets.
  2. Start the local server with ModelContextProtocol.StartServer.
  3. Generate the entry with ModelContextProtocol.GenerateClientConfig Codex.
  4. Launch Codex from the project or workspace root.
  5. Verify /mcp, list_toolsets, and describe_toolset before writing.
  6. Use call_tool with approval and make one sandboxed change at a time.
  7. Re-read after saving and inspect source-control diffs.
  8. Move repeated work into narrow, validated custom tools.

Remember the division of responsibilities: Unreal MCP provides the server, Toolset Registry provides discovery and schemas, and AllToolsets provides bundled editor operations. Tool Search also funnels operations through call_tool, so an allowlist around that outer tool is not automatically a fine-grained permission model for every inner operation.

Treat Unreal MCP as an editor-extension entry point, not natural-language control for everything. Start with reads, expand to bounded sandbox writes, and only then expose reviewed project-specific tools.

References

Verified on July 21, 2026:

Top comments (0)