MCP in Unreal Engine

The Model Context Protocol (MCP) is an open specification (published at modelcontextprotocol.io) that standardizes how an AI client talks to an external tool over a small set of JSON-RPC messages such as initialize, tools/list, and tools/call. A server advertises three kinds of primitives:

• Tools — named functions the client can call, with typed parameters and return values.
• Resources — read-only data the client fetches by URI.
• Prompts — reusable prompt templates.

Unreal MCP is an MCP server: it advertises Tools backed by Unreal Engine functionality and accepts connections from any client that speaks the protocol. The server runs inside the editor process. A key part of its job is to marshal incoming requests onto the Unreal game thread, executing Tool calls serially — which is why clients should not issue overlapping calls.

Crucially, MCP is the same protocol already wiring AI assistants to IDEs, CI/CD systems, and data platforms. Unreal speaking it natively means the engine plugs into that ecosystem with no bespoke glue.

The plugin exposes engine functionality as Tools that an agent invokes on your behalf. Out of the box that includes operations such as:

• Spawning actors and placing objects in a scene.
• Configuring lighting sources, parameters, and intensities.
• Creating and modifying material instances.
• Inspecting Slate UI widgets.
• Running automation tests.

The shipped toolsets — for example SceneTools, ActorTools, MaterialInstanceTools, and ObjectTools — are mostly authored in Python and live inside the Toolset Registry plugin. They cover a broad slice of core systems (actors, assets, levels, materials, meshes, and more), and the set will grow as the feature matures.

The most important capability, though, is extensibility. The interesting productivity gains do not come from the built-in tools but from wrapping your studio-specific operations — asset import pipelines, validation rules, scene conventions — as Tools an agent can call. See Authoring custom tools.

A good first test once connected is to ask the agent something simple to confirm context is flowing, like “What actors do I have selected?” or “Spawn a directional light and set its intensity.”

Setup is short for anyone already on a version with the plugin (Unreal Engine 5.8 and later):

1. Enable the plugin

   Open Edit > Plugins, search for Unreal MCP, tick Enabled, and restart the editor when prompted. The dependent Toolset Registry plugin is enabled automatically.

2. Configure auto-start

   Open Edit > Editor Preferences > General > Model Context Protocol and turn on Auto Start Server. The server then starts on every editor launch and binds to http://127.0.0.1:8000/mcp. The same panel exposes the port (default 8000) and URL path (default /mcp).

   To start it on demand instead, leave auto-start off and run ModelContextProtocol.StartServer (optionally with a port) in the editor console.

3. Generate a client config

   From the editor console (backtick key) run the generator for your agent, for example:

   ModelContextProtocol.GenerateClientConfig ClaudeCode

   This writes .mcp.json to the project root pointing at the running server. Supported client names are ClaudeCode, Cursor, VSCode, Gemini, Codex, and All. The generated file for Claude Code looks like this:

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

   JSON configs (Claude Code, Cursor, VS Code, Gemini) are merged with existing entries, so re-running is safe. The Codex TOML config is write-once — remove a stale file by hand before regenerating.

4. Connect your agent

   Launch your AI agent CLI or app from the project/workspace root where the config was written — this is the most common reason an agent fails to find the server. If it still does not connect, start the editor first (confirm the server started in the Output Log), then launch the agent.

5. Optional: stay inside the editor

   The Terminal plugin embeds a shell panel in the editor and can run startup commands automatically. Combined with Unreal MCP, you can run the whole agent workflow in one window. Set TERM=xterm-256color first (otherwise CLIs like claude fall back to a degraded mode), then cd explicitly to where .mcp.json lives — the panel starts in FPaths::RootDir(), which is not always the same folder.

There are two routes. The first fits nearly every case; the second is for advanced, dynamic tools.

Recommended: the Toolset Registry

Write a class that derives from ToolsetDefinition and group related Tools on it. Both Python and C++ are first-class.

In Python

Python toolsets are .py modules under any plugin's Content/Python/ directory; the registry discovers them at startup. A minimal toolset looks like this:

import unreal
import toolset_registry
from toolset_registry.toolsets.core.utils import require_editable


@unreal.uclass()
class ActorTools(unreal.ToolsetDefinition):
    """Provides tools for inspecting and modifying actors, including
    their transforms, labels, parent-child relationships, and
    components."""

    @staticmethod
    @toolset_registry.tool_call
    def set_actor_label(actor: unreal.Actor, label: str) -> bool:
        """Rename an actor in the level.

        Args:
            actor: The actor to rename.
            label: The new display label.

        Returns:
            True on success.
        """
        require_editable()
        actor.set_actor_label(label)
        return True

Conventions that matter:

• @unreal.uclass() exposes the class to reflection; it inherits from unreal.ToolsetDefinition.
• The class docstring becomes the toolset's grouping description.
• Each Tool function carries @toolset_registry.tool_call and is a @staticmethod. Functions without the decorator are not advertised.
• Parameter and return type hints drive the JSON Schema the Tool advertises.
• The Google-style docstring (Args: / Returns:) is reflected into the schema — write it as carefully as any public API.

In C++

Same pattern, different syntax: derive from UToolsetDefinition, mark the class UCLASS(BlueprintType, Hidden), and expose static UFUNCTION(meta = (AICallable)) methods. Doc comments on the function and each parameter feed the schema. Reach for C++ when a Tool needs engine functionality not exposed to Python, uses USTRUCT or other reflected types that do not map cleanly to Python hints, or sits in a hot path where the Python-to-engine boundary cost matters.

After authoring

Run ModelContextProtocol.RefreshTools to force a re-poll. For C++, Live Coding picks up changed function bodies, but adding a new UFUNCTION requires a full editor restart. To hide a function inside a toolset, omit @toolset_registry.tool_call (Python) or add meta = (AIIgnore) (C++).

Advanced: direct registration

When schemas are decided at runtime, or Tools come and go dynamically, implement IModelContextProtocolTool and register it directly:

TSharedRef<IModelContextProtocolTool> Tool = MakeShared<FMyDynamicTool>();
IModelContextProtocolModule::GetChecked().AddTool(Tool);

The caller owns deregistration. As with registry tools, interface methods are invoked on the game thread.

Design guidance: keep each Tool small and single-purpose, prefer descriptive names and structured return types over free-form strings (structured types serialize to a typed JSON Schema; raw strings force the client to parse them), and write descriptions the way you would document a public API.

The server is an Experimental feature. Many features are incomplete, and APIs and data formats can change at any time. Treat it as a development-workflow tool, not a production pipeline.

• Transport: HTTP and Server-Sent Events only. No stdio or WebSocket.
• Loopback only, no auth: the listener binds to localhost and rejects non-loopback Origin headers. There is no authentication layer — do not expose it beyond the local machine.
• No Resources or Prompts: no shipping toolset advertises MCP Resources or Prompts; only Tools.
• Serial execution: Tool calls run one at a time on the game thread — clients must not issue overlapping calls.
• Editor-only registry: the Toolset Registry adapter is editor-only. Cooked/shipping builds can host a server via IModelContextProtocolModule::StartServer(), but registry tools are not auto-discovered there — they must be added explicitly with AddTool().
• Live Coding gap: new UFUNCTION declarations are not propagated; adding a Tool requires an editor restart.