RunComfy API Docs

Connect the RunComfy MCP server to your AI assistant and make your first tool call.

1. Get your API token

Copy your API token from your Profile page.

Copy the whole token. A truncated token is the most common cause of a 401 — the server can’t tell a partial token from a wrong one.

2. Connect your client

Run this in your terminal, replacing YOUR_RUNCOMFY_TOKEN:

claude mcp add --transport http runcomfy https://mcp.runcomfy.com/mcp --header "Authorization: Bearer YOUR_RUNCOMFY_TOKEN"

Then confirm it worked:

claude mcp list

You should see runcomfy: ... - ✓ Connected.

The transport is http, not streamable-http. Claude Code names the Streamable HTTP transport http, and rejects any other value before it ever contacts the server. Flags also need two dashes — -transport and -header are not valid.

Want it in every project? By default the server is added only to the current directory. Add --scope user to make it available everywhere:

claude mcp add --scope user --transport http runcomfy https://mcp.runcomfy.com/mcp --header "Authorization: Bearer YOUR_RUNCOMFY_TOKEN"

Prefer not to keep a token in your config? Omit the header and sign in through your browser instead:

claude mcp add --transport http runcomfy https://mcp.runcomfy.com/mcp

Then run /mcp inside Claude Code, choose runcomfy, and select Authenticate. A RunComfy page opens where you paste your token once.

No token in a config file — Claude.ai signs in through your browser.

Go to Settings → Connectors → Add custom connector.
Enter the URL https://mcp.runcomfy.com/mcp.
Select Connect.
A RunComfy consent page opens. Paste an API token from your Profile and select Authorize.

Your token is verified by RunComfy and stored encrypted in the authorization grant. Claude never receives it.To disconnect, remove the connector in Claude, or regenerate the token in your RunComfy Profile.

Using the Mac app or iPhone? You can’t add a connector there. RunComfy will appear in your settings once added, but there’s no way to switch it on — Developer mode doesn’t exist on those platforms. Add it at chatgpt.com or in the Windows app instead.

ChatGPT allows no custom headers, so it signs in through your browser rather than taking an API token in a config file. Adding any custom MCP server requires Developer mode, on a Plus, Pro, Business, Enterprise or Edu plan.At chatgpt.com or in the Windows app:

Settings → Security and login → turn on Developer mode
Plugins → + → create an app for https://mcp.runcomfy.com/mcp, authentication OAuth
Paste your Profile token on the RunComfy page that opens

Where it works once added:

	Add it	Use it
chatgpt.com	Yes	Yes
Windows app	Yes	Yes
Mac app	No	No
iPhone	No	No

Following an older guide? OpenAI renamed Connectors to Plugins in July 2026 and moved Developer mode out of Connectors → Advanced into Settings → Security and login.

RunComfy’s tools manage deployments and run inference — they aren’t the search and fetch pair ChatGPT’s deep research feature requires, so use RunComfy from a normal conversation.If these limits are a problem, every other client on this page takes an API token directly and works on any platform.

Add this to .cursor/mcp.json (create the file if it doesn’t exist):

{
  "mcpServers": {
    "runcomfy": {
      "url": "https://mcp.runcomfy.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RUNCOMFY_TOKEN"
      }
    }
  }
}

For a global setup, use ~/.cursor/mcp.json instead of the project file.

Add this to .vscode/mcp.json:

{
  "servers": {
    "runcomfy": {
      "type": "http",
      "url": "https://mcp.runcomfy.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RUNCOMFY_TOKEN"
      }
    }
  }
}

Go to Windsurf Settings → MCP and add:

{
  "mcpServers": {
    "runcomfy": {
      "serverUrl": "https://mcp.runcomfy.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RUNCOMFY_TOKEN"
      }
    }
  }
}

Hermes reads its MCP servers from ~/.hermes/config.yaml. Add RunComfy under mcp_servers:

mcp_servers:
  runcomfy:
    url: "https://mcp.runcomfy.com/mcp"
    headers:
      Authorization: "Bearer YOUR_RUNCOMFY_TOKEN"
    enabled: true

A url with no command is a remote server, so Hermes uses Streamable HTTP — there is no separate transport field to set.Then check it connects:

hermes mcp test runcomfy

You should see ✓ Connected and ✓ Tools discovered: 10. Expect the connect to take 5–8 seconds — the server enumerates tools, resources and prompts on first contact.Inside a running session, reload the config without restarting:

/reload-mcp

Keep the token out of the config file. Put it in ~/.hermes/.env and reference it instead:

mcp_servers:
  runcomfy:
    url: "https://mcp.runcomfy.com/mcp"
    headers:
      Authorization: "Bearer ${env:RUNCOMFY_API_TOKEN}"

Hermes prints RUNCOMFY_API_TOKEN is not set (check ~/.hermes/.env); keeping the literal placeholder on every command even when the variable is set and resolving correctly. It’s a cosmetic bug — if hermes mcp test runcomfy reports ✓ Connected, the token resolved. To confirm for yourself, put a wrong value in .env and watch the same command fail.

Prefer browser sign-in? Hermes registers a loopback callback, so it can use OAuth instead of a token in the file:

mcp_servers:
  runcomfy:
    url: "https://mcp.runcomfy.com/mcp"
    auth: oauth

Then run hermes mcp login runcomfy and paste your token once on the RunComfy page that opens. Hermes stores the resulting grant in ~/.hermes/mcp-tokens/runcomfy.json and refreshes it for you.

If you’d rather Hermes only sees a few of the tools, narrow the list with an allowlist rather than an allow-everything default:

mcp_servers:
  runcomfy:
    url: "https://mcp.runcomfy.com/mcp"
    headers:
      Authorization: "Bearer ${env:RUNCOMFY_API_TOKEN}"
    tools:
      include: [list_deployments, get_deployment, submit_request, get_request_status, get_request_result]

hermes mcp list then shows 5 selected instead of all. Note that hermes mcp test still lists everything the server offers — it reports what’s discoverable, not what’s exposed to the agent.

Add RunComfy in one command:

openclaw mcp set runcomfy '{"url":"https://mcp.runcomfy.com/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer YOUR_RUNCOMFY_TOKEN"}}'

mcp set writes the entry without connecting, so confirm it works:

openclaw mcp probe runcomfy

You should see runcomfy: 10 tools, resources, prompts.The entry is written to mcp.servers.runcomfy in ~/.openclaw/openclaw.json, so you can also edit it by hand:

{
  "mcp": {
    "servers": {
      "runcomfy": {
        "url": "https://mcp.runcomfy.com/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer YOUR_RUNCOMFY_TOKEN"
        }
      }
    }
  }
}

Prefer browser sign-in? Drop the header and let OpenClaw run the OAuth flow — it registers a loopback callback, so no allowlisting is needed:

openclaw mcp set runcomfy '{"url":"https://mcp.runcomfy.com/mcp","transport":"streamable-http","auth":"oauth"}'

Paste your Profile token once on the RunComfy page that opens.Prefer flags to JSON? openclaw mcp add takes the same settings, but note the header is key=value — not the Key: value form other clients use — and that add probes the server before saving:

openclaw mcp add runcomfy --url https://mcp.runcomfy.com/mcp --transport streamable-http --header "Authorization=Bearer YOUR_RUNCOMFY_TOKEN" --timeout 10

The --timeout 10 is required in practice. add’s built-in probe gives up after about 5 seconds, and RunComfy’s first handshake takes longer than that, so the command fails with MCP error -32001: Request timed out and saves nothing. mcp set doesn’t probe, so it never hits this.

Timeouts can be set two ways, and both are stored as written: the flags above take seconds (connectTimeout, timeout), while mcp set JSON takes milliseconds (connectionTimeoutMs, requestTimeoutMs). openclaw mcp status --verbose reports the resolved values in ms, so use it to check what actually applied. Defaults are connect=30000ms request=60000ms.Useful checks: openclaw mcp list for configured servers, openclaw mcp status --verbose for transport and timeouts without connecting, and openclaw mcp doctor runcomfy --probe when something’s wrong.

openclaw mcp show runcomfy --json prints your token in full — it is not redacted. Don’t paste that output into a bug report. mcp list and mcp status don’t print headers at all and are safe to share.

Any client that speaks Streamable HTTP can connect:

Setting	Value
Server URL	`https://mcp.runcomfy.com/mcp`
Transport	Streamable HTTP
Authentication	`Authorization: Bearer YOUR_RUNCOMFY_TOKEN` on every request

Clients that run a browser OAuth flow can instead connect with no token in the config, as long as they register a loopback redirect URI (http://localhost:PORT/...). Hosted clients need their callback allowlisted — currently Claude.ai and ChatGPT. See Which sign-in method should I use?.You can check the endpoint is reachable before configuring anything:

curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST https://mcp.runcomfy.com/mcp \
  -H "Authorization: Bearer YOUR_RUNCOMFY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

200 means your token works. 401 means it was rejected — the response body says why.

3. Verify the connection

Ask your assistant:

“List my RunComfy deployments”

It will call list_deployments. If you get back deployment names and IDs, you’re connected.

4. Your first inference

With a deployment available, try:

“Run my [deployment name] with the prompt: a futuristic cityscape at sunset”

The assistant will:

Call get_deployment to inspect the workflow’s node IDs
Call submit_request with the appropriate overrides
Call get_request_status to poll progress
Call get_request_result to return the output URL

Troubleshooting

401 — RunComfy rejected this API token

The token reached the server and RunComfy did not recognize it. Almost always one of:

Truncated on copy. Re-copy the whole token from your Profile.
Regenerated. Generating a new token invalidates the old one everywhere. Update every client that used it.
Extra characters. Quotes, a trailing space, or a line break pasted along with the token.

Check the token on its own before blaming the client:

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer YOUR_RUNCOMFY_TOKEN" \
  https://api.runcomfy.net/prod/v2/deployments

200 means the token is good and the problem is in your client config. 401 means the token itself is bad.

401 with no explanation in the body

No Authorization header arrived. The header has to be a single argument, so keep it quoted:

--header "Authorization: Bearer YOUR_RUNCOMFY_TOKEN"

Without the quotes the shell splits it at the space and the header is dropped.

Claude Code rejects the command before connecting

If you see an error about the transport, or the flags aren’t recognized, check the command shape:

Transport is http — not streamable-http.
Flags take two dashes — --transport, --header, not -transport, -header.
The order is claude mcp add [flags] NAME URL.

The working command is:

claude mcp add --transport http runcomfy https://mcp.runcomfy.com/mcp --header "Authorization: Bearer YOUR_RUNCOMFY_TOKEN"

The server was there yesterday and is gone now

claude mcp add defaults to local scope — the current directory only. If you moved to another project, re-add it with --scope user so it follows you everywhere.

claude mcp add --scope user --transport http runcomfy https://mcp.runcomfy.com/mcp --header "Authorization: Bearer YOUR_RUNCOMFY_TOKEN"

Hermes doesn't see the tools after editing config.yaml

Hermes loads ~/.hermes/config.yaml at startup. After editing it, run /reload-mcp in the session, or restart the gateway.If it reloads but the tools still aren’t there, check for a tools.include allowlist on the entry — anything not listed is hidden, including tools added since you wrote the list. hermes mcp list shows N selected when a filter is active and all when it isn’t.Ignore the RUNCOMFY_API_TOKEN is not set warning if you’re using ${env:...} — it prints even when the variable resolves fine.

OpenClaw can't reach the server

Probe it — this connects for real and reports what came back:

openclaw mcp doctor runcomfy --probe

If the failure is MCP error -32001: Request timed out within a few seconds of running openclaw mcp add, it’s the probe deadline, not the network — re-run with --timeout 10, or use openclaw mcp set, which saves without probing.Otherwise check two things in the entry:

transport is streamable-http. RunComfy does not serve the older SSE transport.
url is exactly https://mcp.runcomfy.com/mcp, with no trailing slash.

openclaw mcp show runcomfy --json

That output contains your token in the clear — redact it before sharing. To test the token on its own, use the curl check in 401 — RunComfy rejected this API token above.

503 with a Retry-After header

RunComfy’s API couldn’t be reached to verify your token. This is temporary — retry after the number of seconds in the Retry-After header.

429 — too many requests

More than 600 token-authenticated requests in a minute from one IP address. Normal assistant use never reaches this. Wait a minute and retry.

Still stuck? Email hi@runcomfy.com with the exact error message and the client you’re using.

Next steps

Tool Reference — Detailed parameters and examples for all 31 tools
FAQ — Common questions
Serverless API docs — Understand deployments, workflows, and the async queue

Getting Started

Reference

Quickstart

1. Get your API token

2. Connect your client

3. Verify the connection

4. Your first inference

Troubleshooting

Next steps

​1. Get your API token

​2. Connect your client

​3. Verify the connection

​4. Your first inference

​Troubleshooting

​Next steps

1. Get your API token

2. Connect your client

3. Verify the connection

4. Your first inference

Troubleshooting

Next steps