Third-party hosts

The Agent Panel, the mobile app, and any tool that pairs with a running session all speak one small WebSocket protocol to the orchestrator’s pairing listener. A third-party host is any client you build on that protocol — a Blender panel, a browser extension, a CLI, another editor — that attaches to a live desktop tab and drives its agent session. Same agent, same context, no second Claude Code process, nothing extra for the user to install.

This is the exact surface the mobile app is built on. If you can open a WebSocket and send JSON, you can build a host.

How it works

The desktop is already listening

When the Agent Panel is open, the orchestrator runs a token-gated pairing listener on the LAN (see Endpoints). Each open panel tab is a desktop tab with a stable tab_id and a live agent session.

Your host connects with the pairing token

Open a WebSocket to the pairing URL with the token in the query string. Without a valid token the connection is refused — pairing is the whole security boundary.

List and attach to a tab

Send list_tabs to discover the open desktop tabs, then attach_tab to mirror one. Your host now receives that tab’s activity (streamed) and can drive it.

Drive the shared session

Send user_message frames. While attached, the server routes them to the mirrored tab — so your message enters the same conversation the desktop agent is in. That’s what makes it “one agent, shared context” rather than a second session.

Endpoints

The pairing listener is derived from the bridge port (COMFYUI_MCP_BRIDGE_PORT, default 9180):

Port	Purpose
`bridge` (9180)	The panel ⇄ orchestrator UI bridge (the desktop’s own connection).
`bridge + 1` (9181)	The `panel_` HTTP-MCP surface — not* this protocol.
`bridge + 2` (9182)	The pairing / remote-control listener you connect to. Token-gated, bound on `0.0.0.0` (LAN-reachable).

Pairing URL:

ws://<desktop-machine-ip>:9182/?token=<PAIR_TOKEN>

The token is either pinned by the user via COMFYUI_MCP_PAIR_TOKEN (always-on pairing) or minted per session and handed out through the panel’s QR / pair flow. Your host obtains it the same way the mobile app does: the user pairs it once.
Bound to the LAN only. There is no built-in public exposure — if a user wants remote reach they front it with their own tunnel, and the token still gates it.

Message shapes

All frames are JSON objects with a type. Request/response frames carry a cid (correlation id) you choose, echoed back on the matching reply.

Inbound — host → orchestrator

`type`	Fields	Effect
`hello`	`tab_id`, `headless: true`	Register your connection. Third-party hosts are headless clients (no canvas of their own).
`list_tabs`	`cid`	Ask for the open desktop tabs.
`attach_tab`	`cid`, `target_tab_id`	Mirror + drive that desktop tab. Valid only for a real, non-headless desktop tab.
`detach_tab`	—	Stop mirroring/driving; your input reverts to your own (empty) session.
`user_message`	`text` (+ your usual message fields)	A turn in the mirrored tab’s conversation. Server-stamped to the attached tab.

Any other panel event you send while attached is likewise routed to the mirrored tab.

Outbound — orchestrator → host

`type`	Fields	Meaning
`tab_list`	`cid`, `tabs[]`	Reply to `list_tabs`: the attachable desktop tabs.
`tab_attached`	`cid`, `tab_id`, `ok`, `error?`	Reply to `attach_tab`. `ok:false` + `error` if the target is stale/headless.
`mailbox_flush`	buffered frames	Replay of anything the tab produced while you had no live connection.

Plus the mirrored tab’s live agent activity (streamed replies, status, cards), which your host renders.

attach_tab is authoritative — you cannot forge the target. The server overwrites any tab_id you put on an outbound frame with the tab you actually attached to. A host can only ever drive a tab it has explicitly attached to. This is deliberate; see below.

Security invariants — a host MUST preserve these

These are the guarantees that make pairing safe. Building a host that respects them is the whole contract; a host that tries to bypass them is exactly what the listener is designed to reject.

Preserving these isn’t a constraint on your host — it is the feature. They stop a client from hijacking a session it never paired to.

Token gate. The listener refuses any connection without a valid pair token (verifyClient). Never build a flow that ships or embeds the token automatically — the user pairs, once, deliberately.
Authoritative attach_tab stamping. The server, not the client, decides which tab your frames target. Don’t rely on client-supplied tab_id for routing; attach first, then send.
Non-headless targets only. You may attach to a real desktop tab, never to another headless client (you can’t mirror another phone/host).
One tab at a time. Attaching to B drops your subscription to A. Model a single active mirror per connection.
Pinned socket kind. A connection’s kind (headless vs desktop) is fixed on its first hello; don’t try to flip it to escape the takeover guards.

Minimal reference client

const token = "<PAIR_TOKEN>";            // obtained via the user's pair flow
const ws = new WebSocket(`ws://192.168.1.50:9182/?token=${token}`);
let cid = 0;

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "hello", tab_id: "myhost:" + crypto.randomUUID(), headless: true }));
  ws.send(JSON.stringify({ type: "list_tabs", cid: ++cid }));
};

ws.onmessage = (ev) => {
  const m = JSON.parse(ev.data);
  if (m.type === "tab_list") {
    // pick a desktop tab and attach to it
    const target = m.tabs[0]?.tab_id;
    if (target) ws.send(JSON.stringify({ type: "attach_tab", cid: ++cid, target_tab_id: target }));
  } else if (m.type === "tab_attached" && m.ok) {
    // now you're driving that tab's session
    ws.send(JSON.stringify({ type: "user_message", text: "Add a KSampler and wire it up." }));
  } else {
    // render streamed agent activity for the mirrored tab
    console.log("from session:", m);
  }
};

Teach an LLM to build your adapter

Paste the prompt below into Claude, ChatGPT, or your coding agent to have it scaffold a host adapter for your platform. It carries the full protocol contract, so the model doesn’t have to guess.

Copy this into your LLM

You are building a THIRD-PARTY HOST ("adapter") for comfyui-mcp. A host connects
to a running comfyui-mcp orchestrator over WebSocket, attaches to a live desktop
"tab", and drives that tab's agent session — same agent, shared context, no second
session. Build the adapter for THIS platform: <describe your platform, e.g. a
Blender sidebar panel / a Chrome extension / a Neovim plugin>.

CONNECTION
- WebSocket to:  ws://<desktop-ip>:9182/?token=<PAIR_TOKEN>
  (port = bridge port + 2; bridge default 9180. Token is provided by the user via
  their pairing flow — NEVER hardcode, embed, or auto-provision it.)
- On open, send:  {"type":"hello","tab_id":"<your-unique-id>","headless":true}

DISCOVER + ATTACH
- Send {"type":"list_tabs","cid":1}; you receive {"type":"tab_list","cid":1,"tabs":[...]}.
- Send {"type":"attach_tab","cid":2,"target_tab_id":"<a tab_id from tab_list>"};
  you receive {"type":"tab_attached","cid":2,"tab_id":"...","ok":true|false,"error"?}.
  Only real, non-headless desktop tabs are attachable.

DRIVE
- Send {"type":"user_message","text":"..."} to post a turn into the ATTACHED tab's
  conversation. The server routes it to the mirrored tab automatically.
- Send {"type":"detach_tab"} to stop.

RENDER
- After attaching you receive the mirrored tab's live activity (streamed agent
  replies, status, interactive cards) and a {"type":"mailbox_flush"} replay of
  anything produced while you were disconnected. Render these in your UI.

SECURITY — these are non-negotiable; preserve every one:
1. Only connect with a user-provided pair token; never embed or auto-ship it.
2. Never assume you can target a tab you did not attach_tab to — the server stamps
   the target authoritatively; trust tab_attached.ok, don't spoof tab_id.
3. Attach only to non-headless desktop tabs; never to another headless client.
4. One active attachment per connection (attaching to a new tab drops the old).
5. Do not try to change your connection's kind after the first hello.

DELIVERABLE
- A minimal, working adapter for the platform above: connect → list → attach →
  send a user_message → render streamed replies → detach. Handle reconnects and
  the mailbox_flush replay. Keep the pairing/token handling explicit and
  user-driven.

Register your integration

Built something? Register it so it can be listed and so we can flag protocol changes to you before they ship:

Register a third-party host

Open the registration template on GitHub — name, platform, repo, and which protocol version you built against.

Stability: the frames above are what the mobile app ships on, but this is not yet a frozen, versioned contract — read the source (src/services/ui-bridge.ts) as the authority, and register your host so you’re notified when the shapes move.

Getting Started

Configuration

How it works

Endpoints

Message shapes

Inbound — host → orchestrator

Outbound — orchestrator → host

Security invariants — a host MUST preserve these

Minimal reference client

Teach an LLM to build your adapter

Register your integration

Register a third-party host

​How it works

​Endpoints

​Message shapes

​Inbound — host → orchestrator

​Outbound — orchestrator → host

​Security invariants — a host MUST preserve these

​Minimal reference client

​Teach an LLM to build your adapter

​Register your integration

Register a third-party host

How it works

Endpoints

Message shapes

Inbound — host → orchestrator

Outbound — orchestrator → host

Security invariants — a host MUST preserve these

Minimal reference client

Teach an LLM to build your adapter

Register your integration