Skip to content

docs(agent-tools): fix Cursor MCP setup to use API key auth #1221

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 1 commit into from
Jul 3, 2026
+116 −130
Merged

docs(agent-tools): fix Cursor MCP setup to use API key auth #1221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
52 changes: 24 additions & 28 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'?

Any **MCP-compatible client** can connect to the same server URL. **Claude Code**, **Claude Desktop**, **Cursor**, and **Codex** have first-class setup below. **Windsurf**, **Amp**, and other agents use the same URL with OAuth or an API key.

Expand Down Expand Up @@ -145,52 +145,48 @@
</Tab>

<Tab title="Cursor">
Cursor connects to remote MCP servers over HTTP. Add Comfy Cloud in **Cursor Settings → Tools & MCP**, or edit your MCP config file directly.
Cursor connects to remote MCP servers over HTTP. Cursor does **not** support MCP OAuth today. Add Comfy Cloud with a Comfy Cloud API key in your MCP config.

<Steps>
<Step title="Add the server URL">
Create or edit `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for a global setup:
<Step title="Open Cursor Settings">
Click the **Settings** gear in the top-right corner (labeled **1**).

![Cursor — open Settings](/images/agent_tools/cursor_mcp_setup_step1.png)
</Step>
<Step title="Open Tools & MCP">
1. In the sidebar, click **Tools & MCPs** (labeled **2**).
2. Click **+ New MCP Server** (labeled **3**) → **Add a Custom MCP Server**.

![Cursor — Tools & MCPs](/images/agent_tools/cursor_mcp_setup_step2.png)
</Step>
<Step title="Add your API key">
Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project). Set the server URL and pass your Comfy Cloud API key in the `X-API-Key` header. Create a key at [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) (starts with `comfyui-`):

```json
{
"mcpServers": {
"comfy-cloud": {
"url": "https://cloud.comfy.org/mcp"
"url": "https://cloud.comfy.org/mcp",
"headers": {
"X-API-Key": "${env:COMFY_API_KEY}"
}
}
}
}
```
</Step>
<Step title="Sign in">
Open **Cursor Settings → Tools & MCP**. Select **comfy-cloud** and click **Connect** to sign in through your browser (OAuth). Tokens refresh automatically.

Set `COMFY_API_KEY` in your shell or system environment. Prefer `${env:COMFY_API_KEY}` over hardcoding the key in a file you might commit to git.

![Cursor — mcp.json with API key](/images/agent_tools/cursor_mcp_setup_step3.png)
Comment on lines +148 to +180

@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.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

Does Cursor support OAuth for remote MCP servers as of mid-2026, and does it work with static/pre-shared Client ID flows for third-party MCP providers?

💡 Result:

As of July 2026, Cursor provides native support for OAuth for remote Model Context Protocol (MCP) servers [1][2]. For MCP servers requiring OAuth, you can configure them in your mcp.json file [1][3]. Cursor supports the use of static OAuth client credentials to bypass or supplement dynamic flows [1][3]. Key details regarding this support include: Static/Pre-shared Client ID Flows: Cursor allows you to provide a static CLIENT_ID and optional CLIENT_SECRET directly within the auth object of an MCP server entry in mcp.json [1][3]. This is intended for providers that supply fixed credentials, require specific redirect URL whitelisting, or do not support OAuth 2.0 Dynamic Client Registration (DCR) [1][3]. Technical Considerations and Known Limitations: 1. Authorization Code Flow Enforcement: Cursor's MCP client is primarily designed to use the authorization code (redirect-based) flow [4][5]. Even when a CLIENT_SECRET is provided in the configuration, the client may still initiate a redirect-based flow rather than utilizing a client credentials grant (RFC 6749 §4.4) to obtain tokens server-to-server [4][5]. 2. Callback Handling: Cursor utilizes fixed redirect URLs, specifically cursor://anysphere.cursor-mcp/oauth/callback [1][3]. You must register this URL with your OAuth provider [1][3]. Some users have reported issues where the internal callback handler may occasionally fail to respond correctly (e.g., ERR_EMPTY_RESPONSE) or where the "Connect" button fails to trigger the browser flow [6][2]. 3. Fixed Redirection: Because Cursor uses fixed, random-port based redirection for OAuth callbacks, it may experience difficulties with strict Identity Providers (IdPs) like Okta, Entra, or Cognito that require exact, pre-registered redirect URIs, whereas it typically works seamlessly with providers like Keycloak that allow wildcard redirects [7]. For configuration, you can add an auth block to your mcp.json as follows: { "mcpServers": { "your-server-name": { "url": "https://api.example.com/mcp", "auth": { "CLIENT_ID": "your-oauth-client-id", "CLIENT_SECRET": "your-client-secret", "scopes": ["read", "write"] } } } } [1][3]

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the target doc and nearby context
git ls-files agent-tools/cloud.mdx
wc -l agent-tools/cloud.mdx
sed -n '140,190p' agent-tools/cloud.mdx

# Look for any other Cursor/MCP mentions in the repo
rg -n "Cursor|MCP OAuth|mcp.json|X-API-Key|COMFY_API_KEY" -S .

Repository: Comfy-Org/docs

Length of output: 38197

Update the Cursor setup copy to match current MCP OAuth support. Cursor now supports OAuth for remote MCP servers, including static client ID/secret flows, so this section should only fall back to an API key if Comfy Cloud has a specific incompatibility. If the API-key example stays, avoid ${env:COMFY_API_KEY} in headers unless Cursor expands that field for remote HTTP configs.

🤖 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` around lines 148 - 180, The Cursor MCP setup copy is
outdated and currently says Cursor does not support MCP OAuth, which conflicts
with current support for remote MCP OAuth and static client ID/secret flows.
Update the guidance in the Comfy Cloud setup section to describe OAuth as the
default path in Cursor, and only mention the API-key approach as a fallback if
Comfy Cloud specifically requires it. In the `Steps` content and the `mcp.json`
example, revise the `X-API-Key` guidance and avoid using `${env:COMFY_API_KEY}`
in `headers` unless that remote HTTP configuration is actually supported.

</Step>
<Step title="Start generating">
Ask in plain language ("generate an image of a cat astronaut", "find a Wan 2.2 video template"). Cursor invokes the MCP tools on your behalf.
</Step>
</Steps>

<Accordion title="API key instead of OAuth (headless or CI)">
When no browser is available, pass a Comfy Cloud API key in the `X-API-Key` header. Create one at [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) (starts with `comfyui-`):

```json
{
"mcpServers": {
"comfy-cloud": {
"url": "https://cloud.comfy.org/mcp",
"headers": {
"X-API-Key": "${env:COMFY_API_KEY}"
}
}
}
}
```

Set `COMFY_API_KEY` in your shell or system environment. Do not commit the key to version control.
</Accordion>
</Tab>

<Tab title="Codex">
[Codex](https://developers.openai.com/codex/cli) connects to Comfy Cloud over Streamable HTTP. Add the server in Settings, then sign in with OAuth.

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

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L189 

Did you really mean 'Streamable'?

<video
controls
Expand Down Expand Up @@ -315,7 +311,7 @@
Typical flow:

1. **Discover** what is available (`search_templates`, `search_models`, `search_nodes`, or `cql` for graph-style questions).
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 314 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L314 

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 @@ -332,10 +328,10 @@
| `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 331 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L331 

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 334 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L334 

Did you really mean 'cfg'?

### Generation

Expand Down Expand Up @@ -393,7 +389,7 @@
| `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 392 in agent-tools/cloud.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

agent-tools/cloud.mdx#L392 

Did you really mean 'anonymized'?

## Credits and spending

Expand Down Expand Up @@ -451,7 +447,7 @@

**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.
- **OAuth or API key.** Claude Code and Claude Desktop use a one-time browser OAuth flow. **Cursor** requires a Comfy Cloud API key in your MCP config (no OAuth). Other 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

Expand All @@ -460,7 +456,7 @@
Any MCP-compatible client that supports remote HTTP transport can connect to `https://cloud.comfy.org/mcp`. We document first-class setup for **Claude Code**, **Claude Desktop**, **Cursor**, and **Codex**. **Windsurf**, **Amp**, **OpenClaw**, and other agents follow the same URL with OAuth or an API key. See [Install Comfy Cloud MCP](#install-comfy-cloud-mcp).
</Accordion>
<Accordion title="Do I need an API key?">
Not for interactive clients that support OAuth (Claude Code, Claude Desktop, Cursor, Codex, and others). An API key is only needed for headless or CI setups with no browser. See the **Other clients** tab under [Install Comfy Cloud MCP](#install-comfy-cloud-mcp).
Not for interactive clients that support OAuth (Claude Code, Claude Desktop, Codex, and others). **Cursor** requires a Comfy Cloud API key in your MCP config. An API key is also needed for other headless or CI setups with no browser. See the **Cursor** tab or **Other clients** tab under [Install Comfy Cloud MCP](#install-comfy-cloud-mcp).
</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).
Expand Down
Binary file added images/agent_tools/cursor_mcp_setup_step1.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/agent_tools/cursor_mcp_setup_step2.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/agent_tools/cursor_mcp_setup_step3.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
68 changes: 32 additions & 36 deletions ja/agent-tools/cloud.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,22 @@ title: "Comfy Cloud MCP"
sidebarTitle: "Cloud MCP"
description: "Claude Code、Claude Desktop、Cursor、Codex、またはMCP互換エージェントからComfy Cloud MCPに接続: 画像・ビデオ・オーディオ・3Dの生成、モデルとノードの検索、ワークフローの実行。"
icon: "cloud"
translationSourceHash: 2c8d585c
translationSourceHash: 01763e3c
translationFrom: agent-tools/cloud.mdx
translationBlockHashes:
"_intro": b1c56a40
"Overview": 4b68a7b5
"Install Comfy Cloud MCP": b6975c91
"Install Comfy Cloud MCP": ca5e817e
"What your agent can do": 2c2a22e6
"MCP tools": a9211dee
"Credits and spending": 20e94ef0
"Outputs and downloads": a2c8c12f
"Related resources": 58e75560
"Feedback": 6872768e
"Known limitations": 52477743
"FAQ": 4e76854d
"Known limitations": 2f9e13ba
"FAQ": 920ab7b8
---

import CloudFeature from '/snippets/ja/cloud-feature.mdx'

<CloudFeature/>
Expand Down Expand Up @@ -160,48 +161,44 @@ https://cloud.comfy.org/mcp
</Tab>

<Tab title="Cursor">
CursorはリモートMCPサーバーにHTTPで接続します。**Cursor Settings → Tools & MCP**でComfy Cloudを追加するか、MCP設定ファイルを直接編集します。
CursorはリモートMCPサーバーにHTTPで接続します。Cursorは現在MCP OAuthをサポートしていません。MCP設定にComfy Cloud APIキーを指定してComfy Cloudを追加します。

<Steps>
<Step title="サーバーURLを追加">
プロジェクト内に`.cursor/mcp.json`を作成または編集するか、グローバル設定として`~/.cursor/mcp.json`を作成します：
<Step title="Cursor設定を開く">
右上隅の**設定**歯車アイコン（ラベル**1**）をクリックします。

![Cursor — 設定を開く](/images/agent_tools/cursor_mcp_setup_step1.png)
</Step>
<Step title="Tools & MCPを開く">
1. サイドバーで**Tools & MCPs**（ラベル**2**）をクリックします。
2. **+ New MCP Server**（ラベル**3**）→ **Add a Custom MCP Server**をクリックします。

![Cursor — Tools & MCPs](/images/agent_tools/cursor_mcp_setup_step2.png)
</Step>
<Step title="APIキーを追加">
`~/.cursor/mcp.json`（グローバル）または `.cursor/mcp.json`（プロジェクト）を編集します。サーバーURLを設定し、`X-API-Key`ヘッダーでComfy Cloud APIキーを渡します。[platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)でキーを作成します（`comfyui-`で始まります）：

```json
{
"mcpServers": {
"comfy-cloud": {
"url": "https://cloud.comfy.org/mcp"
"url": "https://cloud.comfy.org/mcp",
"headers": {
"X-API-Key": "${env:COMFY_API_KEY}"
}
}
}
}
```
</Step>
<Step title="ログイン">
**Cursor Settings → Tools & MCP**を開きます。**comfy-cloud**を選択し、**Connect**をクリックしてブラウザからログインします（OAuth）。トークンは自動的に更新されます。

シェルまたはシステム環境に`COMFY_API_KEY`を設定します。キーをgitにコミットする可能性のあるファイルに直接記述するよりも、`${env:COMFY_API_KEY}`を推奨します。

![Cursor — APIキーを含むmcp.json](/images/agent_tools/cursor_mcp_setup_step3.png)
</Step>
<Step title="生成を開始">
平易な言葉で質問します（「猫の宇宙飛行士の画像を生成して」「Wan 2.2の動画テンプレートを探して」）。Cursorがあなたに代わってMCPツールを呼び出します。
</Step>
</Steps>

<Accordion title="OAuthの代わりにAPIキー（ヘッドレス/CI用）">
ブラウザが利用できない場合は、`X-API-Key`ヘッダーにComfy Cloud APIキーを渡します。[platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)でキーを作成します（`comfyui-`で始まります）：

```json
{
"mcpServers": {
"comfy-cloud": {
"url": "https://cloud.comfy.org/mcp",
"headers": {
"X-API-Key": "${env:COMFY_API_KEY}"
}
}
}
}
```

シェルまたはシステム環境に`COMFY_API_KEY`を設定します。キーをバージョン管理にコミットしないでください。
</Accordion>
</Tab>

<Tab title="Codex">
Expand Down Expand Up @@ -288,7 +285,7 @@ https://cloud.comfy.org/mcp
}
```

**Windsurf**は`url`の代わりに`serverUrl`を使用します。**Amp**は**Settings → MCP Servers**または`~/.config/amp/settings.json`で同じ`mcpServers`構造を使用します。
**Windsurf**は`url`の代わりに`serverUrl`を使用します。**Amp**は**設定 → MCPサーバー**または`~/.config/amp/settings.json`で同じ`mcpServers`構造を使用します。
</Step>
<Step title="認証">
クライアントがMCP OAuthをサポートしている場合は、ブラウザからログインします。それ以外の場合は、APIキーヘッダーを追加します（下記参照）。
Expand Down Expand Up @@ -320,7 +317,6 @@ https://cloud.comfy.org/mcp
```

設定ファイルにキーを直接記述するのではなく、`${env:COMFY_API_KEY}`またはクライアントのシークレット補間を使用することをお勧めします（gitにコミットする設定ファイルで）。

</Tab>
</Tabs>

Expand Down Expand Up @@ -468,7 +464,7 @@ Comfy Cloud MCP は初期リリースです。以下の制限事項は既知で

**認証**

- **OAuth または API キー。** Claude Code および Claude Desktop は、1回限りのブラウザ OAuth フローを使用します。ヘッドレスクライアントは、代わりに `X-API-Key` ヘッダー経由で Comfy Cloud API キーを渡すことができます。ブラウザを開けないクライアント向けのデバイスコード OAuth フローが計画されています。
- **OAuth または API キー。** Claude Code および Claude Desktop は、1回限りのブラウザ OAuth フローを使用します。**Cursor** は、MCP 設定で Comfy Cloud API キーを必要とします（OAuth なし）。その他のヘッドレスクライアントは、代わりに `X-API-Key` ヘッダー経由で Comfy Cloud API キーを渡すことができます。ブラウザを開けないクライアント向けのデバイスコード OAuth フローが計画されています。

## FAQ

Expand All @@ -477,7 +473,7 @@ Comfy Cloud MCP は初期リリースです。以下の制限事項は既知で
MCP に対応し、リモート HTTP トランスポートをサポートしているクライアントはすべて `https://cloud.comfy.org/mcp` に接続できます。**Claude Code**、**Claude Desktop**、**Cursor**、**Codex** のセットアップ方法を文書化しています。**Windsurf**、**Amp**、**OpenClaw** などの他のエージェントも、同じ URL に OAuth または APIキーで接続します。詳細は [Comfy Cloud MCP のインストール](#install-comfy-cloud-mcp) を参照してください。
</Accordion>
<Accordion title="APIキーは必要ですか？">
OAuth に対応した対話型クライアント（Claude Code、Claude Desktop、Cursor、Codex など）では不要です。APIキーは、ブラウザがないヘッドレスまたは CI 環境でのみ必要です。詳細は [Comfy Cloud MCP のインストール](#install-comfy-cloud-mcp) の **その他のクライアント** タブを参照してください。
OAuth に対応した対話型クライアント（Claude Code、Claude Desktop、Codex など）では不要です。**Cursor** では、MCP 設定に Comfy Cloud の APIキーが必要です。APIキーは、ブラウザのないヘッドレス環境や CI 環境でも必要です。詳細は [Comfy Cloud MCP のインストール](#install-comfy-cloud-mcp) の **Cursor** タブまたは **その他のクライアント** タブを参照してください。
</Accordion>
<Accordion title="なぜエージェントは生成前に確認を求めるのですか？">
有料の生成は支出ゲートの対象です：実行が Comfy Cloud のクレジットを消費する場合（パートナーモデル、または有料 API ノードを含むワークフロー/テンプレート）、サーバーは実行前に明示的な同意を必要とします。詳細は [クレジットと支出](#credits-and-spending) を参照してください。
Expand All @@ -488,8 +484,8 @@ Comfy Cloud MCP は初期リリースです。以下の制限事項は既知で
<Accordion title="/comfy または /cloud と入力したけど何も表示されません。">
`/comfy` や `/cloud` というコマンドはありません。コマンドは、接続方法に応じて2つのプレフィックスのいずれかに表示されます。

- **プラグイン（推奨）：** `/comfy-cloud:generate-image`、`/comfy-cloud:generate-video` ... — すべて表示するには `/comfy-cloud:` と入力してください。
- **直接接続（プラグインなし）：** `/mcp__comfy-cloud__generate-image` ... — 表示するには `/mcp__` と入力してください。
- **プラグイン（推奨）：** `/comfy-cloud:generate-image`、`/comfy-cloud:generate-video` … — すべて表示するには `/comfy-cloud:` と入力してください。
- **直接接続（プラグインなし）：** `/mcp__comfy-cloud__generate-image` … — 表示するには `/mcp__` と入力してください。

どちらの場合でも、プレーン言語で質問するだけでも構いません（「...の画像を生成して」など）。MCP ツールはモデルによって呼び出されるため、スラッシュコマンドは必要ありません。
</Accordion>
Expand Down
Loading
Loading