Hosts de terceros

El panel del agente, la app móvil y cualquier herramienta que se empareje con una sesión en marcha hablan un protocolo WebSocket pequeño hacia el listener de emparejamiento del orquestador. Un host de terceros es cualquier cliente que construyas sobre ese protocolo — un panel de Blender, una extensión de navegador, un CLI, otro editor — que se adjunta a una pestaña de escritorio en vivo y controla su sesión de agente. Mismo agente, mismo contexto, ningún segundo proceso de Claude Code, nada extra que instalar para el usuario.

Esta es exactamente la superficie sobre la que está construida la app móvil. Si puedes abrir un WebSocket y enviar JSON, puedes construir un host.

Cómo funciona

El escritorio ya está escuchando

Cuando el panel del agente está abierto, el orquestador ejecuta un listener de emparejamiento filtrado por token en la LAN (consulta Endpoints). Cada pestaña abierta del panel es una pestaña de escritorio con un tab_id estable y una sesión de agente en vivo.

Tu host se conecta con el token de emparejamiento

Abre un WebSocket a la URL de emparejamiento con el token en la query string. Sin un token válido la conexión se rechaza — el emparejamiento es toda la frontera de seguridad.

Lista y adjunta a una pestaña

Envía list_tabs para descubrir las pestañas de escritorio abiertas, luego attach_tab para reflejar una. Tu host ahora recibe la actividad de esa pestaña (en flujo) y puede controlarla.

Controla la sesión compartida

Envía tramas user_message. Mientras estás adjunto, el servidor las enruta a la pestaña reflejada — así que tu mensaje entra en la misma conversación en la que está el agente de escritorio. Eso es lo que lo hace «un agente, contexto compartido» en lugar de una segunda sesión.

Endpoints

El listener de emparejamiento se deriva del puerto del puente (COMFYUI_MCP_BRIDGE_PORT, por defecto 9180):

Puerto	Propósito
`bridge` (9180)	El puente UI panel ⇄ orquestador (la propia conexión del escritorio).
`bridge + 1` (9181)	La superficie HTTP-MCP `panel_*` — no este protocolo.
`bridge + 2` (9182)	El listener de emparejamiento / control remoto al que te conectas. Filtrado por token, enlazado en `0.0.0.0` (alcanzable en la LAN).

URL de emparejamiento:

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

El token o lo fija el usuario mediante COMFYUI_MCP_PAIR_TOKEN (emparejamiento siempre activo) o se acuña por sesión y se entrega a través del flujo QR / emparejamiento del panel. Tu host lo obtiene igual que la app móvil: el usuario lo empareja una vez.
Enlazado a la LAN por defecto, pero la exposición pública está integrada cuando el usuario la pide: el modal de emparejamiento del panel ofrece un modo Internet que abre un túnel rápido cifrado de cloudflared, y las empresas pueden enrutarlo a través de un relé autoalojado (COMFYUI_MCP_TUNNEL_BACKEND=relay). El token lo filtra de cualquiera de las dos formas.

Formas de los mensajes

Todas las tramas son objetos JSON con un type. Las tramas de petición/respuesta llevan un cid (id de correlación) que eliges tú, y se devuelve en la respuesta correspondiente.

Entrantes — host → orquestador

`type`	Campos	Efecto
`hello`	`tab_id`, `headless: true`	Registra tu conexión. Los hosts de terceros son clientes headless (sin lienzo propio).
`list_tabs`	`cid`	Pide las pestañas de escritorio abiertas.
`attach_tab`	`cid`, `target_tab_id`	Refleja + controla esa pestaña de escritorio. Válido solo para una pestaña de escritorio real, no headless.
`detach_tab`	—	Deja de reflejar/controlar; tu entrada vuelve a tu propia sesión (vacía).
`user_message`	`text` (+ tus campos habituales de mensaje)	Un turno en la conversación de la pestaña reflejada. El servidor lo sella a la pestaña adjunta.

Cualquier otro evento de panel que envíes mientras estás adjunto se enruta igualmente a la pestaña reflejada.

Salientes — orquestador → host

`type`	Campos	Significado
`tab_list`	`cid`, `tabs[]`	Respuesta a `list_tabs`: las pestañas de escritorio adjuntables.
`tab_attached`	`cid`, `tab_id`, `ok`, `error?`	Respuesta a `attach_tab`. `ok:false` + `error` si el destino está caducado/headless.
`mailbox_flush`	tramas en búfer	Repetición de cualquier cosa que produjo la pestaña mientras no tenías conexión en vivo.

Más la actividad en vivo del agente de la pestaña reflejada (respuestas en flujo, estado, tarjetas), que tu host pinta.

attach_tab es autoritativo — no puedes falsificar el destino. El servidor sobreescribe cualquier tab_id que pongas en una trama saliente con la pestaña a la que te adjuntaste de verdad. Un host solo puede controlar una pestaña a la que se ha adjuntado de forma explícita. Es deliberado; mira abajo.

Invariantes de seguridad — un host DEBE preservarlos

Estas son las garantías que hacen seguro el emparejamiento. Construir un host que las respete es todo el contrato; un host que intente saltárselas es exactamente lo que el listener está diseñado para rechazar.

Preservarlas no es una restricción sobre tu host — es la función. Impiden que un cliente secuestre una sesión con la que nunca se emparejó.

Puerta de token. El listener rechaza cualquier conexión sin un token de emparejamiento válido (verifyClient). Nunca construyas un flujo que envíe o incruste el token de forma automática — el usuario se empareja, una vez, a propósito.
Sellado autoritativo de attach_tab. El servidor, no el cliente, decide a qué pestaña apuntan tus tramas. No te fíes de un tab_id suministrado por el cliente para el enrutado; adjunta primero, luego envía.
Solo destinos no headless. Puedes adjuntarte a una pestaña de escritorio real, nunca a otro cliente headless (no puedes reflejar otro teléfono/host).
Una pestaña a la vez. Adjuntarte a B suelta tu suscripción a A. Modela un solo espejo activo por conexión.
Tipo de socket fijado. El tipo de una conexión (headless vs escritorio) se fija en su primer hello; no intentes voltearlo para escapar de las guardas de toma de control.

Cliente de referencia mínimo

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);
  }
};

Enséñale a un LLM a construir tu adaptador

Pega el prompt de abajo en Claude, ChatGPT o tu agente de código para que andamie un adaptador de host para tu plataforma. Lleva el contrato completo del protocolo, así que el modelo no tiene que adivinar.

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.

Registrar tu integración

¿Has construido algo? Regístralo para que se pueda listar y para que podamos avisarte de los cambios de protocolo antes de publicarlos:

Registrar un host de terceros

Abre la plantilla de registro en GitHub — nombre, plataforma, repo y contra qué versión del protocolo construiste.

Estabilidad: las tramas de arriba son las que usa la app móvil, pero esto aún no es un contrato congelado y versionado — lee el código fuente (src/services/ui-bridge.ts) como autoridad, y registra tu host para que te avisen cuando las formas se muevan.

Primeros pasos

Configuración

Cómo funciona

Endpoints

Formas de los mensajes

Entrantes — host → orquestador

Salientes — orquestador → host

Invariantes de seguridad — un host DEBE preservarlos

Cliente de referencia mínimo

Enséñale a un LLM a construir tu adaptador

Registrar tu integración

Registrar un host de terceros

​Cómo funciona

​Endpoints

​Formas de los mensajes

​Entrantes — host → orquestador

​Salientes — orquestador → host

​Invariantes de seguridad — un host DEBE preservarlos

​Cliente de referencia mínimo

​Enséñale a un LLM a construir tu adaptador

​Registrar tu integración

Registrar un host de terceros

Cómo funciona

Endpoints

Formas de los mensajes

Entrantes — host → orquestador

Salientes — orquestador → host

Invariantes de seguridad — un host DEBE preservarlos

Cliente de referencia mínimo

Enséñale a un LLM a construir tu adaptador

Registrar tu integración