> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> The model behind the tools — transports, the ComfyUI-Manager API, and the local/remote/cloud modes.

## 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](https://cloud.comfy.org) (`COMFYUI_API_KEY`).

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Custom nodes & models → ComfyUI-Manager (HTTP), with a subprocess fallback">
    Node install/update/snapshot/bisect and workflow-dependency installs prefer the
    [ComfyUI-Manager](https://github.com/Comfy-Org/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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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](./configuration#deployment-modes).
</Note>

## 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`](./configuration#panel-orchestrator--the-bridge), 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`](./configuration#job-watching), 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

<CardGroup cols={2}>
  <Card title="Image Generation" icon="image" href="./tools/image-generation" />

  <Card title="Workflow Execution" icon="play" href="./tools/workflow-execution" />

  <Card title="Workflow Authoring" icon="pen-ruler" href="./tools/workflow-authoring" />

  <Card title="Workflow Library" icon="folder-open" href="./tools/workflow-library" />

  <Card title="Assets & Images" icon="images" href="./tools/assets-images" />

  <Card title="Models" icon="box" href="./tools/models" />

  <Card title="Custom Nodes" icon="puzzle" href="./tools/custom-nodes" />

  <Card title="API Nodes" icon="cloud" href="./tools/api-nodes" />

  <Card title="Install & Environment" icon="wrench" href="./tools/install-environment" />

  <Card title="Process Control" icon="power" href="./tools/process-control" />

  <Card title="Defaults, Stats & Skills" icon="sliders" href="./tools/defaults-stats-skills" />
</CardGroup>

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