How Hayba works

Hayba connects an AI agent to a running Unreal editor. The agent talks to an MCP server; the server talks to a plugin inside the editor; the plugin runs the work on the editor's game thread and answers with structured results.

The two parts

The MCP server

A Node.js program in mcp-tools/hayba-mcp. Your MCP client starts it and talks to it over stdio using the Model Context Protocol. It holds the tool catalogue: names, descriptions and parameter schemas. It validates each call's arguments, then forwards the command to the editor. Some tools do more work on the Node side first, such as tool search, PCG graph checks, asset source downloads and agent memory.

The editor plugin

A C++ editor plugin, HaybaMCPToolkit, that loads with the editor. It opens a TCP listener on 127.0.0.1, port 52342 by default, and runs each command through one router. The router checks the command against the editor's state (Plan Mode, leases, Play-In-Editor, editor health) before a handler for that domain does the work. There are handlers for actors, assets, Blueprints, materials, UMG, PCG, levels, World Partition, Play-In-Editor, audio, animation, tests and more.

The plugin also hosts the editor UI: the Hayba MCP Toolkit tab with the in-editor chat, the approval cards, the World view and Settings.

What happens on a call

The agent calls a tool, for example hayba_invoke with name: "actor_spawn".
The server checks the arguments against the tool's schema. Through hayba_invoke, an unknown parameter is refused with the list of parameters the tool accepts.
The server sends a length-prefixed JSON message to the plugin: the command, an id and the parameters.
The plugin queues it for the game thread, where all editor work must run.
The router runs its checks. If one fails, the command is refused with a reason code and nothing runs.
For commands that change the editor, the router opens an undo transaction named Hayba: <command>, with the exceptions listed under Undo.
The handler runs and returns JSON. The server passes it back to the agent, sometimes with a hint about what to check next.

Commands are answered in order, a few per editor frame. A command that waits on the editor, such as a shader compile or a long Python script, holds up the ones behind it. See Editor busy or timeouts.

Ports and processes

Port	Who listens	What for
52342	Editor plugin	Commands from MCP servers. If it is taken, the plugin tries 52343 to 52350 in turn.
7821	Server started by the plugin	The in-editor chat and its dashboard.
52360	Server started by your client	The server's local web dashboard.
7822	Optional visual sidecar	Image embeddings for visual search. Only if you install it.

You can have two copies of the server running at once: one your MCP client starts, and one the plugin starts for the in-editor chat. Both connect to the same editor over TCP. The plugin's listener and the server's dashboard bind to 127.0.0.1, so other machines cannot reach them.

Files Hayba writes

<YourProject>/Saved/HaybaMCP/instances/<pid>.json: the port each running editor chose. The server reads these to find the editor.
<YourProject>/Saved/hayba-execution.log: a journal of every command the plugin ran, if the execution journal is on (the default).
<YourProject>/Saved/Screenshots/Hayba: images from widget renders and camera renders.
<YourProject>/.scratch: validator profiles, constraints and lessons used by the plugin's panels and the server it starts.
Saved/HaybaMCP/settings.json, relative to the server's working directory: optional routing settings.

API keys for the in-editor chat are not in these files. They are encrypted with Windows DPAPI for your user account. See In-editor chat.