Connecting External MCP Clients

ClaudusBridge runs a Model Context Protocol (MCP) server inside the Unreal Editor, so any MCP-capable client — Claude Desktop, Cursor, Windsurf, VS Code, Gemini, Codex, or your own scripts — can drive the editor over HTTP. This page covers connecting those external clients.

The embedded terminal is the primary surface

The ClaudusCode terminal that ships in the plugin is the main, batteries-included way to use ClaudusBridge: the agent already runs inside the editor and is wired to the bridge for you. Connecting an external client is for when you want to drive the editor from a tool you already use elsewhere. If you just want to start working, see Your First Conversation and use the embedded terminal.

The endpoint

The server speaks JSON-RPC 2.0 over Streamable HTTP at:

http://127.0.0.1:3000/mcp

It binds to localhost only — everything stays on your machine. The port and path are configurable in Project Settings → Plugins → ClaudusBridge (or per launch with -ClaudusBridgePort=N). Confirm the server is up first:

curl http://127.0.0.1:3000/health
# { "status": "ok", "server": "ClaudusBridge", "port": 3000, "mcpPath": "/mcp" }

Add it to a client

For a Claude (CLI) client, register the bridge as an HTTP MCP server:

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

Most clients accept an equivalent HTTP/Streamable-HTTP server entry in their MCP config. A typical JSON config block looks like:

{
  "mcpServers": {
    "claudusbridge": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Auto-write the client config

ClaudusBridge can write the MCP client configuration for supported clients for you, so you don't have to hand-edit JSON. Use that when available and skip straight to talking to the editor.

The handshake

ClaudusBridge follows the MCP Streamable HTTP spec. A client connects like this:

1. initialize — the client POSTs an initialize request. The server creates a session and returns its capabilities, plus an Mcp-Session-Id header.
2. notifications/initialized — the client sends the initialized notification to complete the handshake.
3. Subsequent requests — every post-initialize request must carry the Mcp-Session-Id header returned by initialize. A request with an unknown or missing session id is rejected and the client should reinitialize.

A minimal initialize body:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-client", "version": "1.0" } }
}

ping and initialize are the only methods exempt from session validation; everything else requires a resolved session.

Tool-search mode (the default)

By default ClaudusBridge runs in tool-search mode (bEnableToolSearch). Instead of registering all 900+ tools natively — which would overwhelm a client's tool list — tools/list returns just three meta-tools. The agent discovers and dispatches the real tools on demand:

Meta-tool	What it does
list_toolsets	Lists the available toolsets (Actors/World, Blueprints, Materials, Niagara, UMG, Sequencer, Assets, Levels, Textures, Multi-User, Asset, Level, Image, Chess, and more).
describe_toolset	Returns the tools inside a named toolset, with their parameters.
call_tool	Invokes a specific tool by name with arguments, without it ever being registered as a native MCP tool.

A typical flow: call list_toolsets to see what's available, describe_toolset to read a toolset's tools, then call_tool to run one. When a user asks an open-ended "what can you do," the agent is instructed to answer by calling list_toolsets rather than guessing.

If you prefer every tool registered natively at startup (eager mode), turn off Enable Tool Search in Project Settings → Plugins → ClaudusBridge. This makes the full tool surface visible to the client directly, at the cost of a very large tool list.

Per-client notes

Client	Connection
Claude Desktop	Add an HTTP MCP server entry pointing at http://127.0.0.1:3000/mcp. ClaudusBridge can auto-write this config.
Claude (CLI)	claude mcp add --transport http claudusbridge http://127.0.0.1:3000/mcp
Cursor	Add an HTTP/Streamable-HTTP MCP server with URL http://127.0.0.1:3000/mcp in the MCP settings.
Windsurf	Add an MCP server entry with the same HTTP URL.
VS Code	Add an HTTP MCP server ("type": "http", "url": "http://127.0.0.1:3000/mcp") to your MCP config.
Gemini	Configure an HTTP MCP server pointing at the bridge URL.
Codex	Configure an HTTP MCP server pointing at the bridge URL.

All of these target the same endpoint — the only difference is where each client stores its MCP server list. When ClaudusBridge can auto-write the config for a client, prefer that over editing JSON by hand.

Troubleshooting

• Connection refused — the editor isn't running, the plugin is disabled, or the server is on a different port. Check curl http://127.0.0.1:3000/health and Project Settings.
• Unknown session id errors — your client dropped or never sent the Mcp-Session-Id header. Reinitialize.
• Only three tools show up — that's tool-search mode working as intended. Use list_toolsets / describe_toolset / call_tool, or disable Enable Tool Search for eager mode.