Skip to main content

​
The mental model

ComfyUI MCP is a thin, well-described layer over a running ComfyUI instance. Most tools talk to that instance over its HTTP/WebSocket API, so they work the same whether ComfyUI is local, remote (--comfyui-url), or Comfy Cloud (COMFYUI_API_KEY).
1

Generation & workflows → ComfyUI HTTP API

generate_image, enqueue_workflow, queue/history/system-stats, and the workflow authoring tools call ComfyUI’s /prompt, /queue, /history, /object_info, etc. Enqueue is fire-and-forget: you get a prompt_id immediately and results arrive via a completion notification. In cloud mode, an alternate cloud-client dispatches the same operations to cloud.comfy.org over X-API-Key.
2

Custom nodes & models → ComfyUI-Manager (HTTP), with a subprocess fallback

Node install/update/snapshot/bisect and workflow-dependency installs prefer the ComfyUI-Manager HTTP API (so they work against remote instances too), falling back to cm-cli / git / pip/uv against a local install where the API can’t do the job.
3

Install & filesystem ops → local only

Installing ComfyUI, updating core, removing model files, reading server logs, and listing the output directory operate on the local filesystem. They require a known COMFYUI_PATH and return a clear error in remote or cloud mode.
4

WebSocket → local + remote, not cloud

Job-completion notifications attach to ComfyUI’s WebSocket where available. Comfy Cloud has no WebSocket — the job watcher falls through to its existing HTTP-polling path.
Rule of thumb: anything that reads or runs the connected server works in any mode; anything that installs software or touches files on disk needs a local install. The full feature-parity matrix is in Configuration → Deployment modes.

​
Self-healing: the queue/render watchdog

A wedged high-res sampler step used to let the agent stack jobs behind a zombie render it couldn’t see or kill. Three best-effort guards close that gap, so the agent stops blindly re-queuing behind a stuck render:
  • Backpressure — panel_run appends a QUEUE WARNING to its result when a render is already running, so the agent doesn’t stack behind it.
  • Stall detection — a passive WebSocket to ComfyUI tracks the running prompt / node / progress; a step that stops advancing past the threshold (COMFYUI_MCP_STALL_S, default 180s) prepends a one-line STALL/BACKLOG note to the agent’s next turn.
  • Escalating cancel — queue (action:“cancel”) interrupts, verifies the job actually stopped (within COMFYUI_MCP_INTERRUPT_S, default 30s), then escalates to /free and reports the render WEDGED (suggesting restart_comfyui) if it still won’t die; clear_pending drops all pending jobs in the same call.
It’s all fail-safe: if the watchdog WebSocket never opens, nothing changes. The agent can also reason about an image’s colors without a vision round-trip via get_image (action:"analyze_color") (dominant palette, average + luminance stats, contrast checks).

​
Tool categories

Image Generation

Workflow Execution

Workflow Authoring

Workflow Library

Assets & Images

Models

Custom Nodes

API Nodes

Install & Environment

Process Control

Defaults, Stats & Skills

The Tool Reference is generated from the live MCP tool schemas (npm run docs:gen), so it never drifts from the code.