Connecting Your AI Client

ClaudusBridge uses the Model Context Protocol (MCP) — an open standard supported by many AI clients. Here's how to connect the most popular ones.

---

Prerequisites

Before connecting, make sure:

1. Unreal Editor is open with your project loaded
2. ClaudusBridge plugin is enabled (check Edit > Plugins)
3. MCP server is running — verify with:

curl http://localhost:3000/health

Expected response:

{
  "status": "ok",
  "server": "ClaudusBridge",
  "version": "0.5.0",
  "port": 3000,
  "mcp_initialized": false,
  "tools_count": 492
}

If health check fails, see Installation & Setup first.

---

Claude Code (CLI) - Full Tutorial

Claude Code is a terminal-based AI agent. Since it runs outside the editor, it connects to ClaudusBridge over HTTP to the MCP server running inside Unreal Editor.

Step 1: Add the MCP Server with the Claude CLI

Use the Claude CLI to register the server instead of manually editing JSON:

claude mcp add --transport http claudusbridge http://localhost:3000/mcp

If you want the server stored in the current project instead of your user config, use:

claude mcp add --transport http --scope project claudusbridge http://localhost:3000/mcp

tip

This is the recommended Claude Code setup. It writes the correct MCP config schema automatically.

caution

Do not manually paste a ClaudusBridge MCP entry into Claude Code JSON config unless you are certain it matches Claude Code's expected schema. If Claude Code reports a schema or parse error, remove the malformed entry and re-add the server with claude mcp add --transport http ....

Step 2: Verify from Claude Code

Check that Claude Code can see the server:

claude mcp list

You can also open /mcp inside Claude Code and confirm that claudusbridge appears as connected.

Once connected, ask Claude Code:

"Ping ClaudusBridge"

You should see the ping command in the ClaudusBridge dashboard's Recent Activity log inside Unreal Editor.

Alternative: Manual HTTP Connection

If Claude Code is not configured yet, or if you want to test the endpoint at a low level, you can still communicate with ClaudusBridge by sending HTTP requests directly. This is useful for quick testing or one-off sessions.

1. Check the server is alive:

curl http://localhost:3000/health

2. Initialize the MCP session:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "claude-code",
        "version": "1.0.0"
      }
    }
  }'

3. Complete the handshake:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

4. Verify connection:

curl http://localhost:3000/health
# "mcp_initialized": true confirms the connection

5. Call any tool (example — list actors in the level):

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_actors",
      "arguments": {}
    }
  }'

Auto-Generated Files

On every MCP initialize (idempotent — files only regenerate when content changes), ClaudusBridge writes the canonical client support files under Saved/ClaudusBridge/:

• CLAUDE.md — Plugin architecture + tool reference for AI assistants
• UE5_EDITOR_CONTROLS.md — UE5 keyboard / mouse shortcut reference for agents driving the editor through /preview, with empirically verified Pixel Streaming gotchas
• watcher_subagent.prompt.md — Mandatory canonical prompt every connecting AI client must hand to its sub-agent spawn tool. The visual watcher observes /preview?bare=1 while the primary agent works with the user; reports flow on the agent_message bus, channel watcher.observation
• claudusbridge_watcher.py — Production-grade Python daemon for unattended persistent watching (pure stdlib, JSON logs, exponential-backoff reconnect, three pattern rules)
• claudusbridge_offline.py — Standalone MCP stdio server for offline tools (build, clean, launch editor) when the editor is not running

The plugin treats these as ephemeral — they may be safely deleted; the plugin will rewrite them on the next initialize.

Mandatory canonical setup after initialize

Every connecting AI client must perform two actions immediately after the MCP initialize handshake completes:

1. Subscribe the primary session to agent_message:

   curl -X POST http://localhost:3000/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{
         "name":"subscribe_events",
         "arguments":{
           "session":"primary",
           "event_types":["agent_message"]
         }
       }
     }'

2. Spawn the visual watcher sub-agent using the prompt at Saved/ClaudusBridge/watcher_subagent.prompt.md. In Claude Code that is the Agent tool with run_in_background: true. Other clients use their equivalent.

This is not optional: tools say success based on API return values, but the visual reality may disagree (an actor placed inside a static mesh, a material instance edited but not the one applied to the visible mesh, a Blueprint compile success that produced a warning silently). The watcher sub-agent has actual eyes on /preview?bare=1 and reports observations on channel watcher.observation so the primary agent always operates with visual ground truth instead of blind tool-success assumptions.

For session-long persistence beyond chat-runtime sub-agent timeouts, also run the Python watcher daemon:

python Saved/ClaudusBridge/claudusbridge_watcher.py

---

Claude Desktop

1. Open Claude Desktop Settings > Developer
2. Add a new MCP server:
   • Name: ClaudusBridge
   • Type: HTTP (some builds may label this as Streamable HTTP)
   • URL: http://localhost:3000/mcp

---

Cursor IDE

1. Open Cursor Settings > MCP Servers
2. Click Add MCP Server
3. Configure:
   • Name: ClaudusBridge
   • Transport: HTTP (or Streamable HTTP if Cursor labels it that way)
   • URL: http://localhost:3000/mcp

---

Windsurf

1. Open Windsurf settings
2. Navigate to the MCP configuration section
3. Add a new server with URL: http://localhost:3000/mcp

---

Codex CLI

ClaudusBridge is fully compatible with Codex CLI's strict rmcp transport. Notifications return HTTP 202 Accepted with an empty body (no Content-Type) per MCP Streamable HTTP spec 2025-03-26 — earlier ClaudusBridge versions returned 200 OK with application/json which Codex treated as Transport channel closed. As of v0.5.0 this is fixed.

codex mcp add claudusbridge --url http://localhost:3000/mcp

Verify:

codex mcp list

---

Any MCP Client

ClaudusBridge follows the MCP specification (2025-03-26). Any client that supports an MCP HTTP endpoint can connect. Some clients label this transport as Streamable HTTP in their UI.

Setting	Value
Transport	HTTP
Endpoint	http://localhost:3000/mcp
Protocol	JSON-RPC 2.0
Auth	None (local only)
Notification ACK	202 Accepted with empty body
Concurrency	Multi-session: each agent passes a unique session to subscribe / poll

If you are writing raw JSON config for a generic MCP client, use "type": "http" for the online server entry.

---

Full Build + Connect Workflow

If your project needs a fresh build (e.g., after modifying C++ code, UPROPERTY changes, or Build.cs edits), here is the complete workflow from build to connection:

1. Close the Editor

# Windows (PowerShell)
powershell -Command "Get-Process -Name UnrealEditor -ErrorAction SilentlyContinue | Stop-Process -Force"

2. Clean Build Artifacts

# Prefer cleaning only the plugin you are rebuilding
$plugin = "C:\Path\To\YourProject\Plugins\ClaudusBridge"
Remove-Item -LiteralPath (Join-Path $plugin "Binaries") -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath (Join-Path $plugin "Intermediate") -Recurse -Force -ErrorAction SilentlyContinue

3. Compile

& "C:\Program Files\Epic Games\UE_5.7\Engine\Build\BatchFiles\Build.bat" `
  YourProjectEditor Win64 Development `
  "C:\Path\To\YourProject.uproject" `
  -WaitMutex -NoHotReloadFromIDE

4. Launch the Editor

$uproject = "C:\Path\To\YourProject.uproject"
$args = ('"{0}"' -f $uproject)
Start-Process `
  -FilePath "C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor.exe" `
  -WorkingDirectory (Split-Path $uproject) `
  -ArgumentList $args

5. Wait for ClaudusBridge

After the editor loads, wait for the project to finish opening and then verify:

curl http://localhost:3000/health
# Should return: "status": "ok"

The editor must load the actual .uproject, not just the generic Unreal Editor shell. If the wrong window opens, relaunch with the .uproject path quoted exactly as shown above.

6. Connect via MCP

For Claude Code, use claude mcp add --transport http ... as described above. For other clients, add an HTTP MCP server that points to http://localhost:3000/mcp, or use the manual HTTP handshake described above for low-level testing.

caution

The editor must be fully loaded before ClaudusBridge responds. If curl fails, wait a bit longer — large projects can take over a minute to load.

---

Verifying the Connection

Once connected, the ClaudusBridge dashboard in the editor will show:

• Connection: Listening with timestamp
• Session Statistics: Command count incrementing as tools are called
• Recent Activity: Log of executed commands with status

Try asking your AI client: "Ping ClaudusBridge" — you should see ping appear in the Recent Activity log.

---

Troubleshooting

Problem	Solution
curl: connection refused	Editor not running, or ClaudusBridge not loaded yet — wait and retry
mcp_initialized: false	No MCP client has connected yet — send the initialize handshake
Claude Code reports MCP config parse/schema errors	Remove the malformed manual entry and re-add ClaudusBridge with claude mcp add --transport http claudusbridge http://localhost:3000/mcp
Tools not showing in Claude Code	Run claude mcp list, confirm claudusbridge is registered, then reconnect from /mcp
Port 3000 in use	Change port in Project Settings > Plugins > ClaudusBridge
Health check returns but tools fail	Editor may still be loading — wait for full initialization

---

Next Steps

Your AI client is connected! Try your first commands.