MCP integration

The plugin ships an embedded MCP server (Model Context Protocol, JSON-RPC 2.0 over HTTP). Any MCP-compatible host can drive the editor: Blueprint and C++ generation, level building, materials, VFX, gameplay, debugging, Play-In-Editor verification, and Brain access.

This is the recommended way to use WoalzCraft. Driving it from a frontier model (Claude Code, Cursor) is the path that builds, plays, screenshots, and self-heals most reliably. The bearer token is persistent across editor sessions: you paste claude mcp add once per project, and the registration survives every UE restart.

Architecture

┌────────────────────┐  MCP  ┌───────────────────┐  tools  ┌──────────────────┐
│ Claude Code / CLI  │ ◀───▶ │  WoalzCraft MCP   │ ◀─────▶ │ UE Editor Engine │
│ Cursor / Cline     │ JSON  │ (localhost:7777)  │         │  build/play/...  │
│ Windsurf           │       │                   │         │                  │
└────────────────────┘       └─────────┬─────────┘         └──────────────────┘
                                       │
                                       ▼
                            ┌──────────────────────┐
                            │ WoalzCraft Brain API │
                            │  (search, submit)    │
                            └──────────────────────┘

The MCP server runs inside the editor process and is on by default. Start UE and the server starts with it, binding 127.0.0.1. Auth is a per-install bearer token, persisted to EditorPerProjectUserSettings.ini and rotatable from Project Settings.

Quick setup · Claude Code

1. Confirm the MCP server is running

It is enabled by default. To check or change it: Edit → Project Settings → Plugins → Woalz Craft → MCP Integration. The status field shows Running on :7777. The plugin auto-tries ports 7777, 7778, ... 7799 if 7777 is busy; the chosen port is written to Saved/WoalzCraft/mcp_port.txt.

2. Copy the config command (one-time)

Click Copy Claude Code Config to Clipboard (or run WoalzCraft.CopyMcpConfig in the console). Paste into your terminal:

claude mcp remove woalzcraft ; claude mcp add woalzcraft \
  http://127.0.0.1:7777 --transport http --scope user \
  --header "Authorization: Bearer <your-token>"

The claude mcp remove prefix makes the command idempotent: any existing registration is cleaned before the new one is added. If there's nothing to remove, the step prints a harmless "not found" and the add proceeds. The ; chain works in bash, zsh, and PowerShell 7+ unchanged.

3. Done, never paste again

After that one paste, the token is cached to your project's Saved/Config/WindowsEditor/EditorPerProjectUserSettings.ini. The next time you open UE for this project the same token loads from cache, so your Claude Code config stays valid. Tokens are per-project by design, each project runs its own MCP server on its own port.

4. Use it

Open Claude Code and ask:

@woalzcraft generate a blueprint that spawns a cube at (0,0,100)

Claude Code discovers the tools, picks generate_blueprint, and the plugin creates the .uasset. You'll see toast notifications in the editor.

Quick setup · Cursor

Click Copy Cursor Config Snippet. Paste under "mcpServers" in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "woalzcraft": {
      "url": "http://127.0.0.1:7777",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Restart Cursor. The tools appear in the agent panel. The token persists across UE restarts, so you only update mcp.json if you click Regenerate MCP Auth Token in plugin Settings.

Available tools (390+ total)

WoalzCraft exposes the entire UE5 authoring stack as MCP tools. Your host discovers the full, current list at connect time; the table below shows the categories with representative tool names.

Full JSON schemas for the read and contribute tools are at the API reference.

Brain contribution tools and tiers

The MCP server itself is free: there's no key check at the localhost layer. What's tier-gated is the small set of Brain contribution tools (brain_submit_*, brain_propose_correction, brain_flag_stale).

When a read-tier user calls one, the plugin sends its community/user Brain key, Brain returns 403, and the plugin translates that into actionable UX:

brain_submit_pattern: Brain rejected the request (HTTP 403). This endpoint requires a WRITE-tier API key. Set BrainWriteKey in plugin settings → Woalz Brain section. Community-tier (read) keys can't submit.

This is enforced server-side; a read-tier user can't spoof or bypass it. The MCP token is localhost auth, not a Brain credential. Write-tier keys are issued to contributors (see Contributing), not sold as a subscription.

Security notes

• Localhost-only bind: the MCP server binds 127.0.0.1, never 0.0.0.0. It's not reachable from the network without an SSH tunnel.
• Token persistence: the bearer token is cached to EditorPerProjectUserSettings.ini. UE projects typically .gitignore the entire Saved/ directory, so it doesn't leak via commits. Toggle Persist MCP Auth Token Across Sessions off for per-session generation (security-first mode), at the cost of re-pasting the config after each restart.
• Token rotation: click Regenerate MCP Auth Token if you suspect a leak. The old token returns 401 immediately; re-paste the config command once to update the host.
• MCP token ≠ Brain access: the localhost token can't grant Brain tier. Brain access is enforced separately at the BrainReadKey / BrainWriteKey layer.

Troubleshooting

"Connection refused" in the host. Editor not running, MCP toggle off, or the port moved off 7777. Check the Output Log for LogWoalzCraft: MCP server live on http://127.0.0.1:<port>. The actual port is in Saved/WoalzCraft/mcp_port.txt.

401 unauthorized. Token rotated, or the host has the wrong token. Click Copy Claude Code Config to Clipboard and re-paste.

MCP server woalzcraft already exists in user config. Use the copy-button output, which starts with claude mcp remove woalzcraft ; so the command is idempotent and never trips this.

Wrong Authorization header. It must be Authorization: Bearer <token> exactly. Most issues come from using X-API-Key (that's for the Brain HTTP API, not MCP) or dropping the Bearer prefix.

Persistence doesn't seem to work. Verify Persist MCP Auth Token Across Sessions is checked in Project Settings. If it's off, the plugin generates a fresh token each session by design, toggle it back on for one-paste-forever behavior.