Skip to content

Getting started

Build Hayba from source, add the plugin to an Unreal project, connect your MCP client and make a first call. Allow about half an hour, most of it for the C++ build.

Requirements

The plugin enables the engine plugins it depends on: PCG, Python Editor Script Plugin, Web Browser Widget, Data Validation and Enhanced Input. A Blueprint-only project works: Unreal offers to build the plugin's modules the first time you open it.

Install from source

  1. Build the MCP server

    Clone the repository, install its dependencies and build the server:

    Terminal
    git clone https://github.com/zajalist/hayba.git
cd hayba
npm install
npm --prefix mcp-tools/hayba-mcp run build

    The server entry point is now at mcp-tools/hayba-mcp/dist/index.js. You will point your client at it in a later step.

  2. Link the plugin into your project

    Create <YourProject>\Plugins if it does not exist. Then, from an administrator Command Prompt (or with Windows Developer Mode on), link the plugin folder into it. Replace <YourProject> and <repo> with your project folder and your clone:

    Command Prompt
    mklink /D "<YourProject>\Plugins\HaybaMCPToolkit" "<repo>\unreal\HaybaMCPToolkit"

    A link, rather than a copy, lets the plugin find the server you just built. If you copy the plugin instead, tell it where the server is. Add this to <YourProject>/Saved/Config/WindowsEditor/EditorPerProjectUserSettings.ini, using the full path to your clone:

    EditorPerProjectUserSettings.ini
    [HaybaMCPToolkit]
SidecarEntryPath=<repo>\mcp-tools\hayba-mcp\dist\index.js

  3. Build the project

    Right-click your .uproject file and choose Generate Visual Studio project files. Open the solution and build the Development Editor configuration, or open the project and accept Unreal's offer to rebuild the missing modules. Close the editor before you rebuild after any later plugin update.

  4. Optional: satellite plugins

    Two optional plugins add commands for engine features not every project enables. Link them the same way if you want those tools:

    • unreal/HaybaMCPGAS adds Gameplay Ability System commands. It needs the engine's GameplayAbilities plugin.
    • unreal/HaybaMCPMetaSound adds MetaSound graph commands.

    The tool reference marks every tool that needs one of them.

Register with your client

Every client runs the same command: node with the full path to dist/index.js. The examples use C:\dev\hayba as the clone location; change it to yours. In JSON files, write each backslash twice.

Claude Code

Terminal
claude mcp add hayba-toolkit -- node C:/dev/hayba/mcp-tools/hayba-mcp/dist/index.js

Start Claude Code from your Unreal project folder. The server looks for the editor's port file under Saved/HaybaMCP/instances, starting from its working directory, so this lets it find the right editor when several are open.

Claude Desktop

Open Settings, then Developer, then Edit Config. This opens %APPDATA%\Claude\claude_desktop_config.json. Add the server and restart Claude Desktop:

claude_desktop_config.json
{
  "mcpServers": {
    "hayba-toolkit": {
      "command": "node",
      "args": ["C:\\dev\\hayba\\mcp-tools\\hayba-mcp\\dist\\index.js"]
    }
  }
}

Cursor

Add the server to .cursor/mcp.json in your project, or to %USERPROFILE%\.cursor\mcp.json to use it everywhere:

.cursor/mcp.json
{
  "mcpServers": {
    "hayba-toolkit": {
      "command": "node",
      "args": ["C:\\dev\\hayba\\mcp-tools\\hayba-mcp\\dist\\index.js"]
    }
  }
}

VS Code

Add the server to .vscode/mcp.json in your workspace, then use it from Copilot Chat in agent mode. VS Code names the top-level key servers:

.vscode/mcp.json
{
  "servers": {
    "hayba-toolkit": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\dev\\hayba\\mcp-tools\\hayba-mcp\\dist\\index.js"]
    }
  }
}

Optional environment variables

Most setups need none of these. Add them under env in your client config if you do.

VariableDefaultUse
UE_TCP_PORT52342Connect to one specific editor. Overrides port discovery.
UE_TCP_HOST127.0.0.1The editor's address. The plugin only listens on this machine.
DASHBOARD_PORT52360Port for the server's local web dashboard.
HAYBA_SETTINGS_PATHsee routingWhere the server reads its routing settings.

First run

  1. Open your project. On first launch the Hayba MCP Toolkit tab opens by itself. Later, open it from the Tools menu, or run the console command Hayba.MCP.Open.
  2. Check the Output Log for LogHaybaMCP: TCP server started on port 52342. Another port between 52343 and 52350 is fine; it means another editor already had 52342.
  3. In your client, ask the agent to check the connection:
Prompt
Use Hayba to check that the Unreal editor is connected, then list the actors in the current level.

The agent calls hayba_check_ue_status, then finds and calls actor_list. If the check reports that the editor is not connected, see Troubleshooting.

Plan Mode is on by default. While it is on, an external agent can only make edits you approve one at a time, and only edits to an existing actor can be approved that way. Creating assets, spawning actors and running Python are refused. Read Plan Mode, approvals and undo before you start the guides.

To chat inside the editor instead of an external client, set a provider and key in the toolkit's Settings, under Chat model. See In-editor chat.

Updating

Pull the latest source, then rebuild both halves:

Terminal
git pull
npm install
npm --prefix mcp-tools/hayba-mcp run build:server

build:server compiles the server and copies its data files without rebuilding the dashboard. Then restart your MCP client so it starts the new server, close the editor, and rebuild the project so the new plugin code loads. A running editor keeps the old plugin loaded until you restart it. See Stale build after an update.