Unreal MCP README

✨ AI Game Developer — Unreal MCP

                                

Unreal MCP is an AI-powered game development assistant for the Unreal Editor. Connect Claude, Cursor, Copilot, or any MCP-aware agent to Unreal Engine and let it inspect and drive your project — spawn actors, edit levels, author Blueprints, manage assets, edit and compile C++, capture screenshots, and more.

Unreal-MCP is the Unreal Engine counterpart of Unity-MCP and Godot-MCP: a C++ editor plugin that exposes Unreal Editor operations as AI Tools and connects them to an MCP server through the same hosted cloud backend (ai-game.dev) that powers Unity-MCP and Godot-MCP — or your own self-hosted server. The local server is the shared, engine-agnostic GameDev-MCP-Server (binary gamedev-mcp-server) — one server consumed by Unity-MCP, Godot-MCP, and Unreal-MCP; no server source lives in this repo.

Unlike Unity and Godot (C# engines that host the .NET McpPlugin in-process), Unreal's editor is C++ — so the .NET MCP host runs as an auto-managed sidecar process (unreal-mcp-bridge) that the plugin spawns and talks to over a localhost IPC channel. The full design lives in docs/ARCHITECTURE.md (see the §0 system-overview diagram).

Status: beta. The plugin, the .NET sidecar, the unreal-mcp-cli, the AI Game Developer editor UI, and 25 built-in tools across 5 families (plus 3 system tools) — the editor data layer is one query language, RQL have shipped and are exercised by CI. The unreal-mcp-cli is published on npm — install the plugin with it (Option B below); the Fab / Epic Marketplace listing for the precompiled plugin is coming soon (Option A). Pixel-capture (screenshot) tools need a GPU-backed editor; everything else runs headless.

💬 Join our Discord Server — Ask questions, showcase your work, and connect with other developers!

• ✔️ AI agents — Use the best agents from Anthropic, OpenAI, Google, or any other provider with no vendor lock-in
• ✔️ RQL data layer — query and change actors, components, assets, levels and editor state with one language (rql-query / rql-mutate / rql-schema)
• ✔️ 25 built-in Tools — MCP Tools across 5 families for operating the Unreal Editor
• ✔️ Blueprint authoring — Create, edit, and compile Blueprints with a structured error/warning feedback loop the AI can act on
• ✔️ C++ edit & compile — Read, scaffold, and edit project C++, then compile (Live Coding or UBT) with a structured error report
• ✔️ Visual feedback — Capture viewport, game-view, camera, and isolated-actor screenshots the LLM can inspect directly
• ✔️ Custom Tools, Prompts & Resources — Register your own AI Tools, prompt templates, and resources from any UE plugin with no fork — one public, modular-feature contract (Customize Tools, Prompts & Resources)
• ✔️ Cloud or self-hosted — Connect to ai-game.dev out of the box, or point at your own GameDev-MCP-Server
• ✔️ Per-tool enable / disable — Flip any tool on or off from the MCP Tools window; the toggle is enforced at the execution boundary, not just hidden

Table of contents

First-party extensions now use independent component releases and an online CLI index. See the monorepo test/release guide; it supersedes legacy per-repository release instructions below.

• Requirements
• Install
• Updating the plugin
• First run
• Tools — all 6 families, 26 tools (+ 3 system tools)
• Per-tool enable / disable
• unreal-mcp-cli
• Customize Tools, Prompts & Resources
• Runtime usage (in-game)
  • Editor-only — exclude Unreal-MCP from packaged games
• Configuration & environment variables
• Troubleshooting
• How Unreal MCP Architecture Works
• Repo layout
• Links
• License

Requirements

• Unreal Engine 5.5+ (developed and CI-tested against 5.7, and verified to build & run on 5.8). The plugin deliberately ships no EngineVersion pin — UE treats that field as an exact-build match, not a floor, and would refuse to load on newer engines.
• .NET 9 SDK to build the bridge sidecar from source. (End users of a packaged release do NOT need it — the self-contained sidecar is bundled inside the plugin and auto-spawned, ARCHITECTURE §6. The local MCP server is downloaded as a prebuilt GameDev-MCP-Server release binary, never built here.)
• Node.js ^20.19.0 || >=22.12.0 for the optional unreal-mcp-cli.
• A C++ Unreal project (the plugin builds an Editor module, so the host project must be able to compile C++).

Install

There are three ways to install the plugin, in order of preference. Fab / Epic Marketplace is the recommended channel for end users — it ships precompiled, per-engine binaries and the Epic Games Launcher keeps them up to date automatically, so there is zero compile and zero stale-build risk. Source / unreal-mcp-cli installs remain the current path for developers and early adopters until the Fab listing goes live.

Option A — Fab / Epic Marketplace (recommended; coming soon)

Status: not yet live. The Fab listing is operator-gated and tracked separately; until it publishes, use Option B or C below. The framing here is what the end-user flow will be.

1. Install Unreal-MCP from Fab (the Epic Marketplace successor) into your engine via the Epic Games Launcher.
2. Enable the plugin for your project from Edit → Plugins.
3. Open the project — UE loads the precompiled plugin (no C++ build on your machine). On boot the Output Log prints [Unreal-MCP] plugin loaded.

Because Fab ships precompiled binaries and the Epic Launcher updates them in place, you never compile the plugin and never have to clear a stale build cache — the most robust path for non-developers.

Option B — unreal-mcp-cli (current / advanced)

The CLI is the recommended path today, until the Fab listing is live. Install it from npm — no repo clone, no build step. By default install-plugin / update use a local UnrealMCP/ checkout when one is present; otherwise they download the dedicated unreal-mcp-plugin-source-<version>.zip source asset from the public GitHub Release that matches the CLI version. That source asset keeps the distributed descriptor semantics (no EngineVersion pin) and carries the signed bridge payload under Source/ThirdParty/UnrealMcpBridge/<rid>/; the installer materializes it into Binaries/ThirdParty/... for first-open convenience. --plugin-source <dir> remains the offline / CI / dev override. The CLI copies (or, for dev, junctions) the plugin into your project and, on update, automatically clears the stale UE build cache so you always get a clean recompile of the new code (see Updating the plugin). On desktop platforms (Win64 / Mac / Linux), unreal-mcp-cli open also runs a pre-launch build when the project/plugin state still needs native editor binaries, then auto-dismisses the known Unreal blocker dialogs (Missing ... Modules, UnrealMCP is Incompatible) if they still appear during startup. Linux dialog automation is X11-only; Wayland is detected and warned as unsupported.

# 1. Install unreal-mcp-cli (or use `npx unreal-mcp-cli@latest <command>` for a one-off, no install)
npm install -g unreal-mcp-cli

# 2. Install the UnrealMCP plugin into your project
unreal-mcp-cli install-plugin ./YourProject

# 3. Authorize against the cloud server (ai-game.dev)
unreal-mcp-cli login ./YourProject

# 4. Open the Unreal Editor for the project (wires the MCP connection env vars)
unreal-mcp-cli open ./YourProject

See cli/README.md for the full 18-command reference.

Option C — manual

1. Copy UnrealMCP/ into <YourProject>/Plugins/UnrealMCP/ (or create a directory junction / symlink to it for live development).
2. Open the project; UE compiles the UnrealMcpEditor module on first launch.
3. On editor boot the Output Log prints [Unreal-MCP] plugin loaded — that confirms the plugin and its game-thread dispatcher started.

The sidecar binary (unreal-mcp-bridge) is bundled inside the plugin in a packaged release: a prebuilt, self-contained binary for your platform ships under UnrealMCP/Binaries/ThirdParty/UnrealMcpBridge/<rid>/ and the editor auto-spawns it on startup with zero user action — no .NET install, no env var, no manual launch (ARCHITECTURE §6). The first Cloud OAuth device-code browser approval is the only remaining human step; after that, reconnect on later launches is zero-click (the cloud token is cached in Saved/Config/UnrealMcp/).

When you copy the repo source checkout directly (Option C/manual or a live dev junction), the bundled binary is not present — the plugin then resolves the sidecar from the UNREAL_MCP_BRIDGE_PATH environment variable instead: point that at a locally built sidecar, or run unreal-mcp-cli bootstrap-local to build the bridge from source into <YourProject>/Intermediate/UnrealMCP/ and set the var to the result. With neither a bundled binary nor the env var resolved, the plugin's TCP listener still starts but logs [Unreal-MCP] no sidecar binary resolved for rid <rid> … and spawns nothing.

Updating the plugin

Updating in place must always leave you running the new code. The risk is UE's incremental compiler: if the plugin source changes (new .cpp files, a new module) but the old UnrealMCP/Intermediate/ build cache survives, UE can do a partial recompile against a stale module file-list and silently leave you on old/partial code. Each channel handles this differently:

• Fab / Epic Marketplace → automatic. The Epic Games Launcher replaces the precompiled binaries in place; nothing to compile, no cache to clear. This is why Fab is the recommended channel.

• unreal-mcp-cli update → automatic clean rebuild. update re-copies the plugin source and, by default, deletes the installed plugin's stale Intermediate/ and the C++ Binaries/ so UE performs a clean compile on the next editor launch — no manual steps. The bundled sidecar bridge under Binaries/ThirdParty/UnrealMcpBridge/<rid>/ is kept intact: release-source installs refresh it from Source/ThirdParty/..., while repo/dev installs preserve the previously bundled copy when needed. Dev junction installs are never cleaned (that would wipe your live source tree's outputs). Pass --no-clean to opt out of the cache wipe.

  bashCopy

  node bin/unreal-mcp-cli.js update <YourProject>            # default: clean rebuild on version change
  node bin/unreal-mcp-cli.js update <YourProject> --force    # re-copy even when versions match
  node bin/unreal-mcp-cli.js update <YourProject> --no-clean # keep the existing build cache
  

• Manual copy → clear the cache yourself. If you overwrite <YourProject>/Plugins/UnrealMCP/ by hand, close the editor first, delete <YourProject>/Plugins/UnrealMCP/Intermediate/ and the C++ Binaries/ (keep Binaries/ThirdParty/ if a bundled bridge is present), then relaunch so UE recompiles cleanly.

First run

1. Open the AI Game Developer main window from the editor's Tools menu (the tab is registered under the Tools menu category).
2. Choose a connection mode:
   • Cloud (default) — connects to ai-game.dev. Click Authorize to start the OAuth device-code flow: the window shows a verification URL and a short user code; open the URL, enter the code, approve, and the editor finishes authorizing. Use Revoke to clear the stored cloud token.
   • Custom — connects to a local gamedev-mcp-server you run (or any compatible server). Enter the server URL and point your AI client at it. (The plugin does not start the local server for you — run unreal-mcp-cli or your own process; see Troubleshooting.)
3. The Connection section shows a status dot, a status label, and a Connect / Disconnect / Stop button; the bridge status reads Running (restarts: N) or Stopped. Use them to confirm the sidecar is live.
4. Point your AI client (Claude Code, Cursor, the AI Game Developer app, …) at the server. The AI agents section lists the agents currently connected; to write an MCP client config use unreal-mcp-cli setup-mcp.

Connection settings persist to <Project>/Saved/Config/UnrealMcp/ai-game-developer-config.json (Saved/ is gitignored by every UE template, so tokens never land in VCS by default).

Pinned MCP client URL. unreal-mcp-cli setup-mcp <agent> writes an MCP client config that points at the project-pinned cloud URL <base>/mcp/p/<pin>, so the agent routes to this project's editor even when your account drives several. Pass --no-pin to write the bare <base>/mcp URL instead. The pin is a routing path segment only — the OAuth resource stays <base>/mcp.

Project key. When this machine is signed in (unreal-mcp-cli login, or the editor's Sign in), a Cloud config also carries Authorization: Bearer agd_pk_… — a non-expiring, revocable key bound to this project's pin — for every agent, so no agent needs its own OAuth. The key is cached in ~/.ai-game-dev/project-keys.json and reused. Pass --oauth for a URL-only config (the agent signs in itself), or --regenerate-key to mint a new key and revoke the old one (the editor's AI agent panel has a Regenerate key button). Not signed in, or the server cannot mint a key ⇒ the URL-only config.

That's it. Ask your AI "Spawn three cubes in a row and a point light above them" and watch it happen. ✨

Tools

Unreal-MCP ships 26 built-in ("core") tools across 6 families that your AI can call, plus 3 system tools it cannot (see below). Tool ids are kebab-case (rql-query, blueprint-compile), matching the Unity/Godot naming convention. Extensions can add more (see Customize Tools, Prompts & Resources).

This list is generated from the STANDARD-surface registration sources (UnrealMCP/Source/UnrealMcpEditor/Private/Tools/UnrealMcp*Tools.cpp, excluding UnrealMcpSkillTools.cpp — its tool is a system tool, listed separately below — plus UnrealMCP/Source/UnrealMcpRql/Private/UnrealMcpRqlTools.cpp). Counts: rql 3, blueprint 11, console 1, python 1, source 6, screenshot 4 = 26.

Per-tool enable / disable

Every tool can be individually enabled or disabled from the MCP Tools window — the standalone MCP Tools tab (registered under the editor's Tools menu). The window shows each tool's title, family, and description, plus an "N / M tools enabled" summary line. Disabling a tool:

• removes it from the served manifest entirely — it never appears in the MCP tools/list; and
• is enforced at the execution boundary too — even if a stale tools/list is dispatched, a disabled tool is rejected at Execute() rather than run.

Two filters combine to decide whether a tool is served (see ARCHITECTURE §7/§8):

• a whitelist (enabledTools, overridable via UNREAL_MCP_TOOLS) — when non-empty, only listed tools are served; empty means "no filter"; and
• a blocklist (disabledTools) — the per-tool toggles you flip in the UI.

A tool is served iff it passes the whitelist and is not in the blocklist. Both sets are persisted across editor sessions and survive an extension hot-reload (a re-registered tool inherits the retained toggle, so a rebuild can never silently re-enable a tool you disabled).

All connection settings live in the single AI Game Developer main window's Connection section (there is no separate Settings tab or Project-Settings page — Unity-MCP parity). The MCP Prompts and MCP Resources windows are wired but ship empty in this release — each renders a subdued empty-state message (the "N / M enabled" summary is unique to the Tools window).

unreal-mcp-cli

A cross-platform Node CLI (unreal-mcp-cli) that scaffolds projects, installs the plugin, configures connection settings, drives the local server, and invokes tools over HTTP. It is a port of unity-mcp-cli / godot-cli. Full reference: cli/README.md.

Published on npm — install with npm install -g unreal-mcp-cli, or run a one-off with npx unreal-mcp-cli@latest <command>.

The full 18-command surface:

Customize Tools, Prompts & Resources

This is the headline extensibility feature. Anyone can register their own AI Tools, prompts, and resources — from any third-party UE plugin — and have them appear in the MCP manifest alongside the built-ins. No fork, no link-time coupling, no load-order assumptions. Your contributions are discovered automatically on editor boot (and on late-load / hot-unload), merged in deterministic order, and exposed to every connected AI agent.

All three kinds use the same small, public, modular-feature-based contract — a provider interface plus a fluent registry builder, both living in the UnrealMcpRuntime module (re-exported by UnrealMcpEditor, so the same contract serves editor and runtime extensions). The full author guide is docs/EXTENSIONS.md.

RQL modules (editor data)

An extension for an engine feature contributes an RQL module rather than tools: implement IUnrealMcpRqlModule and register sources (e.g. the project's Niagara systems), operations (the UFUNCTIONs of an operations class, called with call), computed members and a guide for the unreal-rql skill. Agents then reach the feature through rql-query / rql-mutate like the rest of the editor (docs/rql.md, docs/EXTENSIONS.md). The first-party extensions in extensions/ and the template samples/UnrealAITemplate/ are RQL modules.

Tools

For what is not editor data, implement IUnrealMcpToolProvider and declare your tools with the fluent FUnrealMcpToolRegistry builder:

#include "IUnrealMcpToolProvider.h"
#include "UnrealMcpToolRegistry.h"

class FMyExtensionProvider : public IUnrealMcpToolProvider
{
public:
    virtual FString GetExtensionId() const override      { return TEXT("com.foo.my-extension"); }
    virtual FText   GetDisplayName() const override      { return NSLOCTEXT("Foo", "Name", "My Extension"); }
    virtual FString GetExtensionVersion() const override { return TEXT("1.0.0"); }

    virtual void RegisterTools(FUnrealMcpToolRegistry& Registry) override
    {
        Registry.Tool(TEXT("hello-extension"))
            .Title(TEXT("Hello Extension"))
            .Description(TEXT("Returns a friendly greeting."))
            .ParamString(TEXT("name"), TEXT("Who to greet. Defaults to 'world'."))
            .ReadOnlyHint(true)
            .IdempotentHint(true)
            .Handle([](const FUnrealMcpToolCall& Call) -> FUnrealMcpToolResult
            {
                const FString Name = Call.Has(TEXT("name")) ? Call.GetString(TEXT("name")) : TEXT("world");
                return FUnrealMcpToolResult::Success(FString::Printf(TEXT("Hello, %s!"), *Name));
            });
    }
};

Then register the provider as a modular feature in your module's StartupModule (and unregister in ShutdownModule):

// In StartupModule:
IModularFeatures::Get().RegisterModularFeature(
    IUnrealMcpToolProvider::GetModularFeatureName(), Provider.Get());

Prompts

Prompts are reusable, parameterized prompt templates the agent fetches via prompts/get. Implement IUnrealMcpPromptProvider and declare prompts with FUnrealMcpPromptRegistry. Prompt arguments reuse the same Param* helpers as the tool builder; a handler returns role-tagged messages:

#include "IUnrealMcpPromptProvider.h"
#include "UnrealMcpPromptRegistry.h"

class FMyPromptProvider : public IUnrealMcpPromptProvider
{
public:
    virtual FString GetExtensionId() const override      { return TEXT("com.foo.my-extension"); }
    virtual FText   GetDisplayName() const override      { return NSLOCTEXT("Foo", "Name", "My Extension"); }
    virtual FString GetExtensionVersion() const override { return TEXT("1.0.0"); }

    virtual void RegisterPrompts(FUnrealMcpPromptRegistry& Registry) override
    {
        Registry.Prompt(TEXT("level-design-brief"))
            .Title(TEXT("Level Design Brief"))
            .Description(TEXT("Generate a level design brief from a single 'theme' argument."))
            .Role(EUnrealMcpPromptRole::User)
            .ParamString(TEXT("theme"), TEXT("The level theme (e.g. 'haunted forest')."),
                         EUnrealMcpParamRequirement::Required)
            .Handle([](const FUnrealMcpToolCall& Call) -> FUnrealMcpPromptResult
            {
                const FString Theme = Call.GetString(TEXT("theme"));
                if (Theme.IsEmpty())
                    return FUnrealMcpPromptResult::Error(TEXT("theme is required."));
                const FString Text = FString::Printf(
                    TEXT("Draft a level design brief for a \"%s\"-themed level."), *Theme);
                return FUnrealMcpPromptResult::Success(Text, EUnrealMcpPromptRole::User);
            });
    }
};

// Register under the prompt modular-feature name (and unregister in ShutdownModule):
IModularFeatures::Get().RegisterModularFeature(
    IUnrealMcpPromptProvider::GetModularFeatureName(), PromptProvider.Get());

level-design-brief is the shipped core prompt — see UnrealMCP/Source/UnrealMcpRuntime/Private/Prompts/UnrealMcpCorePrompts.cpp.

Resources

Resources are addressable, readable content the agent fetches via resources/read — the resource's URI is its identity. Implement IUnrealMcpResourceProvider and declare resources with FUnrealMcpResourceRegistry. A read returns content blocks — text XOR a base64 blob + a mime type:

#include "IUnrealMcpResourceProvider.h"
#include "UnrealMcpResourceRegistry.h"

virtual void RegisterResources(FUnrealMcpResourceRegistry& Registry) override
{
    Registry.Resource(TEXT("unreal://project/levels"))                  // JSON (text) resource
        .Name(TEXT("Project Levels"))
        .Description(TEXT("A JSON snapshot of the active world and its levels."))
        .MimeType(TEXT("application/json"))
        .Read([](const FString& Uri) -> FUnrealMcpResourceResult
        {
            return FUnrealMcpResourceResult::Text(Uri, BuildLevelsJson(), TEXT("application/json"));
        });

    Registry.Resource(TEXT("unreal://project/icon"))                    // binary (blob) resource
        .Name(TEXT("Project Icon"))
        .Description(TEXT("A small PNG, returned as a base64 blob."))
        .MimeType(TEXT("image/png"))
        .Read([](const FString& Uri) -> FUnrealMcpResourceResult
        {
            const FString Base64 = FBase64::Encode(IconBytes, sizeof(IconBytes));
            return FUnrealMcpResourceResult::Blob(Uri, Base64, TEXT("image/png"));
        });
}

// Register under the resource modular-feature name (and unregister in ShutdownModule):
IModularFeatures::Get().RegisterModularFeature(
    IUnrealMcpResourceProvider::GetModularFeatureName(), ResourceProvider.Get());

unreal://project/levels and unreal://project/icon are the shipped core resources — see UnrealMCP/Source/UnrealMcpRuntime/Private/Resources/UnrealMcpCoreResources.cpp. Only static, fixed-URI resources are supported today (templated / parameterized URIs are deferred). A blob is base64 on the Unreal side and the IPC wire; a known upstream quirk in the shared GameDev-MCP-Server / MCP-Plugin-dotnet can mis-emit blob bytes on the final MCP wire to the client (text resources round-trip cleanly end-to-end) — that is an upstream issue, not the Unreal plugin or bridge.

How it behaves (identical for tools, prompts, and resources):

• Auto-discovery & hot-reload. Unreal-MCP enumerates every registered provider (UnrealMcpToolProvider / UnrealMcpPromptProvider / UnrealMcpResourceProvider) on boot, and subscribes to register/unregister events — so loading or unloading your plugin at any time triggers a registry rebuild and a manifest revision bump, and the sidecar diffs the new manifest and adds/removes the affected tools / prompts / resources automatically. You never push anything yourself.
• Deterministic merge. Providers are merged in ascending GetExtensionId() order; within one provider, entries register in declaration order. Your GetExtensionId() is stamped onto everything you contribute (don't call .ExtensionId(...) yourself).
• Per-extension isolation. Each descriptor is validated (a tool/prompt needs a kebab-case name + well-formed schema + bound handler; a resource needs a non-empty URI + handler). An invalid or duplicate entry (duplicate tool/prompt name, or duplicate resource URI) is dropped/rejected and the reason is recorded on your extension's record — your other valid entries, and every other extension, are unaffected. (UE builds without C++ exceptions, so isolation is descriptor-level, not handler-body-level; validate inputs and fail gracefully with the Error(...) result helpers.)
• Toggles & enable/disable. Extension-contributed tools are toggled in the MCP Tools window like the built-ins; a disabled extension contributes nothing to any manifest. (The MCP Prompts / MCP Resources windows are wired but still render empty in this release — see Per-tool enable / disable — so prompt/resource toggling from the UI is a follow-up; registration and use work today.)

Learn more:

• Full author guide: docs/EXTENSIONS.md — the contract for tools, prompts, and resources, the builders, lifecycle, ordering, isolation semantics, and versioning.
• Design: docs/ARCHITECTURE.md §5 (tools) + §A (the prompt/resource registration path).
• Working samples: samples/UnrealAITemplate/ — a complete, buildable editor extension plugin with an RQL module (the hello operations source, a computed member, a guide); samples/UnrealAIRuntimeSample/ — the runtime (in-game) counterpart, a Type=Runtime plugin whose game-time-dilation tool reads/sets the live world's time dilation, callable in a running game over a runtime MCP connection (docs/ARCHITECTURE.md §12.9; see EXTENSIONS.md "Runtime usage"). For prompts and resources, the shipped core families (UnrealMcpCorePrompts.cpp level-design-brief, UnrealMcpCoreResources.cpp unreal://project/levels + unreal://project/icon) are the runnable reference.

Runtime usage (in-game)

Everything above drives the editor. Unreal-MCP can also run inside a running game — PIE, Standalone, or a packaged Development build — so an AI assistant can drive your game live. This is the Unreal counterpart of Unity-MCP's runtime (in-game) support: the UE analog of Unity's UnityMcpPluginRuntime.Initialize().Build().Connect() and its [AiTool] Chess-bot sample.

The runtime entry point is a UGameInstanceSubsystem, UUnrealMcpRuntimeSubsystem (in the plugin's UnrealMcpRuntime runtime module). It is auto-instantiated once per UGameInstance but never auto-connects — a connection is always an explicit, opt-in call (see the security contract below).

Connect three ways

All three reach the same UUnrealMcpRuntimeSubsystem::Connect(Host, Token, Mode, bAllowRemoteHost); the connection mode defaults to Custom (a developer-supplied loopback server).

1. From C++ (e.g. your GameMode::BeginPlay):

#include "UnrealMcpRuntimeSubsystem.h"

void AMyGameMode::BeginPlay()
{
    Super::BeginPlay();

    if (UUnrealMcpRuntimeSubsystem* Mcp = UUnrealMcpRuntimeSubsystem::Get(this))
        Mcp->Connect(TEXT("http://localhost:8080"), TEXT("my-token")); // Custom mode, loopback
    // ... and, when you are done:
    //  Mcp->Disconnect();
}

Get(WorldContext) is a static BlueprintPure helper that returns the subsystem for the context's game instance (or null). Connect returns false (and connects nothing) if any security gate rejects — see below.

2. From Blueprint — Get Unreal MCP Runtime Subsystem (the Get node, WorldContext-aware) → Connect (a BlueprintCallable node under the Unreal MCP category; Token / Mode / bAllowRemoteHost are advanced pins). Pair it with the Disconnect node and the Is Connected pure node for status.

3. From the console (QA convenience, no recompile) — registered while the subsystem is alive:

UnrealMcp.Connect <host> [token]
UnrealMcp.Disconnect

The console path always uses loopback + Custom mode.

Your own in-game tools, prompts & resources

A game ships its own gameplay tools (and, if useful, prompts and resources) and the AI drives them live — the UE analog of Unity's WithToolsFromAssembly / [AiTool] Chess-bot. You author all three exactly as for an editor extension (the Customize Tools, Prompts & Resources section above), with two changes for a game module: make it Type=Runtime and depend on UnrealMcpRuntime (not UnrealMcpEditor). Register your providers at module startup, or use the subsystem's discoverable wrappers — one register/unregister pair per kind:

if (UUnrealMcpRuntimeSubsystem* Mcp = UUnrealMcpRuntimeSubsystem::Get(this))
{
    Mcp->RegisterToolProvider(MyToolProvider);          // tools merge in; manifest re-pushed
    Mcp->RegisterPromptProvider(MyPromptProvider);      // prompts merge in; manifest re-pushed
    Mcp->RegisterResourceProvider(MyResourceProvider);  // resources merge in; manifest re-pushed
}
// ... before destroying the providers, call the matching Unregister*Provider(...) for each.

The complete, buildable example is samples/UnrealAIRuntimeSample/ — a Type=Runtime plugin whose game-time-dilation tool reads/sets the live world's AWorldSettings::TimeDilation (slow-motion / fast-forward), callable in a running game over a runtime MCP connection. (It demonstrates the tool path; prompts and resources register through the same three-wrapper API shown above and the shipped core families are the runnable reference.) The author-side details (the contract, lifecycle, ordering, isolation) are in docs/EXTENSIONS.md → Runtime usage.

Runtime tool set vs editor-only

A runtime connection ships exactly one built-in tool: ping (a liveness probe). ping is a system tool, so it answers at POST /api/system-tools/ping and is not advertised to an AI agent — meaning a packaged game that registers nothing of its own presents an empty tool list, which is an honest description of it. Everything a runtime AI agent can do is bring-your-own: register your own tools via the extension bus above (RegisterToolProvider) and they appear normally.

All of the engine-development families — the RQL data layer (rql-query / rql-mutate / rql-schema over actors, components, assets, levels, the console and editor state), every screenshot tool, plus Blueprint authoring, C++ source edit & compile, console-run-command and python-execute — are editor-only (the 26 editor tools). They drive the editor and several are RCE-class (e.g. rql-mutate, console-run-command, python-execute), so they are not compiled into a shipped game by default. There is no editor in a packaged game, so the runtime built-in surface is intentionally just ping + whatever tools your game registers.

Editor-only — exclude Unreal-MCP from packaged games

If you only want Unreal-MCP for AI tooling inside the Unreal Editor and intend to ship a packaged game with zero Unreal-MCP footprint — no runtime module, no bundled .NET sidecar binary — pin the plugin to the editor with a TargetDenyList in your consumer project's own .uproject (not the plugin's .uplugin):

// <YourProject>.uproject — "Plugins" array
{
    "Name": "UnrealMCP",
    "Enabled": true,
    "TargetDenyList": [ "Game", "Client", "Server" ]
}

UE honours TargetDenyList / TargetAllowList on a plugin reference (PluginReferenceDescriptor::IsEnabledForTarget): the plugin stays active in the Editor target, but is excluded from packaged Game / Client / Server builds — so neither the runtime infra module nor the bundled unreal-mcp-bridge sidecar is staged or compiled into your shipped product. Editor-type modules (UnrealMcpEditor) are stripped from a game build regardless; the deny-list also drops the UnrealMcpRuntime infra module and its sidecar RuntimeDependencies (§12.5), giving you a zero compiled footprint.

Caveat — do not create a direct module dependency. A TargetDenyList only excludes the plugin's own modules. If one of your game modules adds UnrealMcpRuntime (or any UnrealMcp* module) to its *.Build.cs PublicDependencyModuleNames / PrivateDependencyModuleNames, or #includes an UnrealMcp* header, that direct dependency overrides the deny-list and UBT compiles the runtime module into your game anyway. A pure editor-only project references nothing from the plugin, so it stays clean by construction — only opt into a module dependency when you actually want runtime (in-game) usage.

For runtime (in-game) usage instead, leave the deny-list off: the UnrealMcpRuntime infra module + the ping built-in ship into the packaged build (§12.5), and you register your own gameplay tools via IUnrealMcpToolProvider — see Runtime usage (in-game) and Customize Tools, Prompts & Resources. The two are mutually exclusive: deny-list for an editor-only project, no deny-list for a game that hosts a live MCP connection.

Security contract

A runtime connection is remote control of a running game (spawning actors, writing any reflected property, arbitrary CVars via console-run-command, calling UFunctions) — RCE-class if it were reachable in a shipped product. The runtime surface is therefore locked down by five layered mitigations (docs/ARCHITECTURE.md §12.8), all enforced inside Connect():

1. Opt-in only. The subsystem auto-instantiates but never auto-connects — there is no auto-dial on load and no config-asset auto-connect. A connection only ever happens through an explicit Connect() call.
2. Kill switch, default OFF. UUnrealMcpRuntimeSettings::bRuntimeMcpEnabled (Project Settings → Plugins → Unreal MCP (Runtime)) defaults to false. While it is off, every Connect() is rejected and no sidecar is spawned. It is a Game config setting (DefaultGame.ini, section [/Script/UnrealMcpRuntime.UnrealMcpRuntimeSettings]), so it travels into the packaged build where the gate must take effect. Turning it on does not auto-connect — an explicit Connect() is still required.
3. Shipping gate. The bUnrealMcpAllowShipping *.Build.cs flag defaults to false (→ UNREAL_MCP_ALLOW_SHIPPING=0); in a Shipping build Connect() logs and returns false unless that flag was deliberately compiled in. Development / PIE builds are unaffected.
4. Loopback-host default. Connect() rejects any non-loopback Host unless the caller explicitly passes bAllowRemoteHost = true. The default keeps the connection on localhost / 127.0.0.0/8 / ::1.
5. Loopback IPC + one-shot stdin token. The plugin ⇄ sidecar IPC is loopback-only and authenticated with a one-shot token delivered over stdin, never argv, and never logged (same model as the editor, ARCHITECTURE §1.4).

Additionally, the runtime path is Desktop-only (Win64 / Mac / Linux): spawning the .NET unreal-mcp-bridge sidecar process is not possible on console or mobile platforms, so those platforms have no runtime MCP surface at all.

End-to-end runbook. The full operator walkthrough — enabling the kill switch, connecting from PIE and a packaged Development build, and exercising tools over the live connection — is in docs/RUNTIME-E2E.md. The deterministic half (security gates, world-resolver switching, connect/disconnect/orphan-safety) is locked by headless Automation specs.

Configuration & environment variables

The plugin reads configuration with the precedence process env → <Project>/.env → config file → built-in defaults. The recognized UNREAL_MCP_* variables (defined in UnrealMCP/Source/UnrealMcpEditor/Private/Config/UnrealMcpConfig.cpp):

Never commit .env. A project-root .env can hold UNREAL_MCP_TOKEN, and UE project templates ship no .gitignore. unreal-mcp-cli configure appends .env to the target project's .gitignore; this repo's own scaffold already gitignores it. The sidecar IPC token travels over stdin (never argv) and is never logged.

Troubleshooting

• No connected clients. Retrying [1..10] then HTTP 500 from a local server. The connection mode defaulted to Cloud, so the sidecar dialed ai-game.dev instead of your local server. Set UNREAL_MCP_CONNECTION_MODE=Custom (env, .env, or the UI toggle).
• No [Unreal-MCP] plugin loaded line at boot. The editor module failed to load — check the Output Log for a StartupModule error or a malformed .uplugin.
• A tool body returns 'x' is required. when invoked over the REST passthrough. Send -H "Content-Type: application/json"; without it the server drops the JSON body.
• Screenshot tools return a structured error. Pixel capture needs a GPU-backed editor — they cannot render under headless -nullrhi.
• No sidecar / sidecar keeps restarting. Check the bridge status in the Connection section (Running (restarts: N) / Stopped). If the log shows no sidecar binary resolved for rid <rid> …, neither a bundled binary nor UNREAL_MCP_BRIDGE_PATH resolved — in a packaged release this means the plugin was packaged without your platform's bridge (reinstall the correct build); in a from-source build, set UNREAL_MCP_BRIDGE_PATH or run unreal-mcp-cli bootstrap-local to build one from source. (The sidecar is bundled inside packaged releases and auto-spawned, §6 — there is no download-on-first-run.)
• Ports. IPC uses a deterministic per-project port in 30000–39999 and probes forward (then an ephemeral port) on a collision; the local server uses a deterministic hash port in 20000–29999 with no probing — the CLI derives the same number without reading any config, and the server binds the exact requested port. The exact number is a debugging nicety, not a requirement.
• Logs. Use the main window's Open log file action, an RQL query (console | where Verbosity == "Error"), or the editor Output Log (LogUnrealMcp category).

How Unreal MCP Architecture Works

Unreal-MCP is a bridge between LLMs and the Unreal Editor. It exposes and explains Unreal's tools to the LLM, which then understands the interface and uses the tools according to your requests.

Because the editor is C++, the .NET McpPlugin host doesn't run in-process (as it does in Unity/Godot). Instead the plugin listens on a localhost TCP port and spawns an auto-managed sidecar process (unreal-mcp-bridge) that dials it, authenticating with a one-shot token delivered over stdin. The sidecar relays IPC ⇄ SignalR to the MCP server (cloud ai-game.dev by default, or a local gamedev-mcp-server). The AI Tools the plugin registers are then callable by any MCP-aware AI agent. The authoritative design — IPC protocol, dynamic tool registration, schema generation, the game-thread dispatcher, extensions, sidecar lifecycle, UI, and config — lives in docs/ARCHITECTURE.md (start at the §0 system-overview diagram).

What is MCP

MCP — Model Context Protocol. In a few words, it is USB Type-C for AI, specifically for LLMs (Large Language Models). It teaches the LLM how to use external features — such as the Unreal Engine in this case, or even your own custom C++ tool. Official documentation.

What is an AI agent

It is an application with a chat window. It may have smart agents to operate better, and embedded advanced MCP Tools. A well-built MCP client is 50% of the AI success in executing a task — which is why it is important to choose a good one.

What is the MCP Server

It is the bridge between the MCP Client and "something else" — in this case the Unreal Editor. In Cloud mode this is the hosted ai-game.dev backend; in Custom mode it is the shared GameDev-MCP-Server host you run yourself.

What is an MCP Tool

An MCP Tool is a function the LLM can call to interact with Unreal. These tools are the bridge between natural-language requests and actual Unreal operations. When you ask the AI to "spawn an actor" or "compile this Blueprint," it uses MCP Tools to execute the action. Tools have typed, described parameters; return structured results; and run on the editor game thread via the dispatcher (the IPC reader thread never executes tool bodies).

Repo layout

Links

• Unity-MCP — the Unity sibling
• Godot-MCP — the Godot sibling
• GameDev-MCP-Server — the shared local MCP server (gamedev-mcp-server)
• MCP-Plugin-dotnet — the shared .NET MCP plugin/server core (com.IvanMurzak.McpPlugin)
• ReflectorNet — the shared reflection/serialization core
• ai-game.dev — the cloud backend
• Model Context Protocol

License

Apache-2.0 © Ivan Murzak