ComfyUI Agent Bridge

In-graph Agent Emit / Agent Receive nodes on named channels, plus an in-process MCP server, so an externally-running coding agent (Claude Code / Codex) can exchange text and images with a ComfyUI workflow mid-pipeline and trigger runs.

How it works

A thread-safe singleton ChannelStore holds, per named channel, an inbox (graph -> agent) and an outbox (agent -> graph), each with a turn counter. ComfyUI nodes touch the store directly (same process). A FastMCP streamable-HTTP server runs in a daemon thread on a side port; its tools touch the same singleton. Text crosses inline; images cross by file path through a temp dir.

• inbox = graph -> agent: written by Agent Emit, read by the comfy_pull tool.
• outbox = agent -> graph: written by the comfy_push tool, read by Agent Receive.

Install

Clone (or symlink) this repo into your ComfyUI custom_nodes directory and install the dependency, then restart ComfyUI:

cd ComfyUI/custom_nodes
git clone https://github.com/ethanfel/ComfyUI-Agent-Bridge
pip install -r ComfyUI-Agent-Bridge/requirements.txt   # mcp>=1.2.0 (validated on 1.28.1)

(The custom_nodes subdirectory name is arbitrary — ComfyUI loads the package regardless.)

On startup ComfyUI loads the package and the bridge logs its URL:

[comfyui-nodes-agents] MCP bridge on http://127.0.0.1:9188/mcp  (claude mcp add --transport http comfy http://127.0.0.1:9188/mcp)

The bridge autostarts from __init__.py and is wrapped in try/except, so a bridge failure never blocks ComfyUI from loading the nodes.

The two nodes (category agents/bridge)

Agent Emit (-> agent) — send from the graph to the agent.

• Inputs: channel (STRING, default main); optional text (multiline STRING), image (IMAGE), seed (INT, socket input — e.g. wire a KSampler seed).
• Writes the latest text/image/seed to the channel inbox (image is saved to a PNG in the temp dir and the path is stored). Passes (text, image, seed) straight through as outputs, so you can wire it inline.

Agent Receive (<- agent) — receive from the agent into the graph.

• Inputs: channel (STRING, default main); wait_seconds (FLOAT, default 30.0, max 86400); keep_last (BOOLEAN, default true); stop_on_timeout (BOOLEAN, default true); optional signal (any type).
• signal — an order-only dependency input: wire any upstream output into it to force that node to run before this Receive. Use it to guarantee an Agent Emit (which sends the prompt to the agent) fires first, so Receive isn't waiting before the agent has anything to work on. The value is ignored.
• Outputs (text, image, seed) — seed (INT) is whatever the agent passed to comfy_push(seed=...), or 0 if none. Wire it into a KSampler, etc.
• Blocks up to wait_seconds for a new comfy_push on the channel. Each pushed value is consumed once (turn-based), so a second receive with no new push won't replay it.
• keep_last — on timeout (no new message), output the last message again instead of blanking. Great for Auto Queue so the display holds steady between evals. Off → returns "" + a 64x64 black placeholder on timeout.
• stop_on_timeout — on timeout, signal the ComfyUI frontend to switch Auto Queue off, so the loop halts when the message stream goes quiet instead of spinning. (Handled by the bundled web/agent_bridge.js; best-effort across ComfyUI frontend versions.)

Single Receive per channel: the consume-once model means two Agent Receive nodes on the same channel compete for pushes. Use distinct channel names.

wait_seconds blocks a ComfyUI execution worker for its whole duration. Outside interactive use, keep it modest (seconds, not hours) so you don't tie up a worker waiting on an agent.

Connecting an agent

The bridge speaks MCP over streamable HTTP at http://127.0.0.1:9188/mcp.

Codex (plugin — recommended)

This repo ships as a Codex plugin. Point Codex at the repo as a marketplace, then install the plugin; Codex auto-registers the comfy MCP server (HTTP, no auth) and the comfyui-bridge skill. Verified on Codex CLI 0.142.3:

# from GitHub:
codex plugin marketplace add ethanfel/ComfyUI-Agent-Bridge
# ...or from a local clone:
codex plugin marketplace add /path/to/ComfyUI-Agent-Bridge

codex plugin add comfyui-agents@comfyui-agents

Confirm registration:

codex mcp get comfy
# transport: streamable_http
# url: http://127.0.0.1:9188/mcp

The plugin only declares the HTTP server URL, so ComfyUI (and the bridge) must be running for the tools to connect.

Codex (single MCP server, no plugin)

If you'd rather not install the plugin, add just the MCP server:

codex mcp add comfy --url http://127.0.0.1:9188/mcp

This writes a streamable-HTTP entry equivalent to:

[mcp_servers.comfy]
url = "http://127.0.0.1:9188/mcp"

Codex (stdio only): if your Codex build can only speak stdio MCP, point it at scripts/codex_stdio_shim.py — a real stdio<->HTTP MCP proxy that connects to the same bridge URL and forwards tool calls. Equivalent to codex mcp add comfy --env COMFY_BRIDGE_URL=http://127.0.0.1:9188/mcp -- python /abs/path/scripts/codex_stdio_shim.py:

[mcp_servers.comfy]
command = "python"
args = ["/abs/path/ComfyUI-Nodes-Agents/scripts/codex_stdio_shim.py"]
env = { COMFY_BRIDGE_URL = "http://127.0.0.1:9188/mcp" }

The shim requires ComfyUI (and the bridge) to be running; if it can't reach the HTTP bridge it exits non-zero with a clear stderr message so Codex surfaces the error. Use an absolute path to the shim.

Claude Code (HTTP)

claude mcp add --transport http comfy http://127.0.0.1:9188/mcp

Then in Claude Code, /mcp should list the five tools.

Running ComfyUI in Docker / on another host

The bridge binds 127.0.0.1 by default, reachable only from the same host (inside the container). To reach it from an agent on another machine:

1. Bind all interfaces — set COMFY_BRIDGE_MCP_HOST=0.0.0.0 in the container.
2. Publish the port — -p 9188:9188 (or ports: ["9188:9188"] in compose).
3. Point the agent at the server IP, not localhost:

   claude mcp add --transport http comfy http://192.168.1.12:9188/mcp
   codex  mcp add comfy --url        http://192.168.1.12:9188/mcp
   

   For the Codex plugin, edit .codex-plugin/mcp.json's url to the server IP (or just use codex mcp add above).

COMFY_BASE_URL stays http://127.0.0.1:8188 — the bridge runs inside the ComfyUI container and reaches ComfyUI over the container's own localhost.

Images across hosts. Images cross by file path. By default the bridge writes them into ComfyUI's output directory (output/agent_bridge/), which in a typical setup is a shared mount visible at the same path to both ComfyUI and the agent — so paths resolve on both sides with no configuration.

If your container mounts that folder at a different internal path than the agent sees, set both:

• COMFY_BRIDGE_TMP — dir the bridge writes, container-side (e.g. /ComfyUI/output/agent_bridge)
• COMFY_BRIDGE_TMP_PUBLIC — the path the agent sees for it (e.g. /media/unraid/comfyui/output/agent_bridge)

comfy_pull then advertises the agent-visible path and comfy_push translates it back to the container path before Agent Receive loads it. Text needs none of this — it's inline.

Security: binding 0.0.0.0 exposes the bridge — including comfy_run_workflow (runs saved workflows) and file-path reads — to your LAN with no authentication. Keep it on a trusted network or firewall the port.

MCP tools

Tool	Direction	Purpose
comfy_pull(channel="main")	graph -> agent	Read the latest text/image/seed emitted on a channel (returns {turn, text, image_path, seed}).
comfy_push(channel="main", text=None, image_path=None, seed=None)	agent -> graph	Send text/image/seed to the channel's Agent Receive node.
comfy_list_channels()	—	List active channels and their turn counters.
comfy_run_workflow(name, inputs=None, wait=True)	—	Load a saved workflow from workflows/, optionally inject inputs, queue it via the ComfyUI API, optionally poll for results.
comfy_get_result(prompt_id)	—	Fetch produced images/outputs for a queued prompt id.

comfy_run_workflow reads workflows/<name>.json (API-format export). inputs overrides node fields keyed as "<node_id>.<field>", e.g. {"6.text": "a red fox"}. With wait=True it polls the ComfyUI /history endpoint (bounded ~60s) until outputs appear.

The core loop

1. Graph: Load Image -> Agent Emit (channel=in). Queue the prompt.
2. Agent: comfy_pull("in") -> get the image path; inspect/edit it.
3. Agent: comfy_push("out", text="...", image_path="<edited>.png").
4. Graph: Agent Receive (channel=out, wait_seconds=30) -> Preview/Save. Queue; the text + image arrive.

For a full render round-trip: save an API-format workflow to workflows/txt2img.json with an Agent Receive(channel=prompt) feeding the prompt and an Agent Emit(channel=render) on the output, then from the agent: comfy_push("prompt", "a red fox") -> comfy_run_workflow("txt2img", wait=true) -> comfy_pull("render").

Environment variables

Variable	Default	Effect
COMFY_BRIDGE_MCP_HOST	127.0.0.1	Interface the MCP bridge binds. Set 0.0.0.0 to reach it from another host (e.g. ComfyUI in Docker). See Running ComfyUI in Docker.
COMFY_BRIDGE_MCP_PORT	9188	Port the MCP bridge binds (use 0 for an ephemeral port, e.g. in tests).
COMFY_BRIDGE_TMP	ComfyUI output/agent_bridge	Dir where Agent Emit writes image PNGs. Defaults to ComfyUI's output dir (a shared, same-path mount in typical setups); falls back to .comfy_bridge_tmp outside ComfyUI.
COMFY_BRIDGE_TMP_PUBLIC	(unset)	If the container mounts the temp dir at a different path than the agent sees, the prefix the agent should see. comfy_pull advertises it; comfy_push translates back. See Docker.
COMFY_BRIDGE_TMP_TTL	3600	Age (seconds) after which save_tensor_png reaps old img_*.png temp files.
COMFY_BRIDGE_WORKFLOWS	workflows	Dir that comfy_run_workflow loads <name>.json from.
COMFY_BASE_URL	http://127.0.0.1:8188	ComfyUI HTTP API base URL used by comfy_run_workflow / comfy_get_result.

Development

COMFY_BRIDGE_MCP_PORT=0 python -m pytest tests/ -v

COMFY_BRIDGE_MCP_PORT=0 makes the entrypoint import (which autostarts the bridge) bind an ephemeral port instead of the fixed 9188. The test suite includes a real MCP round-trip (tests/bridge/test_mcp_roundtrip.py) that boots the streamable-HTTP server on a free port and drives it with a real MCP client.