ContextForge Unreal

A thin third-party ContextForge adapter for Epic Games' official Unreal Engine MCP server.

Version 2.4.0 adds agent-directed, exact X/Y Blueprint node placement, detailed node/pin geometry, and rich comment-box inspection and editing to the managed UE 5.8 engine-wide editor plugin. Existing Blueprint interface, compiler, component, connection, optional auto-layout, and PIE tools remain available. It extends Epic's official ToolsetRegistry, without introducing a second MCP server. The adapter and plugin use one version and one npm release. Install once per compatible Unreal Engine build, not once per project. See engine-wide deployment.

What it does

Unreal Engine 5.8 exposes its official MCP server over local Streamable HTTP. The first Editor normally uses:

http://127.0.0.1:8000/mcp

Additional Editors can be launched with -ModelContextProtocolPort=N. ContextForge Unreal v2.3 discovers a bounded loopback range, 8000-8015 by default, identifies each Editor by its actual .uproject, and routes calls by project identity rather than treating port 8000 as a global singleton.

ContextForge still sees Unreal's native eager MCP tools directly. In the Unreal project used to validate v2, the Editor exposed 830 direct tools in one tools/list response. Those Unreal tool names and authority classifications are preserved. Object input schemas gain only the optional _contextforgeUnreal routing field, which the adapter removes before forwarding arguments to Unreal.

Related MCP server: opencode-codex-mcp

Precision Blueprint authoring

The agent decides the graph layout, not a layout solver. Read ContextForgeBlueprintTools.GetGraphSnapshot alongside Epic's existing Blueprint graph/node inspection tools, study the execution/data-pin connections, and choose deliberate graph-space coordinates. PlaceGraphNodes accepts explicit GUID-to-X/Y positions and validates stale snapshots, measured-vs-estimated node sizes, untouched neighbors, accidental comment-group membership changes, and preserved connections. It applies the reviewed batch in a single undoable transaction. No node changes are saved unless requested.

GetGraphSnapshot also reads existing comment titles, tooltip details, RGBA color, font size, comment bubble preferences, grouping behavior, nested geometric containment, and Unreal's transient comment drag-member set, with those two types of membership clearly distinguished. SetGraphComment places or updates precisely sized, styled comments around an explicitly reviewed GUID set (including nested comments). It checks for accidental overlap with unrelated nodes, returns a readback receipt, and supports repeated idempotent updates. The older FormatGraphCluster and UpsertGraphComment remain optional compatibility tools; they are not the default agent workflow. See native authoring guidance.

Engine-wide plugin installation

The same npm distribution includes contextforge-unreal-plugin, an explicitly invoked manager for build, status, install/update, and uninstall. There is no automatic engine mutation when the adapter launches or updates. ContextForge can invoke the manager through its approved Command capability during setup and future updates. The manager installs a UE-build-specific compiled plugin in Engine/Plugins/Marketplace/ContextForgeUnrealTools, never into a project. See installation and safety rules.

Prerequisites

• Unreal Engine 5.8 with the experimental Model Context Protocol plugin enabled.

• Enable Tool Search disabled in Editor Preferences > Model Context Protocol.

• The AllToolsets plugin enabled for the full engine tool collection, or the specific toolset plugins you want.

• Auto Start Server enabled, or run ModelContextProtocol.StartServer in the Editor console.

After changing Enable Tool Search, restart the Unreal MCP server.

Authority metadata

Unreal 5.8 eager tools currently do not provide MCP read/write annotations.

ContextForge Unreal therefore carries a reviewed exact-name READ manifest in src/read-only-tools.mjs. The current reviewed manifest contains 248 exact Unreal 5.8 tools. Existing manually reviewed entries are retained, and new Python-backed entries are admitted only after static review of Epic's installed UE 5.8 tool_call implementations. Ambiguous or mutating implementations remain WRITE. Every unlisted or newly introduced Unreal tool defaults to WRITE.

This is intentionally conservative. The adapter never uses runtime naming heuristics as security authority.

Runtime material instances

Epic's UE 5.8 MaterialInstanceTools is only partially compatible with runtime UMaterialInstanceDynamic objects. list_parameters accepts MaterialInterface, but the scalar, vector, texture, and static-switch value getters and setters are schema-typed to MaterialInstanceConstant, and Epic's helper implementation explicitly enforces that type. UE 5.8 exposes no separate MID parameter toolset, and ProgrammaticToolset can only orchestrate already-registered tools rather than call arbitrary Unreal APIs.

ContextForge Unreal does not synthesize a parallel MID API. Generic ObjectTools remain available for property-level inspection or manipulation where they are sufficient; broader runtime material parameter support belongs upstream in Unreal's toolsets.

Image capture compatibility

UE 5.8 has two ToolsetRegistry/MCP boundary defects that affect image capture. Omitted TOptional<> parameters are rejected unless the published schema also supplies a default, and ToolsetRegistry image values are serialized into MCP text instead of native image content.

For EditorToolset.EditorAppToolset.CaptureViewport, ContextForge Unreal supplies explicit null only for omitted captureTransform and annotations. UE 5.8 maps those nulls to unset TOptional<> values, so an omitted transform still uses the live viewport camera and omitted annotations stay disabled. Explicit caller values are never replaced.

For CaptureViewport, CaptureEditorImage, and CaptureAssetImage, the adapter recognizes only Epic's declared FToolsetImage return locations. It promotes the PNG into native MCP image/png content, removes the duplicate base64 from text/structured metadata, and preserves useful non-image metadata such as viewport camera location, rotation, FOV, grid, and actor labels. It does not scan arbitrary tool JSON for image-looking fields.

All three capture tools are statically reviewed READ operations in UE 5.8. ContextForge Unreal does not resize or recompress captures.

Niagara stack input schema compatibility

UE 5.8 exposes NiagaraToolsets.NiagaraToolset_System.SetStackInputData with overlapping JSON Schema oneOf branches for Niagara float (number) and int32 (integer) values. JSON integers satisfy both branches, which makes an otherwise valid integer payload fail strict oneOf validation before it reaches Unreal.

For this exact tool and only when both overlapping numeric branches are present, ContextForge Unreal publishes that nested value union as anyOf. The branch schemas and tool arguments remain unchanged, and every unrelated Unreal schema is passed through untouched.

Tool changes and hot reload

Unreal advertises tools.listChanged: true. ContextForge Unreal forwards native notifications/tools/list_changed notifications downstream, so ContextForge can refresh the direct tool catalog without a Skill restart.

Run ModelContextProtocol.RefreshTools in Unreal when tool registrations change.

The large eager catalog is intentional. Searching or filtering admitted tool catalogs belongs in ContextForge/Keel so exact Unreal schemas, tool identity, and reviewed authority metadata remain available; this adapter does not fall back to Unreal Tool Search.

Connection behavior

The upstream HTTP session is connected lazily and kept warm. Unreal Editor tool calls are serialized because Editor MCP work runs on the game thread.

Reviewed READ calls may retry once when a previously warm connection has gone stale. WRITE calls are never automatically retried after dispatch because their outcome may be ambiguous after a transport failure.

Faster updates

The release package contains a bundled adapter with no runtime npm dependencies. ContextForge Discovery can inspect and seal the package without performing a cold dependency hydration step.

Build and test dependencies remain development-only and are not required by the installed Skill.

ContextForge installation

This adapter is not bundled with ContextForge.

1. Open the latest release from Smangsty/contextforge-unreal.

2. Download the release .tgz through ContextForge Discovery.

3. Prepare and review the exact candidate.

4. Admit and enable it only after human review.

Network containment

ContextForge grants this adapter its INTERNET_CLIENT profile because the adapter opens an HTTP socket.

The adapter accepts loopback HTTP only. Endpoint validation refuses remote hosts, HTTPS endpoints, credentials, query strings, and URL fragments.

Design constraints

• No Unreal Engine binaries are redistributed.

• Unreal owns engine behavior and the native tool schemas.

• The adapter owns transport conversion, loopback containment, reviewed authority annotations, serialized calls, and connection recovery.

• Native eager tools are required. Tool Search mode is rejected with a direct prerequisite error.

• The adapter can start while Unreal is closed; tool requests then report the missing Editor MCP endpoint.

• Epic's optional unreal_mcp_proxy is not required for ContextForge Unreal.

Development

npm run build produces the bundled executable at bin/contextforge-unreal.mjs.

npm test validates endpoint containment, eager-mode detection, authority annotation behavior, and tool-list-change forwarding.

npm run check-version verifies package, lockfile, source, and server manifest versions stay aligned and prevents runtime dependencies from sneaking back into the release.

npm pack builds, tests, and validates the self-contained release artifact.

License

MIT