AI Agent Guide: Building, Validating, Managing, and Executing ComfyUI Workflows via MCP
This guide serves as the definitive reference for AI coding and vision agents (Claude Code / Desktop, Cursor, Codex, Copilot, Cline, Antigravity) connecting to the comfyui-node Model Context Protocol (MCP) server.
The comfyui-node MCP server runs locally as a standard input/output (stdio) JSON-RPC process. It bridges directly into your live local ComfyUI instance via WebSocket and REST APIs.
Confirms connection to the local ComfyUI server, inspects host OS, RAM, GPU device list (VRAM capacity), queue length, installed models (checkpoints, UNETs, CLIPs, VAEs, LoRAs), samplers, schedulers, configured workflow storage directories, and automatically detected runnable recipe recommendations.
When to use: Always call first when starting a session to know what hardware, models, and curated model recipes are immediately available.
Connection fields: reachable says whether ComfyUI answered over HTTP; connected / connectionState describe the event WebSocket, which comfy_info starts on first use and may still be handshaking. Treat reachable: false as "ComfyUI is down"; reachable: true with connected: false is normal on a first call.
outputOnly?: boolean: List only terminal output nodes that save media.
When to use: Call before writing a workflow graph to inspect exact input names, expected pin data types (MODEL, LATENT, CONDITIONING, IMAGE, INT, FLOAT), default values, and output pin names/indices.
list: Discovers available recipes with descriptions, required models, categories, default parameters (steps, cfg, sampler, scheduler), and checks whether required models are installed.
scaffold: Builds a complete, validated, pre-wired workflow graph for the chosen recipe, bound to the server's installed model files, with optional automatic persistence (saveName: "my_recipe.json").
When to use: Whenever starting a task with a modern diffusion architecture to get a guaranteed-correct baseline without manually wiring nodes.
(Optional) Call comfy_workflows (action: "save", name: "my_workflow.json", workflow: customGraph, slots: { prompt: "6.inputs.text" }) to store the workflow for reuse.
Call comfy_generate with the workflow and your prompt/overrides (count: 1 or count: 4).
The tool result immediately returns the execution status, candidate URLs, and a vision-ready review image block.
[!IMPORTANT]
Distilled/Turbo models (like z_image_turbo_nvfp4.safetensors) require cfg: 1.0, steps: 8, sampler_name: "res_multistep", scheduler: "simple", and ConditioningZeroOut on the negative conditioning. Higher CFG or step counts will overbake/burn the latents.
API Prompt Format Only: Always produce API format JSON (node IDs as keys with class_type and inputs). Never output UI format JSON (with nodes and links arrays).
Never Guess Node Names: Custom node names vary between ComfyUI installations. Use comfy_nodes with query to find the exact class name and input names.
Verify Link Indices: Links are represented as [sourceNodeIdString, outputIndexInt]. Output indices are 0-based.
Distilled Model Guidance Rule: For distilled NVFP4 / Turbo models, always keep cfg: 1.0 and use ConditioningZeroOut to prevent guidance burn and overbaked contrast.
Scheduler Matching: Match the exact scheduler (beta57 for Krea2, simple for Z-Image AuraFlow) for artifact-free 8-step sampling.
Use Fixed Seeds for Targeted Tweaks: Use comfy_revise with seedPolicy: "keep" when iterating prompts.
Inspect Crops Before Re-Generating: Use comfy_inspect (mode: "crop") to inspect fine textures before re-running.
§7. Comparison: comfyui-node MCP vs. Comfy-Org/comfy-mcp
Both comfyui-node and Comfy-Org's official comfy-mcp connect MCP-compatible coding agents to a local or self-hosted ComfyUI server over stdio, but they make fundamentally different architectural choices:
Node 22+ or Bun — single npx -y comfyui-node command, zero Python environment required; ships in the same npm package as the TypeScript SDK
Python 3.10+ — requires installing both comfy-mcp and comfy-cli>=1.14 (pip install comfy-mcp "comfy-cli>=1.14")
ComfyUI Transport
In-process HTTP + WebSocket (ComfyApi) — keeps a warm WebSocket connection, streams live MCP notifications/progress, and recovers completed runs via /history without spawning child processes
Subprocess wrapper around comfy-cli — every MCP tool call shells out to comfy --where local --json <subcommand> and parses the CLI JSON envelope
~40 CLI-passthrough tools covering generation, discovery, workflow editing, model downloads, custom-node installation, and local server process management
Visual Inspection & Seed Lineage
Built-in sharp vision pipeline — returns inline MCP ImageContent contact sheets (comfy_inspect: contact_sheet, image, crop, compare parent-vs-child) and branches runs via comfy_revise with recorded parentRunId lineage
CLI media processing — video contact sheets, audio waveforms, and output file harvesting via comfy-cli
Recipe Scaffolding
Hardware-matched canonical recipes (comfy_recipes) — auto-detects installed UNETs/checkpoints/CLIPs/VAEs (krea2_turbo, z_image_turbo, sdxl_base, flux_schnell) and scaffolds a pre-wired, validated graph
Ecosystem template search — searches local templates and the Comfy ecosystem catalog
Server & Package Administration
Scoped to workflow authoring & execution — never starts/stops processes or installs arbitrary Python node packages on the host
Full host lifecycle management — includes tools to launch, stop, and restart the ComfyUI server process, pull model weights, and run install_node
Shared SDK & Multi-GPU Pools
Same library in app & agent — the workflows your agent authors and validates run unchanged in your TypeScript app on ComfyApi, WorkflowPool, or MultiWorkflowPool
Dedicated MCP wrapper — pairs with comfy-cli (and Comfy-Org's hosted https://cloud.comfy.org/mcp for cloud execution)
Use comfyui-node MCP when you want a zero-Python npx command, a compact 9-tool surface that preserves agent context budget, tight visual iteration (contact_sheet → crop → comfy_revise with seedPolicy: "keep" and recorded parent/child lineage), live WebSocket progress notifications, or one MIT-licensed package shared between your coding agent and your TypeScript/Node application.
Use Comfy-Org/comfy-mcp when you already manage your installation with comfy-cli and want the agent to administer the ComfyUI host itself (starting/restarting the local ComfyUI process, downloading checkpoints, installing custom node packs) or route jobs to Comfy Cloud.