Expand Comfy Cloud MCP user docs and sync i18n (#1204)

Document MCP tools, outputs, workflow sharing, and known limitations so users know what agents can do without server-side setup details.

Author: comfyui-wiki

agent-tools/cloud.mdx

@@ -15,17 +15,77 @@ import CloudFeature from '/snippets/cloud-feature.mdx'
 
 ## Overview
 
-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 — all from a chat with your agent.
+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.
 
-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.
+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.
+
+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.
+
+## What your agent can do
+
+You do not call MCP tools yourself. Your agent picks the right tool based on what you ask for. Slash commands and prompts (below) are shortcuts that steer the agent toward common tasks, but plain language works too ("generate an image of a cat astronaut", "upscale this photo", "find a Wan 2.2 video template").
+
+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).
+
+The server prefers matching [pre-built templates](https://comfy.org/workflows) before building a workflow from scratch, which tends to produce better results faster.
+
+## MCP tools
+
+These are the tools your agent has access to once connected. Names match what appears in MCP client logs and debugging.
+
+### Discovery
+
+| Tool | Description |
+| --- | --- |
+| `search_templates` | Search pre-built workflow templates from [comfy.org](https://comfy.org/workflows) by text, tag, media type, or model |
+| `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) |
+| `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 |
+
+### Execution
+
+| Tool | Description |
+| --- | --- |
+| `submit_workflow` | Submit a ComfyUI API-format workflow for execution on Comfy Cloud |
+| `upload_file` | Upload an input image or file for use in workflows (for example, with LoadImage) |
+| `get_job_status` | Poll execution status of a submitted workflow |
+| `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 |
+
+### 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 |
+| `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>
+
+### Sharing workflows
+
+| Tool | Description |
+| --- | --- |
+| `share_workflow` | Publish a saved workflow and return a `?share=<id>` URL anyone can open |
+| `import_shared_workflow` | Resolve a share URL or bare share ID into workflow JSON, optionally saving it to your account |
+
+**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.
 
 ## Install
 
 Pick your client:
 
 <CardGroup cols={2}>
   <Card title="Claude Code" icon="terminal" href="#claude-code">
-    Install the plugin — connection and commands in one step.
+    Install the plugin. Connection and commands in one step.
   </Card>
   <Card title="Claude Desktop" icon="desktop" href="#claude-desktop">
     Add a custom connector in the app, then sign in.
@@ -60,14 +120,14 @@ The plugin adds these slash commands:
 | --- | --- |
 | `/comfy-cloud:generate-image` | Generate, edit, or modify an image |
 | `/comfy-cloud:generate-video` | Generate, edit, or extend a video |
-| `/comfy-cloud:generate-audio` | Generate audio |
-| `/comfy-cloud:generate-3d` | Generate a 3D model |
+| `/comfy-cloud:generate-audio` | Generate audio, music, or sound effects |
+| `/comfy-cloud:generate-3d` | Generate a 3D model from text or an image |
 | `/comfy-cloud:remove-background` | Remove the background from an image |
-| `/comfy-cloud:upscale-image` | Upscale an image |
-| `/comfy-cloud:search-models` | Search available models |
-| `/comfy-cloud:search-nodes` | Search for nodes |
-| `/comfy-cloud:search-templates` | Find pre-built workflows |
-| `/comfy-cloud:help` | See what you can do |
+| `/comfy-cloud:upscale-image` | Upscale an image to higher resolution |
+| `/comfy-cloud:search-templates` | Find pre-built workflow templates on [comfy.org](https://comfy.org) |
+| `/comfy-cloud:search-models` | Search for available models |
+| `/comfy-cloud:search-nodes` | Search for nodes and get wiring suggestions |
+| `/comfy-cloud:help` | See what you can do with ComfyUI Cloud |
 
 <Accordion title="Prefer just the connection, without the plugin?">
   Add the server directly:
@@ -78,7 +138,7 @@ The plugin adds these slash commands:
 
   Then run `/mcp`, select **comfy-cloud** → **Authenticate**. Add `-s user` to make it available in all your projects.
 
-  This path still gives you slash commands, but in raw MCP form — `/mcp__comfy-cloud__generate-image`, `/mcp__comfy-cloud__search-models`, and so on (the `/mcp__<name>__` prefix uses the name you passed to `claude mcp add`). The plugin above is recommended because it wraps these as the friendlier `/comfy-cloud:*` commands.
+  This path still exposes the same workflows as MCP prompts: `/mcp__comfy-cloud__generate-image`, `/mcp__comfy-cloud__search-models`, and so on (the `/mcp__<name>__` prefix uses the name you passed to `claude mcp add`). The plugin above is recommended because it wraps these as the friendlier `/comfy-cloud:*` commands.
 </Accordion>
 
 ### <span style={{ marginRight: "0.6rem" }}><Icon icon="desktop" size={22} /></span> Claude Desktop
@@ -118,6 +178,23 @@ Claude Desktop adds Comfy Cloud as a **custom connector** through its UI, then r
   </Step>
 </Steps>
 
+Claude Desktop does not support Claude Code slash commands. Instead, open the **prompt picker** for the same workflows:
+
+| Prompt | Description |
+| --- | --- |
+| `generate-image` | Generate an image from a text description |
+| `generate-video` | Generate a video from text or an image |
+| `generate-audio` | Generate audio, music, or sound effects |
+| `generate-3d` | Generate a 3D model from text or an image |
+| `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) |
+| `search-nodes` | Search nodes and get wiring suggestions |
+| `help` | See what you can do with ComfyUI Cloud |
+
+You can also skip prompts and ask in plain language. The MCP tools work the same way.
+
 ### Headless / CI (API key)
 
 Claude Code and Claude Desktop use OAuth, so you do not need an API key. For **headless or CI** setups where no browser is available, authenticate with an API key instead:
@@ -133,12 +210,28 @@ Claude Code and Claude Desktop use OAuth, so you do not need an API key. For **h
   </Step>
 </Steps>
 
+## Outputs and downloads
+
+The MCP server runs in the cloud and **never writes files to your machine**. When a generation completes, your agent calls `get_output`, which returns:
+
+1. A **temporary signed download URL** (valid for a short window).
+2. A ready-to-run **shell command** (`curl` on macOS and Linux, `curl.exe` on Windows).
+
+Your agent should run that command in your shell. The command includes the destination path and filename.
+
+<Warning>
+  Run the returned command **verbatim**. Do not re-encode or edit the signed URL. The signature lives in the query string and breaks if the URL is modified.
+</Warning>
+
+If your MCP client cannot run shell commands (some GUI-only setups), copy the command and run it yourself in a terminal.
+
 ## Related resources
 
 | Resource | What it's for |
 | --- | --- |
 | [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) | Claude Code plugin marketplace and community skill library. The **comfy-cloud** plugin used above is distributed here; browse or contribute additional skills for Comfy workflows. |
 | [Comfy CLI](/agent-tools/comfy-cli) | Command-line tool for local ComfyUI install/launch and for calling hosted partner nodes from scripts or CI (`comfy generate`, in beta). Complements MCP when you need terminal or automation workflows. |
+| [Share a workflow on Comfy Cloud](/cloud/share-workflow) | Share workflows from the Comfy Cloud UI (the MCP `share_workflow` tool does this from an agent session). |
 
 ## Feedback
 
@@ -147,25 +240,44 @@ Comfy Cloud MCP is in public beta. Please try it out and tell us what works and
 - **[Feedback survey](https://links.comfy.org/cloudmcpbeta)**: report bugs, request features, or share general impressions.
 - **Discord**: [#comfy-mcp-and-cli](https://discord.gg/xWJn6nhE3R) on the Comfy Discord for questions and discussion.
 
+## Known limitations
+
+Comfy Cloud MCP is an early release. These limitations are known and being worked on:
+
+**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.
+- **Workflow building depends on agent accuracy.** Complex multi-node workflows may need a retry or refinement.
+
+**File handling**
+
+- **Outputs require a shell download step.** See [Outputs and downloads](#outputs-and-downloads).
+- **Upload size limits** may apply depending on your MCP client. Some clients impose their own limits on file uploads.
+
+**Authentication**
+
+- **OAuth or API key.** Claude Code and Claude Desktop use a one-time browser OAuth flow. Headless clients can pass a Comfy Cloud API key via the `X-API-Key` header instead. A device-code OAuth flow for clients that cannot open a browser is planned.
+
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="Which clients are supported?">
     Claude Code and Claude Desktop today, both signing in with OAuth. Support for more clients is coming.
   </Accordion>
   <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.
+    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="Do the slash commands work in Claude Desktop?">
-    No. The slash commands ship in the Claude Code plugin. Claude Desktop connects to the same MCP server (so the tools work — just ask in plain language), but it doesn't support Claude Code plugins or slash commands.
+    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>
   <Accordion title="I typed /comfy or /cloud and nothing came up.">
     There is no `/comfy` or `/cloud` command. Commands appear under one of two prefixes depending on how you connected:
 
     - **Plugin (recommended):** `/comfy-cloud:generate-image`, `/comfy-cloud:generate-video`, … — type `/comfy-cloud:` to see them all.
     - **Direct connection (no plugin):** `/mcp__comfy-cloud__generate-image`, … — type `/mcp__` to see them.
 
-    Either way you can also just ask in plain language ("generate an image of …") — the MCP tools are model-invoked and don't need a slash command.
+    Either way you can also just ask in plain language ("generate an image of …"). The MCP tools are model-invoked and do not require a slash command.
   </Accordion>
   <Accordion title="The sign-in did not open a browser.">
     In Claude Code, run `/mcp`, select **comfy-cloud**, and choose **Authenticate**. In Claude Desktop, reopen the connector from **Customize → Connectors** and trigger sign-in.

agent-tools/index.mdx

@@ -13,7 +13,7 @@ ComfyUI provides **MCP servers** and **Comfy CLI** so AI agents and developers c
 
 <CardGroup cols={2}>
   <Card title="Comfy Cloud MCP" icon="cloud" href="/agent-tools/cloud">
-    Connect to the hosted MCP server at <code>cloud.comfy.org</code>. Runs workflows on Cloud GPUs, uses pre-installed models, and searches the full template library.
+    Connect to the hosted MCP server at <code>cloud.comfy.org/mcp</code>. Generate images, video, audio, and 3D on Cloud GPUs, search templates/models/nodes, run workflows, and share saved workflows from chat.
   </Card>
   <Card title="Comfy Partner MCP" icon="plug" href="/agent-tools/partner-mcp">
     Run a local MCP server using the Comfy Partner-Node SDK. Provides unified <code>generate_image</code>, <code>generate_video</code>, <code>generate_3d</code>, and more tools across 30+ partner providers.