Skip to content

docs(agent-tools): sync Cloud MCP docs with server v0.28.1 — full tool list, spend gating, saved-workflow execution #1217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
comfyui-wiki merged 2 commits into from
Jul 3, 2026
Merged

docs(agent-tools): sync Cloud MCP docs with server v0.28.1 — full tool list, spend gating, saved-workflow execution #1217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f390b5b
docs(agent-tools): sync Cloud MCP tool docs with server v0.28.1 (en)
mattmillerai Jul 3, 2026
dc0fcec
docs(agent-tools): sync ko/zh/ja Cloud MCP pages + i18n hashes
mattmillerai Jul 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 50 additions & 10 deletions agent-tools/cloud.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@

The **Comfy Cloud MCP server** connects AI agents to [Comfy Cloud](https://cloud.comfy.org) over the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, you can generate images, video, audio, and 3D, search models, nodes, and templates, and run ComfyUI workflows from a chat with your agent.

The server runs remotely at `cloud.comfy.org/mcp`. Workflows execute on Comfy Cloud GPUs, so you do not need a local GPU. Your agent talks to the server over HTTPS; the server translates tool calls into authenticated requests to Comfy Cloud on your behalf.

Check warning on line 20 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L20 

Did you really mean 'GPUs'?

Support is currently scoped to **Claude Code** and **Claude Desktop**, which sign in with **OAuth** (a one-time browser sign-in). Support for more clients is coming.

Expand All @@ -28,8 +28,8 @@
Typical flow:

1. **Discover** what is available (`search_templates`, `search_models`, `search_nodes`, or `cql` for graph-style questions).
2. **Run** a generation or workflow (`submit_workflow`, with `upload_file` when an input image is needed).
3. **Retrieve** outputs (`get_output` returns a download command your agent runs in your shell).
2. **Run** a generation: `run_template` for a matching pre-built template, `submit_workflow` for a custom workflow (with `upload_file` when an input image is needed), or `partner_generate` for partner models like Flux, Grok, Gemini, OpenAI, Ideogram, and Seedance.

Check warning on line 31 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L31 

Did you really mean 'Seedance'?
3. **Wait and retrieve** outputs (`wait_for_job`, then `get_output` returns a download command your agent runs in your shell).

The server prefers matching [pre-built templates](https://comfy.org/workflows) before building a workflow from scratch, which tends to produce better results faster.

Expand All @@ -42,33 +42,45 @@
| Tool | Description |
| --- | --- |
| `search_templates` | Search pre-built workflow templates from [comfy.org](https://comfy.org/workflows) by text, tag, media type, or model |
| `get_template` | Fetch a template's full workflow JSON for inspection or hand-editing |
| `get_template_schema` | See which of a template's parameters can be overridden at run time |
| `search_models` | Search the model catalog by text, type, base model, or source |
| `search_nodes` | Search available nodes by text, category, or input/output types. Also surfaces **subgraph blueprints** (pre-wired node groups like Text to Image or Remove Background) |

Check warning on line 48 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L48 

Did you really mean 'subgraph'?
| `get_node` | Get the complete input spec for specific nodes, including full option lists |
| `cql` | Run a [CQL](https://github.com/Comfy-Org/cql) graph query for structural questions (for example, which nodes produce images, or paths between node types). Use `search_nodes` when you need full input specs for a specific node |
| `get_prompting_guide` | Prompt style and recommended settings (steps, cfg, sampler, resolution) per model family |

Check warning on line 51 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L51 

Did you really mean 'cfg'?

### Execution
### Generation

| Tool | Description |
| --- | --- |
| `run_template` | Run a pre-built template by name, with optional parameter overrides — the preferred path when a template matches |

@coderabbitai coderabbitai Bot Jul 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Em dashes in new content violate the MDX style guideline.

Several newly-added rows/sentences use em dashes (—) where the guideline asks for periods, commas, colons, parentheses, or a second sentence:

  • Line 57: run_template description
  • Line 73: submit_batch, ... description
  • Line 83: run_saved_workflow description
  • Line 98: create_app description
  • Line 109: report_session_summary description
  • Line 115: "...you agreed to spend credits — so expect the agent..."
✏️ Proposed fixes 
-| `run_template` | Run a pre-built template by name, with optional parameter overrides — the preferred path when a template matches |
+| `run_template` | Run a pre-built template by name, with optional parameter overrides. Preferred path when a template matches. |
-| `submit_batch`, `get_batch_status`, `get_batch_output`, `wait_for_batch` | Submit many generations in one call and collect them together later — the batch ID stays valid across sessions |
+| `submit_batch`, `get_batch_status`, `get_batch_output`, `wait_for_batch` | Submit many generations in one call and collect them together later (the batch ID stays valid across sessions) |
-| `run_saved_workflow` | Run a saved workflow by filename — the server converts it from editor format to executable format automatically |
+| `run_saved_workflow` | Run a saved workflow by filename. The server converts it from editor format to executable format automatically. |
-| `create_app` | Turn a saved workflow into an App Mode app — a simplified "run this workflow" view with chosen inputs and outputs |
+| `create_app` | Turn a saved workflow into an App Mode app: a simplified "run this workflow" view with chosen inputs and outputs |
-| `report_session_summary` | Share an anonymized session summary with the Comfy team — **only with your explicit consent**; the agent must ask first, and no prompts, file paths, or personal information are included |
+| `report_session_summary` | Share an anonymized session summary with the Comfy team, **only with your explicit consent**. The agent must ask first, and no prompts, file paths, or personal information are included |
-...the server blocks execution until your agent confirms you agreed to spend credits — so expect the agent to check with you before those runs.
+...the server blocks execution until your agent confirms you agreed to spend credits. Expect the agent to check with you before those runs.

As per coding guidelines, "In English documentation, avoid em dashes (—); use periods, commas, colons, parentheses, or a second sentence instead."

Also applies to: 73-73, 83-83, 98-98, 109-109, 115-115

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@agent-tools/cloud.mdx` at line 57, The newly added MDX content uses em dashes
in several descriptions, which violates the documentation style guideline.
Update the affected entries in the table and prose by replacing each em dash
with a period, comma, colon, parentheses, or a second sentence, and verify the
wording in run_template, submit_batch, run_saved_workflow, create_app,
report_session_summary, and the “you agreed to spend credits” sentence all
follow the same style.

Source: Coding guidelines

| `submit_workflow` | Submit a ComfyUI API-format workflow for execution on Comfy Cloud |
| `partner_generate` | Generate with partner-API models (Flux/BFL, Grok, Gemini, OpenAI, Ideogram, Seedream/Seedance, and more) |
| `upload_file` | Upload an input image or file for use in workflows (for example, with LoadImage) |
| `apply_slots` | Apply parameter overrides to a workflow's interior values and return the modified workflow |

### Jobs and batches

| Tool | Description |
| --- | --- |
| `get_job_status` | Poll execution status of a submitted workflow |
| `wait_for_job` | Wait until a job finishes instead of polling repeatedly |
| `get_output` | Retrieve output images, videos, or audio from a completed workflow |
| `use_previous_output` | Chain workflows by reusing output from one run as input to another |
| `cancel_job` | Cancel a pending or running job |
| `get_queue` | Check how many jobs are running and pending |
| `submit_batch`, `get_batch_status`, `get_batch_output`, `wait_for_batch` | Submit many generations in one call and collect them together later — the batch ID stays valid across sessions |

### Saved workflows

| Tool | Description |
| --- | --- |
| `list_saved_workflows` | Browse your saved workflows from Comfy Cloud |
| `get_saved_workflow` | Inspect a saved workflow's nodes, inputs, and configuration |
| `get_saved_workflow` | Inspect a saved workflow's nodes, inputs, and customizable settings |
| `save_workflow` | Save a workflow to your Comfy Cloud account |

<Note>
You can browse and inspect saved workflows, but the agent cannot run them by ID directly today. Saved workflows use the ComfyUI graph format and must be converted to API format before execution. See [Known limitations](#known-limitations).
</Note>
| `update_workflow` | Update an existing workflow in place as a new version (earlier versions stay recoverable) |
| `run_saved_workflow` | Run a saved workflow by filename — the server converts it from editor format to executable format automatically |

### Sharing workflows

Expand All @@ -79,12 +91,37 @@

**Hub URL share IDs:** the trailing hyphen-delimited hex token in a `comfy.org/workflows/<slug>-<hex>` hub URL is the share ID. For example, `comfy.org/workflows/topaz-starlight-upscale-1c77e82713b7` has share ID `1c77e82713b7`. Pass that token to `import_shared_workflow` as `share_id`. The `share_url` parameter only accepts `?share=<id>` query URLs like `https://cloud.comfy.org/?share=...`, not hub page URLs.

### Apps and links

| Tool | Description |
| --- | --- |
| `create_app` | Turn a saved workflow into an App Mode app — a simplified "run this workflow" view with chosen inputs and outputs |
| `get_app_mode_url` | Get the stable link that opens a workflow as a runnable app |
| `get_workflow_canvas_url` | Get a link that opens a workflow directly on the Comfy Cloud canvas, ready to view, edit, or run |

### Account and session

| Tool | Description |
| --- | --- |
| `get_billing_status` | Check your credit balance, subscription tier, and billing link |
| `get_server_info` | Confirm which server the agent reached: environment, host, version, and auth state |
| `submit_feedback` | Get the beta feedback survey link |
| `report_session_summary` | Share an anonymized session summary with the Comfy team — **only with your explicit consent**; the agent must ask first, and no prompts, file paths, or personal information are included |

Check warning on line 109 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L109 

Did you really mean 'anonymized'?

## Credits and spending

Discovery is free: `search_templates`, `search_models`, and `search_nodes` work with just a [Comfy account](https://cloud.comfy.org). Running generations consumes Comfy Cloud credits and requires a subscription or credit balance.

Tools that spend real money are **spend-gated**. When a generation uses a paid partner model (`partner_generate`) or a workflow/template containing paid API nodes (`run_template`, `run_saved_workflow`, `submit_batch`), the server blocks execution until your agent confirms you agreed to spend credits — so expect the agent to check with you before those runs. Free, local-only workflows never prompt.

You can ask your agent about your balance at any time ("how many credits do I have?") — it answers via `get_billing_status`.

## Install

Pick your client:

<CardGroup cols={2}>
<Card title="Claude Code" icon="terminal" href="#claude-code">

Check warning on line 124 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L124 

Did you really mean 'claude'?
Install the plugin. Connection and commands in one step.
</Card>
<Card title="Claude Desktop" icon="desktop" href="#claude-desktop">
Expand Down Expand Up @@ -189,7 +226,7 @@
| `upscale-image` | Upscale an image to higher resolution |
| `remove-background` | Remove the background from an image |
| `search-templates` | Find pre-built workflow templates |
| `search-models` | Search for models (checkpoints, LoRAs, VAEs) |

Check warning on line 229 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L229 

Did you really mean 'VAEs'?
| `search-nodes` | Search nodes and get wiring suggestions |
| `help` | See what you can do with ComfyUI Cloud |

Expand All @@ -205,7 +242,7 @@
</Step>
<Step title="Add the server with the key header">
```bash
claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…"

Check warning on line 245 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L245 

Did you really mean 'mcp'?
```
</Step>
</Steps>
Expand Down Expand Up @@ -246,8 +283,8 @@

**Workflows**

- **Saved workflows cannot be run by ID.** Your agent can list and inspect saved workflows, but must reconstruct or convert them to API format before execution.
- **Generated assets may not embed workflow metadata.** Images created via MCP might not reopen the workflow when opened in ComfyUI.
- **Editor-to-executable conversion has rough edges.** Saved workflows run by filename via `run_saved_workflow` (the server converts them automatically), but some node configurations still convert imperfectly.
- **Assets generated via `submit_workflow` may not embed workflow metadata.** They might not reopen the originating workflow when opened in ComfyUI.
- **Workflow building depends on agent accuracy.** Complex multi-node workflows may need a retry or refinement.

**File handling**
Expand All @@ -268,6 +305,9 @@
<Accordion title="Do I need an API key?">
Not for Claude Code or Claude Desktop. They use OAuth. An API key is only needed for headless or CI setups with no browser.
</Accordion>
<Accordion title="Why does my agent ask before generating?">
Paid generations are spend-gated: when a run would consume Comfy Cloud credits (a partner model, or a workflow/template with paid API nodes), the server requires your explicit agreement before executing. See [Credits and spending](#credits-and-spending).
</Accordion>
<Accordion title="Do the slash commands work in Claude Desktop?">
No. Slash commands ship in the Claude Code plugin. Claude Desktop connects to the same MCP server (the tools work if you ask in plain language or use the prompt picker), but it does not support Claude Code plugins or slash commands.
</Accordion>
Expand Down
Loading
Loading