WoalzCraft
Download Plugin

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 generation, editing, debugging, Brain submission, project analysis.

As of v0.9.0-alpha4 (Phase 2.20), the bearer token is persistent across editor sessions — you paste claude mcp add once per project, the registration survives every UE restart from then on. No more re-pasting after every editor reopen.

Architecture

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

The MCP server runs inside the editor process. Start UE, the server starts with it. Auth is a per-install bearer token, persisted to EditorPerProjectUserSettings.ini (default), rotatable via Project Settings.

Quick setup · Claude Code

1. Enable the MCP server

Edit → Project Settings → Plugins → Woalz Craft → MCP Integration, then toggle Enable MCP server on. Watch the status field for Running on :7777.

The plugin auto-tries ports 7777, 7778, ..., 7799 if 7777 is busy.

2. Copy the config command (one-time)

Click Copy Claude Code Config to Clipboard. 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>"

Note the claude mcp remove prefix — added in v0.9.0-alpha4 to make the command idempotent. If you already have a registration (from a previous install or session), it gets cleaned before the new one is added. If you don't have one, the remove step shows a harmless "not found" message and the add proceeds normally.

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. Next time you open UE for this project, the same token loads from cache — your Claude Code config stays valid.

For a different project, you'll paste once for that project too. Tokens are per-project intentionally — each project has its own MCP server instance bound to its own port.

4. Use it

Open Claude Code, 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 (Phase 2.20), so you only need to update mcp.json if you click Regenerate MCP Auth Token in plugin Settings.

Available tools (32 total)

Inspection & generation

| Tool | Description | | --------------------- | -------------------------------------------------------- | | generate_blueprint | Create a new Blueprint from natural language | | edit_blueprint | Modify an existing BP by name + change description | | apply_blueprint_template | Apply a pre-defined Blueprint template (15 patterns) | | duplicate_blueprint | Clone an existing BP | | apply_patch | JSON Patch RFC 6902 surgery on BP nodes/variables (Phase 2.20) | | list_blueprints | List BPs in the project (paginated) | | get_blueprint_details | Read full BP graph + variables + connections | | get_node_catalog | Browse available UE5 nodes |

Diagnostics & repair

| Tool | Description | | --------------------- | -------------------------------------------------------- | | debug_blueprint | Static + pattern analysis, returns issue list | | compile_blueprint | Compile a BP, return diagnostics (plain-English) | | auto_fix_blueprint | Auto-repair issues (BROKEN_PIN, ORPHAN_NODE, SELF_LOOP, DUPLICATE_EVENT) | | analyze_project_health | High-level project health summary |

Project context

| Tool | Description | | --------------------- | -------------------------------------------------------- | | get_project_assets | List Content/ assets by type | | get_project_index | Project structure overview | | get_woalzcraft_md | Read project-level WOALZCRAFT.md rules file | | list_templates | List available Blueprint templates | | get_blueprint_history | Recent generations + results |

Brain integration (read)

| Tool | Description | | --------------------- | -------------------------------------------------------- | | search_brain | Semantic search the Brain knowledge base | | brain_get_entry | Fetch a single Brain entry by UUID | | brain_list_entries | Paginated list with filters (type/category) | | brain_verify_entry | Validate a candidate Brain contribution client-side |

Brain integration (write — paid tier)

| Tool | Description | | ----------------------------- | ------------------------------------------------- | | brain_submit_blueprint | Submit a full BP as a contribution | | brain_submit_node_ref | Submit a single-node reference + usage example | | brain_submit_pattern | Submit a higher-level pattern (e.g. "cooldown timer") | | brain_propose_correction | Propose a fix to an existing Brain entry | | brain_flag_stale | Flag an entry as outdated |

These five require a write-tier Brain key (BrainWriteKey in plugin settings). Free / community-tier users get a clear error message pointing them to the right setting.

User memory + telemetry

| Tool | Description | | -------------------------- | --------------------------------------------------- | | get_user_preferences | Read remembered preferences | | record_user_preference | Save a preference | | get_recent_sessions | List recent chat sessions | | record_event | Log a tool-usage event |

Full JSON schemas at API reference.

Free vs paid tier safety

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

When a free-tier user calls one of those, the plugin sends the Brain BrainReadKey (community tier), Brain returns 403 Write access required, and the plugin translates that into:

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. There's no way for a free-tier user to spoof or bypass it. The MCP token (Phase 2.20 persistent) is a localhost auth, not a Brain credential.

To upgrade: buy a Pro subscription on woalz.com or via Fab, paste the issued BrainWriteKey into Project Settings.

Security notes

  • Token persistence (Phase 2.20): bearer token cached to EditorPerProjectUserSettings.ini. UE projects typically .gitignore the entire Saved/ directory, so the token doesn't leak via repo commits. Toggle off via bMcpPersistToken=false if you prefer per-session generation (security-first mode).
  • Token rotation: if you suspect a leak, click Regenerate MCP Auth Token in Project Settings. Old token returns 401 immediately on next request; the new token is also cached, so you'll re-paste the claude mcp add command once to update host config.
  • Localhost-only bind: MCP server binds to 127.0.0.1, never 0.0.0.0. Not reachable from the network without an SSH tunnel.
  • Rate-limited: Per-IP rate limiter prevents runaway tool loops.

Troubleshooting

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

Tool calls return "stub". Earlier plugin versions (pre-0.9.0) had stub implementations. Upgrade to v0.9.0-alpha4+ for full implementations of all 32 tools — auto_fix_blueprint, apply_patch, and the four brain_submit_* tools all became real implementations in this release.

401 unauthorized. Token rotated or your config has the wrong token. Click Copy Claude Code Config to Clipboard in Project Settings and re-paste.

MCP server woalzcraft already exists in user config. This was the old failure mode in v0.9.0-alpha3 and earlier. The new copy-button output starts with claude mcp remove woalzcraft ; so this should never happen again — make sure you're using the v0.9.0-alpha4+ button output.

Wrong Authorization header. Double-check the header is Authorization: Bearer <token> exactly. Most issues come from accidentally using X-API-Key (which is for Brain HTTP, not MCP) or missing the Bearer prefix.

Persistence doesn't seem to work. Verify in Project Settings that Persist MCP Auth Token Across Sessions is checked. If it's off, the plugin generates a fresh token each session — that's the intended security-first mode, but it does mean re-pasting after every restart. Toggle it back on for one-paste-forever behavior.