Connect an external MCP client

Configure a stdio MCP server that runs the Claudus CLI. Build it first - see Build the CLI - because the plugin ships as source and the path below does not exist until then. The client starts that local process; the proxy discovers or launches the selected Unreal project's backend. The same configuration works with the editor window open or closed.

Use the absolute .uproject path. A directory is accepted only when it contains exactly one .uproject. Replace every sample path below with your installation paths.

JSON client configuration

Claude-compatible configurations, Cursor, Windsurf and Gemini use a server entry with a command and arguments:

{
  "mcpServers": {
    "claudusbridge": {
      "command": "C:/Projects/MyProject/Plugins/ClaudusBridge/Resources/Proxy/Win64/claudus-mcp-proxy.exe",
      "args": [
        "mcp",
        "--project-path", "C:/Projects/MyProject/MyProject.uproject",
        "--launch-headless",
        "--agent", "asset-assistant"
      ]
    }
  }
}

The executable path may instead be under your engine's plugin directory. On macOS/Linux, use the matching Resources/Proxy/Mac/claudus-mcp-proxy or Resources/Proxy/Linux/claudus-mcp-proxy path, without .exe.

Use a different stable --agent value for assistants that work independently. To connect only to an already-running project, replace --launch-headless with --no-launch-headless.

VS Code

In the project's .vscode/mcp.json, the root key is servers and the type is stdio:

{
  "servers": {
    "claudusbridge": {
      "type": "stdio",
      "command": "C:/Projects/MyProject/Plugins/ClaudusBridge/Resources/Proxy/Win64/claudus-mcp-proxy.exe",
      "args": ["mcp", "--project-path", "C:/Projects/MyProject/MyProject.uproject", "--launch-headless", "--agent", "vscode-assistant"]
    }
  }
}

Codex

The equivalent entry in .codex/config.toml is:

[mcp_servers.claudusbridge]
command = 'C:\Projects\MyProject\Plugins\ClaudusBridge\Resources\Proxy\Win64\claudus-mcp-proxy.exe'
args = ['mcp', '--project-path', 'C:\Projects\MyProject\MyProject.uproject', '--launch-headless', '--agent', 'codex-assistant']

Generated configurations

ClaudusBridge's client configuration support writes the native command form. Project files include .mcp.json for Claude-compatible clients, .cursor/mcp.json, .vscode/mcp.json, .gemini/settings.json, and .codex/config.toml. Review the destination and project path when generating configuration, then restart or reload that MCP connection: an existing proxy cannot adopt new arguments automatically.

If your client has a server setup UI, choose a local command/stdio server and enter the executable and argument array. Client-specific trust or enablement controls still apply.

Verify the connection

First run doctor and ready from the installation walkthrough. In your assistant, list the available toolsets, describe one, then make a read-only call. The default tool-search mode uses:

Tool	Inputs
list_toolsets	{}
describe_toolset	{"toolset_name":"<name returned by list_toolsets>"}
call_tool	{"toolset_name":"<qualified name>","tool_name":"<tool>","arguments":{}}

Timeline tools may also appear alongside these discovery tools. The live schemas determine the required arguments; pass those exact fields.

Migrating from 1.x

Replace HTTP URL entries with the native stdio command above. ClaudusBridge 2.0 has no HTTP MCP listener, SSE endpoint, /health route or HTTP fallback. curl to the former port cannot validate the new bridge. Use status, doctor, ready and ping instead.

Old --url-path and --port proxy arguments are accepted only as deprecated compatibility inputs and do not select a native endpoint. Remove them from current configurations. Project discovery replaces a fixed MCP URL, port and Mcp-Session-Id header.

Update the plugin and rebuild the CLI together. Native wire protocol 2 can negotiate protocol 1 with compatible native backends; that does not make an HTTP-only 1.x plugin compatible.

Troubleshooting

• No tools or startup timeout: confirm the exact project, enabled plugin, matching engine and executable permissions with doctor. First startup may include project and shader work.
• unsupported-legacy: the selected running plugin advertises the removed transport. Update it and restart the project and MCP connection.
• Connected, but a tool needs a viewport: open the full editor and use the context required by that tool. Hidden mode does not create Slate widgets or a viewport camera.
• Connection lost during an edit: inspect the asset or job before retrying. Reconnection does not prove that the interrupted mutation was undone.

See transport lifecycle and limits for takeover, shutdown and build safety.