VibeUE

MCP Server for Unreal Engine

MCP PROXY

Keep VibeUE tools visible to your AI client even when Unreal Engine isn't running

What is the MCP Proxy?

By default, VibeUE's MCP server only runs while Unreal Editor is open. This means your AI client will show a connection error and can't see any VibeUE tools until you launch UE first — every session.

The VibeUE MCP Proxy is a lightweight Python process that runs in the background at all times. It sits between your AI client and Unreal Engine, acting as a stable relay so tools are always discoverable — whether UE is running or not.

Without the proxy:

  • Start Claude → MCP connection error
  • Must launch UE first, then reconnect
  • AI can't see tools until UE is running

With the proxy:

  • Start Claude → tools are visible immediately
  • Launch UE anytime — tool calls route through automatically
  • Friendly error if you call a tool before UE is open

How It Works

1

Proxy listens on port 8089

Your AI client connects to http://127.0.0.1:8089/mcp instead of 8088. The proxy is always available, even with UE closed.

2

Tool list served from disk

When UE starts, it writes a tools-manifest.json to %APPDATA%\VibeUE\. The proxy always serves tool definitions from this file, so your AI client sees all VibeUE tools even when UE is closed.

3

Tool calls forwarded to UE

When you actually invoke a tool, the proxy forwards the request to UE on port 8088. If UE isn't running, you get a clear friendly message instead of a cryptic connection error.

4

MCP handshake answered directly

The initialize handshake that AI clients send on startup is answered by the proxy itself — no UE required. This is what eliminates the startup connection error.

AI Client
Claude / Cursor / etc.
──── :8089 ────>
VibeUE Proxy
vibeue-proxy.py
──── :8088 ────>
Unreal Engine
(when running)

tools/list always served from manifest  |  tools/call forwarded live to UE

Setup

Step 1 — Start the Proxy

Run the launcher script included with VibeUE. It starts the proxy in the background with no console window, and kills any existing instance first:

Plugins\VibeUE\Content\Python\start-vibeue-proxy.bat

Double-click it, or run it from a terminal. Python must be installed and on your PATH (pythonw is used so no console window appears).

Step 2 — Point Your MCP Client at Port 8089

Replace port 8088 with 8089 in your MCP config. Example for Claude Code:

claude mcp add --scope user --transport stdio VibeUE-Claude -- npx -y mcp-remote http://127.0.0.1:8089/mcp --transport http-only --allow-http --header "Authorization:Bearer YOUR_API_KEY"

Same change applies to any client — just swap 8088 → 8089 in your JSON config or command. See the AI Client Setup page for per-client config examples.

Step 3 — Launch UE at Least Once

Open Unreal Engine with VibeUE enabled once to generate the tools manifest at %APPDATA%\VibeUE\tools-manifest.json. After that, the proxy can serve tool definitions even with UE closed. The manifest updates automatically every time you open UE.

Auto-Start Options

For the smoothest experience, start the proxy automatically so it's always running before you open your AI client.

Option A — Windows Startup (Recommended)

Add the launcher to Windows startup so the proxy starts with your PC:

  1. Press Win + R, type shell:startup, press Enter
  2. Create a shortcut to start-vibeue-proxy.bat and paste it into the Startup folder
  3. The proxy will now start automatically at login, before you open any AI client

The script kills any previous proxy instance before starting, so re-running it is safe.

Option B — Have Claude Start It for You

You can instruct Claude Code to check for and start the proxy at the beginning of each session. Add this to your CLAUDE.md at your Unreal project root:

## Startup
At the start of each session, ensure the VibeUE proxy is running:
- Check if anything is listening on port 8089
- If not, run: Plugins\VibeUE\Content\Python\start-vibeue-proxy.bat
- Wait a moment, then confirm the proxy started before proceeding

Claude will check port 8089 and launch the proxy automatically at the start of each conversation if it isn't already running.

Bearer Token Configuration

If you've set an API key in VibeUE, the proxy needs it to forward tool calls to UE. Create a config file in the same folder as the proxy:

File: Plugins\VibeUE\Content\Python\vibeue-proxy.json

{
  "bearer_token": "YOUR_API_KEY"
}

The proxy reads this file on startup. Restart the proxy after changing it. If no API key is set in VibeUE, you don't need this file.

Troubleshooting

Proxy won't start — "pythonw not found"

Install Python from python.org and ensure it's added to your PATH. Run python --version in a terminal to verify.

Tools list is empty

The manifest hasn't been generated yet. Open Unreal Engine with VibeUE enabled at least once. The manifest is written to %APPDATA%\VibeUE\tools-manifest.json on UE startup.

Tool calls fail even when UE is running

Check your bearer token. If VibeUE has an API key set, create vibeue-proxy.json with the correct token and restart the proxy.

How do I stop the proxy?

Run the bat script again — it kills any existing instance first. Or find and stop the pythonw process in Task Manager.

Back: AI Client Setup Next: AI Chat