Getting Started

Getting Started

This page covers prerequisites, installation, starting the MCP server, connecting an AI client, and running your first Blueprint operation.

---

Prerequisites

Requirement	Version / Notes
Unreal Engine	5.8.x (tested on 5.8.2 CL 56702186)
OS	Windows 10/11 x64
Compiler	MSVC — Visual Studio 2022 17.14+ or VS 2026 18.0+
Unreal MCP	Bundled with UE 5.8 (ModelContextProtocol plugin)
C++ Host Project	Your UE project must be a C++ project

Visual Studio workloads

Inside Visual Studio Installer, ensure you have:

• Game development with C++
• Desktop development with C++
• MSVC compiler toolset
• Windows 10/11 SDK
• C++ profiling tools

---

Installation

Step 1 — Copy the plugin

Place the UEBPCracker folder inside your project's Plugins/ directory:

<YourProject>/
└── Plugins/
    └── UEBPCracker/
        ├── UEBPCracker.uplugin
        ├── Config/
        │   └── DefaultUEBPCracker.ini
        └── Source/
            ├── UEBPCrackerEditor/
            └── UEBPCrackerEditorTests/

The reference host project is available at UEBPCrackerHost/ in the repository.

Step 2 — Generate project files

Right-click your .uproject file → Generate Visual Studio project files.

Step 3 — Build

Open the solution in Visual Studio. Set configuration to Development Editor / Win64 and build.

If you see "Missing Modules" on first run, check the first real C++ error in the UBT output rather than clicking through the dialog.

Step 4 — Enable plugins

In Unreal Editor, open Edit → Plugins and enable:

Plugin	Required?
ModelContextProtocol	✅ Required
UEBPCracker	✅ Required
ToolsetRegistry	✅ Required (usually auto-enabled)
DataValidation	Recommended
EditorScriptingUtilities	Optional
PythonScriptPlugin	Optional (for diagnostics)

Restart the editor after enabling plugins.

Step 5 — Enable write operations

By default, UEBPCracker runs in read-only mode. To enable mutations, edit (or create) Config/DefaultUEBPCracker.ini inside the plugin folder:

[/Script/UEBPCrackerEditor.UEBPCrackerSettings]
bEnableWriteOperations=True

You can also configure the content root (default /Game/AI/):

[/Script/UEBPCrackerEditor.UEBPCrackerSettings]
bEnableWriteOperations=True
AllowedWriteRoots=/Game/AI/
AllowedWriteRoots=/Game/Blueprints/

---

Starting the MCP Server

Method A — Auto-start (recommended)

Go to Edit → Editor Preferences → General → Model Context Protocol:

Setting	Value
Auto Start Server	✅ Enabled
Server Port Number	8000
Server URL Path	/mcp
Enable Tool Search	✅ Enabled

Method B — Editor console command

Open the Output Log console and run:

ModelContextProtocol.StartServer 8000

To stop:

ModelContextProtocol.StopServer

To refresh tools after a plugin recompile:

ModelContextProtocol.RefreshTools

Method C — Command-line launch

UnrealEditor.exe "path\to\UEBPCrackerHost.uproject" -ExecCmds="ModelContextProtocol.StartServer 8000"

⚠️ -ExecCmds is unreliable (~1 in 4 boots the handler never fires). For automated testing, use command-line params with FTSTicker instead. See UE 5.8 Gotchas.

---

Connecting an AI Client

The MCP endpoint is always: http://127.0.0.1:8000/mcp

VS Code / Copilot

Generate the client config from the editor console:

ModelContextProtocol.GenerateClientConfig VSCode

Or manually add to your workspace's MCP config:

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

Claude Desktop / Codex / Any MCP Client

Point the client to http://127.0.0.1:8000/mcp. The toolset name for UEBPCracker is:

UEBPCrackerEditor.UEBPCrackerToolset

---

Smoke Test

Ask your AI agent:

"Call the health_check tool on the UEBPCracker toolset."

Expected response:

{
  "success": true,
  "engineVersion": "5.8.x",
  "pluginVersion": "0.1.0",
  "toolsetVersion": "0.1.0",
  "writeRoots": ["/Game/AI/"],
  "bWriteEnabled": true,
  "bLoopbackBind": true,
  "policyFingerprint": "sha1:..."
}

If bWriteEnabled is false, check your DefaultUEBPCracker.ini.

---

First Blueprint — End-to-End Example

Direct tool calls

1. create_blueprint  →  /Game/AI/BP_HealthActor  (parent: Actor)
2. add_variable      →  Health (float, default 100.0, instance-editable)
3. add_component     →  SceneComponent (root)
4. add_component     →  StaticMeshComponent (parent: root)
5. add_function_graph → OnCalculateDamage
6. add_node          →  ReceiveBeginPlay event override
7. add_node          →  PrintString function call  (InString = "Hello!")
8. connect_pins      →  ReceiveBeginPlay.then → PrintString.execute
9. compile_blueprint
10. save_blueprint

Via .uebp.json spec

Create BlueprintSpecs/BP_HealthActor.uebp.json (see Blueprint Spec Format) and run:

validate_blueprint_spec  →  "file": "BP_HealthActor.uebp.json"
plan_blueprint_spec      →  "file": "BP_HealthActor.uebp.json"
apply_blueprint_spec     →  "file": "BP_HealthActor.uebp.json"

---

Next Steps

• Architecture — understand how the commit pipeline works
• Tool Reference — full parameter documentation for every tool
• Blueprint Spec Format — write reproducible Blueprint specs
• Security Model — configure write roots, plan hash, policy