Unreal Engine MCP Server

The Unreal Engine MCP Server is a Model Context Protocol (MCP) implementation that allows AI assistants to control Unreal Engine. It uses a native C++ Automation Bridge plugin to route commands.

Key Capabilities:

• Asset Management: Browse, import, duplicate, rename, delete, and create materials.
• Actor & Level Control: Spawn/delete actors, transform objects, manage physics, load/save levels, and handle lighting.
• Editor & Sequencer: Control PIE sessions, viewports, camera, and cinematic timelines (Sequencer/Movie Render Queue).
• Visuals & Audio: Manage Niagara particles, Blueprints, Material graphs, and Audio components/mixes.
• System: Execute console commands, manage project settings, and run Python scripts.

The MCP Automation Bridge provides a wide range of automation capabilities for Unreal Engine via AI assistants:

• Asset Management: Browse, import, duplicate, rename, delete assets; create materials.
• Actor Control: Spawn, delete, transform, physics, tags, components.
• Editor Control: PIE sessions, camera, viewport, screenshots, bookmarks.
• Level Management: Load/save levels, streaming, lighting.
• Animation & Physics: Animation BPs, state machines, ragdolls, vehicles, constraints.
• Visual Effects: Niagara particles, GPU simulations, procedural effects.
• Sequencer: Cinematics, timeline control, Movie Render Queue, media, Take Recorder, replay.
• Graph Editing: Blueprint, Niagara, Material, Behavior Tree graphs.
• Audio: Sound cues, audio components, MetaSounds.
• System: Console commands, UBT, tests, logs, project settings, Python execution.

Both transports support notifications/cancelled to handle request cancellation.

• Native MCP: Cancellation is advisory. If a request is still in the queue, it is dropped. If an editor operation is already executing (in-flight), it will run to completion, but the server will suppress the late response (the SSE socket closes without a result).
• TypeScript stdio: Inbound cancellations are forwarded to the automation bridge, which rejects the matching queued or in-flight request using an internal AbortSignal mechanism.

Scope: Cancellation is session-scoped and keyed by the client's JSON-RPC id. One session cannot cancel requests from another session. The _meta.progressToken provided by the client is preserved and echoed in notifications/progress notifications.

FMcpScopedCapabilityToken (configured via McpAutomationBridgeSettings.h#ScopedCapabilityTokens) allows for highly restricted principals. A scoped token can define:

• A specific profile
• Specific scopes (only Read, Write, or Destructive; Admin is never allowed in scoped tokens)
• Allowed path prefixes
• Allowed projects
• Per-minute request and tool-call quotas

If a scoped token conflicts with a legacy token, the scoped token takes precedence because it is narrower.

The Unreal Engine MCP Server defines three semantic axes for its capabilities to indicate how they interact with state changes:

1. Previewable: Whether a capability can be previewed before execution.
2. Undoable: Whether a capability's effects can be reversed via a standard undo operation.
3. Compensatable: Whether a capability can be reversed using a specific 'inverse' capability or manual cleanup.

By default, all capabilities are pessimistic, meaning they are assumed to have no preview, no undo, and no compensation. A capability only claims a stronger semantic (like compensation) if there is verified evidence in the implementation ledger (e.g., a verified inverse capability exists).

The project has moved to a permanent single-tool surface. The only tool returned by tools/list is unreal. All other 23 canonical parent tools are registered privately and must be accessed via unreal.execute.

Handling Direct Tool Calls (Migration): If you attempt to call a tool by name other than unreal, the server will not execute it. Instead, it returns a DIRECT_TOOL_CALL_REMOVED receipt. This receipt contains a nextCall object that you can copy-paste to perform the correct call through the gateway.

Receipt Shapes:

• Unknown tool: { "operation": "search" }
• Known tool, no action: { "operation": "describe", "tool": "<tool>" }
• Known tool with action: { "operation": "execute", "tool": "<tool>", "action": "<action>", "params": { ... } }

The MCP Automation Bridge implements several security hardening measures to prevent unauthorized access or escape attacks:

• Path Sanitization: Enforces project-relative paths (e.g., /Game, /Engine, /Script) and explicitly rejects traversal sequences like .. in commands like import or create_folder.
• Symlink Resolution: execute_python validates file paths by resolving symlinks and re-validating them against the project directory.
• Code Size Limits: execute_python enforces a maximum of 1 MB for inline code payloads.
• Authentication: When bRequireCapabilityToken is enabled, the native MCP transport validates the X-MCP-Capability-Token header.
• Request Origin: Uses ERequestOrigin to explicitly route between HTTP and WebSocket responses.

The Unreal Engine MCP Server advertises a specific set of capabilities during the initialize phase. This includes tools, resources (with subscription support), prompts, completions, and tasks.

Note that the tasks capability includes specific sub-methods: list, cancel, and requests (specifically for tools/call).

Important: The server's advertisement is derived from its actual registered handlers. If a handler is not registered, the capability will not be advertised.

{
  "tools": {},
  "resources": { "subscribe": true },
  "prompts": {},
  "completions": {},
  "tasks": { "list": {}, "cancel": {}, "requests": { "tools": { "call": {} } } }
}

When implementing GAS, choose a replication mode based on the actor's role:

• Minimal: Only replicates tags and attributes (optimized for AI).
• Mixed: Full replication for the owner, minimal for others (optimized for players).
• Full: Full replication for all actors.

If a client does not declare support for a specific primitive (resources, prompts, completions, subscriptions, or tasks), the server provides a fallback mechanism. Instead of returning a schema or knowledge dump, the server provides a single bounded, executable pointer.

Modes:

• mode: "native": The client is pointed directly at the native method.
• mode: "gateway": The client is pointed at a single bounded unreal gateway operation.

The Procedural Content Generation (PCG) framework follows a specific data flow hierarchy:

1. UPCGGraph defines the overall graph.
2. UPCGNode instances represent individual operations.
3. UPCGSettings configure those nodes.
4. Data is processed as FPCGPoint structures.
5. The final output is typically handled by a spawner like UPCGStaticMeshSpawner.

UPCGGraph → UPCGNode → UPCGSettings
                ↓
         FPCGPoint data
                ↓
    UPCGStaticMeshSpawner (output)