docs(agent-tools): fix Cursor MCP setup to use API key auth#1221
Conversation
Replace incorrect OAuth Connect steps with screenshot-guided API key setup in mcp.json, and sync ja/zh/ko translations plus FAQ auth notes.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
📝 WalkthroughWalkthroughDocumentation across English, Japanese, Korean, and Chinese versions of ChangesCloud MCP authentication documentation
No sequence diagram needed here — this is pure prose fixin', not a flow worth mixin'. Possibly related PRs
With OAuth doors now closed up tight, 🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with 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.
Inline comments:
In `@agent-tools/cloud.mdx`:
- Around line 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: ef597658-93c1-42b5-bcb7-1341e9673a8b
⛔ Files ignored due to path filters (3)
images/agent_tools/cursor_mcp_setup_step1.pngis excluded by!**/*.pngimages/agent_tools/cursor_mcp_setup_step2.pngis excluded by!**/*.pngimages/agent_tools/cursor_mcp_setup_step3.pngis excluded by!**/*.png
📒 Files selected for processing (4)
agent-tools/cloud.mdxja/agent-tools/cloud.mdxko/agent-tools/cloud.mdxzh/agent-tools/cloud.mdx
| 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**). | ||
|
|
||
|  | ||
| </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**. | ||
|
|
||
|  | ||
| </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. | ||
|
|
||
|  |
There was a problem hiding this comment.
🎯 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:
- 1: https://cursor.com/docs/mcp
- 2: https://forum.cursor.com/t/mcp-oauth-callback-returns-err-empty-response-localhost-callback-handler-sends-no-data/154519
- 3: https://cursor.com/docs/mcp.md
- 4: https://forum.cursor.com/t/mcp-oauth-client-credentials-grant-ignored-when-client-secret-is-present/152307/1
- 5: https://forum.cursor.com/t/mcp-oauth-client-credentials-grant-ignored-when-client-secret-is-present/152307
- 6: https://forum.cursor.com/t/remote-mcp-server-connect-button-produces-zero-network-requests-oauth-flow-never-starts/150962/1
- 7: https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/connection-methods/client-id.md
🏁 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.
1 participant
Summary
mcp.jsoninstead of Connect/sign-in.Test plan
agent-tools/cloudand verify the Cursor tab shows 4 steps and all 3 screenshots render.