arcum42-ComfyUI_SageUtils/ref_docs/upstream_docs/cloud/mcp-server.md

title, description

title	description
ComfyUI MCP Server	Connect AI agents to Comfy Cloud for image generation via the Model Context Protocol (MCP)

import GetApiKey from '/snippets/get-api-key.mdx'

**Research Preview:** The ComfyUI MCP Server is currently in limited early access. Features, tools, and behavior may change as the project evolves. Interested? [Sign up for the waitlist](https://form.typeform.com/to/hHmvw1UH).

The ComfyUI MCP Server connects AI assistants — including Claude Desktop, Claude Code, and Cursor — to Comfy Cloud via the Model Context Protocol (MCP). It lets AI agents generate images, search models/nodes/templates, and run full ComfyUI workflows on cloud GPUs, with no local GPU required.

Quick Start

1. Get Your API Key

2. Connect Your Client

The ComfyUI MCP Server is hosted at https://cloud.comfy.org/mcp. No local installation or Node.js required — just point your MCP client at the server URL with your API key.

```bash claude mcp add comfyui-cloud \ --transport http \ https://cloud.comfy.org/mcp \ -H "X-API-Key: your-api-key-here" ``` Add the following to your Claude Desktop config file:

| OS | Config path |
|:---|:------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "comfyui-cloud": {
      "url": "https://cloud.comfy.org/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}
```

Add the following to your Cursor MCP config (`.cursor/mcp.json` in your project or global config):

```json
{
  "mcpServers": {
    "comfyui-cloud": {
      "url": "https://cloud.comfy.org/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}
```

See [Cursor's MCP documentation](https://docs.cursor.com/context/model-context-protocol) for more details.

After adding the server, restart your MCP client to pick up the new configuration.

---

Available Tools

Discovery

Tool	Description
search_templates	Search pre-built workflow templates from comfy.org by text, tag, media type, or model
search_models	Search model catalog by text, type, base model, or source
search_nodes	Search available nodes by text, category, or input/output types

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 (e.g. 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 the output of one 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

The server checks for a matching pre-built template before building a workflow from scratch, leading to better results and faster generation.

---

How It Works

┌──────────────┐    HTTPS/MCP    ┌─────────────────────────────────────────────┐
│  AI Agent    │◄───────────────►│            Comfy Cloud                      │
│  (Claude,    │   X-API-Key     │  cloud.comfy.org/mcp → Workflow Execution   │
│   Cursor)    │                 │                        on Cloud GPUs        │
└──────────────┘                 └─────────────────────────────────────────────┘

Your AI agent connects directly to the hosted MCP server at cloud.comfy.org/mcp. The server translates MCP tool calls into workflow executions on Comfy Cloud GPUs — no local server or GPU required.

The AI agent uses the discovery tools to find templates and nodes, then constructs the ComfyUI API-format workflow JSON, submits it, and returns the results — just describe what you want in natural language.

---

Example Prompts

After installing, try these prompts in your AI assistant:

Generate an image of a cat astronaut floating in space, cartoon style

Find me workflow templates for text-to-video generation

Search for SDXL checkpoint models and tell me which ones are available

Generate a fantasy landscape with mountains and a glowing river at sunset

What nodes are available for image upscaling?

The agent will search for a matching template, build the ComfyUI workflow, submit it to Comfy Cloud, and return the generated image directly in the conversation.

---

Output Handling

• Images are displayed inline in the conversation (Claude Code) or in the artifact side panel (Claude Desktop)
• Video and audio outputs are returned as downloadable links
• Animated images (GIF, WebP) are saved but not previewed inline to preserve animation
• Inline image previews are resized to 1024px for efficient display; full-resolution outputs are always available via the get_output tool

---

Known Limitations

This is an early release. The following limitations are known and being actively worked on.

Workflows

• Cannot run saved workflows by ID. You can browse and inspect saved workflows (list_saved_workflows, get_saved_workflow), but not execute them directly. Saved workflows use the ComfyUI graph format, which requires conversion to API format. The AI agent must reconstruct the workflow from scratch.
• Generated assets have no workflow metadata. Images created via the MCP server don't include workflow JSON in their metadata, so they won't show the workflow when opened in ComfyUI.
• Workflow accuracy depends on the AI. The agent constructs ComfyUI workflows from natural language. Complex multi-node workflows or unusual node configurations may require iteration.

File Handling

• Upload size limits may apply depending on your MCP client.
• Image previews are resized. Inline previews are limited to 1024px (JPEG). Full-resolution files are saved to disk.

Authentication

• API key only. Authentication requires a Comfy Cloud API key passed via the X-API-Key header. Browser-based OAuth is not yet available.

Client-Specific

• Claude Desktop — Generated images appear in the artifact side panel via HTML, not as native image artifacts.

---

Troubleshooting

MCP server not showing up

Restart your MCP client (close and reopen Claude Code, Claude Desktop, or Cursor). MCP servers are loaded at startup. Double-check that the server URL is exactly https://cloud.comfy.org/mcp in your config.

API key errors

Verify your API key is valid at platform.comfy.org/profile/api-keys. Make sure the key is passed in the X-API-Key header (not as a Bearer token). Generate a new key if needed and update your client config.

Connection errors

If the MCP client can't reach the server, check that:

1. You have an active internet connection
2. Your firewall or proxy isn't blocking cloud.comfy.org
3. You have an active Comfy Cloud subscription