Skip to main content
Version: 2.0.0

Native transport and backend lifecycle

ClaudusBridge 2.0 exposes MCP to clients over stdio through the Claudus CLI, which the plugin builds on your machine from the sources it ships with. Its Unreal backend uses authenticated, framed loopback connections. Native wire protocol 2 accepts compatible native protocol 1 clients/backends through negotiation; the MCP protocol version and plugin release version are separate concepts.

CLI command or stdio MCP client
                |
          Claudus CLI
                |
    Exact-project discovery and authentication
                |
    Existing editor OR hidden UnrealEditor-Cmd
                |
      Project's live Unreal tool catalog

Only one backend owns project work at a time. The diagram shows alternative targets, not simultaneous writers.

Discovery and readiness​

Each instance publishes its project identity, PID, native endpoint and catalog readiness in a per-user registry. The proxy matches the requested physical project and checks the advertisement. Authentication material belongs to that local connection; users do not copy tokens into a fixed HTTP URL.

  • status reads the registry without connecting. A record can be starting, ready, shadowed, invalid or unsupported legacy.
  • doctor checks project and engine prerequisites without launching anything.
  • ready --wait connects and waits for the catalog, rather than treating a process or open port as sufficient readiness.
  • ping measures a real backend round trip. Its default is discovery-only.

Select the absolute .uproject. A directory with several project files is ambiguous. A project-scoped launch lock prevents duplicate hidden starts; a mutex based on the canonical physical project path coordinates writers reached through path aliases.

With the editor window closed​

For supported engine work, the proxy starts UnrealEditor-Cmd with the ClaudusBridgeMcpServer commandlet. It loads the project and plugin, pumps engine work and the automation inbox, and uses Unreal's real object and package serialization.

The commandlet remains alive while native clients, tool execution or shader work are active. After those become idle, a short grace period allows it to shut down. A one-shot command does not reserve an always-running backend; a persistent MCP connection can keep it alive.

This mode has no interactive Slate widgets or current viewport camera. Viewport capture requires a full editor process. Materials may compile without having a render resource in commandlet mode; hasResource: false is a limitation of the context, not proof of a clean rendered result. Discover and validate each tool's runtime requirements.

Opening the interactive editor​

The interactive editor publishes a startup claim and takes priority for the same project. The proxy stops sending new work to the hidden backend, waits for in-flight work to settle, requests quiescent takeover, and verifies that the hidden process exited before connecting to the editor. If it cannot establish a safe handover, subsequent requests fail rather than writing through both processes.

Opening the GUI remains an Unreal workflow action; the CLI does not create an interactive viewport merely because a tool requests one.

Connection recovery​

Persistent mcp mode monitors the connection and can rediscover a replacement backend. It restores the MCP initialization handshake and resumes the agent session when the backend accepts that session. Background recovery itself is discovery-only; launching a hidden backend requires a foreground request through the launch-enabled path.

An interrupted tool call can return an error even if the engine applied some or all of its changes. The proxy does not promise exactly-once mutation across a crash or lost response. Inspect the object, package or job before retrying.

Idle keep-alives do not diagnose a busy synchronous tool as a dead connection. Client timeouts cancel the request cooperatively and discard late responses; they do not undo mutations or guarantee preemption of the game thread.

MCP discovery and events​

MCP clients initialize over stdio, acknowledge with notifications/initialized, then use tools/list, tools/call and resources. There are no HTTP session headers in this interface.

Tool-search mode normally exposes list_toolsets, describe_toolset and call_tool. The proxy can add timeline tools/resources when a timeline store is enabled. Eager registration is available for clients that need the full catalog. Runtime catalog changes produce notifications/tools/list_changed; progress is requested with a progress token (--progress for CLI calls).

Agent identity, session and lock events travel over the native connection. Their presence does not make multiple agents execute Unreal mutations on separate game threads. Orchestration explains scheduling and ownership.

Rebuilding or replacing the plugin​

Windows will not let a compiler overwrite a DLL that a running process has loaded, so every process holding the plugin's modules has to exit first.

  1. Pause every MCP client for the exact physical project so none can restart a backend mid-build.

  2. Save the intended project work and close the interactive editor. quiesce will not close it for you: an editor can hold unsaved packages, so that decision stays with the person at the keyboard.

  3. Stand the hidden backend down and wait for the binaries to become writable:

    claudus.exe quiesce --project-path "C:\Projects\MyProject\MyProject.uproject"

    The command sends an authenticated stand-down request, lets in-flight work finish, waits for the process to finish tearing down, and exits 0. It is idempotent when nothing is running and never starts a backend. Any agent can issue it, so a rebuild never waits on another client disconnecting.

  4. Build or replace the plugin with the correct engine and platform toolchain.

  5. Start the desired editor or hidden backend, check ready, then resume clients.

quiesce is not a maintenance lock. A request from any client can start a fresh backend while the build is running, so keep clients paused until it finishes rather than relying on the command to hold the project.

A successful C++ compilation proves compilation, not every runtime path. Check the feature's actual behavior after reloading the new modules. The CLI and the Unreal plugin modules are distinct build artifacts: after changing the CLI's own sources, rebuild it with Tools → Generate Claudus CLI or ClaudusBridge.BuildCli.

Compatibility and limits​

  • Version 2.0 has no HTTP listener, /mcp URL, /health endpoint or HTTP fallback. Follow migration.
  • The CLI builds for Win64, universal macOS and Linux x64. Native proxy tests on those systems do not by themselves validate all Unreal plugin modules or rendering behavior there.
  • Catalog entries vary with enabled plugins. A listed tool may still require a loaded world, PIE, a viewport, a selected object or another editor state.
  • Package locks cover the bridge's classified/inferred mutations. Untargeted changes can be reported after the fact; locks cannot isolate arbitrary external code or make every tool transactional.
  • Offline asset utilities have explicit format limits and are separate from engine-backed editing.