The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Runcomfy MCP listing page.
MCP server for the RunComfy platform — Serverless API (ComfyUI), Model API, and Trainer API. Manage deployments, run hosted models, train LoRAs, and retrieve results from AI assistants like Claude, Cursor, and Windsurf.
Endpoint: https://mcp.runcomfy.com/mcp
Docs: docs.runcomfy.com/mcp
31 tools mirroring the RunComfy docs 1:1, across three products plus your account balance.
Docs: docs.runcomfy.com/serverless
| Category | Tools |
|---|---|
| Deployment management | list_deployments, get_deployment, create_deployment, update_deployment, delete_deployment |
| Inference | submit_request, get_request_status, get_request_result, cancel_request |
| Advanced | call_instance_proxy |
Docs: docs.runcomfy.com/model-apis
| Category | Tools |
|---|---|
| Catalog | list_models, get_model, list_model_categories |
| Inference | run_model, get_model_request_status, get_model_request_result, cancel_model_request |
No deployment to manage and per-request billing. list_models browses the
catalog by keyword or capability (category=image-to-video), get_model
returns one model's input schema — property types, defaults, enums, and
ranges — and run_model runs it. So an assistant can go from "make me a
video" to a valid request without leaving the tools or guessing a parameter.
Entries also carry description, base_price_usd per price_unit, and a
model_url to the model's page.
model_id is the identifier shown on the model's page at
runcomfy.com/models, slashes included — e.g.
blackforestlabs/flux-1-kontext/pro/edit. File inputs must be public HTTPS URLs.
Docs: docs.runcomfy.com/trainer-apis
| Category | Tools |
|---|---|
| Datasets | create_dataset, list_datasets, get_dataset_status, delete_dataset |
| Dataset uploads | upload_dataset_file_from_url, upload_dataset_text_file, get_dataset_upload_urls |
| Training jobs | submit_training_job, get_training_job_status, get_training_job_result, cancel_training_job, resume_training_job, edit_training_job |
Typical flow: create a dataset → upload media and matching .txt captions →
poll until READY → submit a job with an AI Toolkit YAML config → poll status
→ pull checkpoints from the result.
Because the server runs remotely it cannot read local files. Upload media it
can reach over HTTP with upload_dataset_file_from_url, write captions inline
with upload_dataset_text_file, and for local or >150 MB files use
get_dataset_upload_urls and PUT the bytes to the signed URL yourself.
| Category | Tools |
|---|---|
| Balance | get_balance |
One wallet funds all three products. get_balance reports what is left, in
balance_usd for reading and balance_microdollars (millionths of a dollar)
for exact threshold checks. It is served from api.runcomfy.net rather than
mirrored per product, because there is only one figure to report.
A trained LoRA runs without any deployment: pass its base model's model_id
to run_model and the LoRA as an input, e.g.
{"lora": {"path": "my_first_lora_3000.safetensors"}} — either a name from
your LoRA Assets or a public
URL such as a checkpoint from get_training_job_result. For a dedicated
endpoint with chosen hardware, deploy it and use the Serverless tools instead.
Every client authenticates with a RunComfy API token from your Profile page. Two ways to supply it:
Token header (one command, nothing else to do):
Or browser OAuth — omit the header, then run /mcp inside Claude Code and pick
Authenticate:
--transport http is the Streamable HTTP transport. streamable-http is not a
value Claude Code accepts, and single-dash -transport / -header are not
either — both forms fail before the server is ever contacted.
Check it with claude mcp list, which should show runcomfy: connected.
Add https://mcp.runcomfy.com/mcp in Settings → Connectors → Add custom
connector, then select Connect. Claude discovers RunComfy's OAuth 2.1
endpoints, opens a RunComfy consent page, and asks for one of the API tokens
shown in your RunComfy Profile. The token
is validated by RunComfy and encrypted inside the MCP authorization grant; it
is never returned to Claude.
.cursor/mcp.json:
.vscode/mcp.json:
Settings → MCP:
https://mcp.runcomfy.com/mcpAuthorization: Bearer <token> on every request, or OAuth 2.1 with
a loopback redirect URI| Symptom | Cause |
|---|---|
401 with RunComfy rejected this API token | The token is wrong, expired, or truncated on copy. Generate a new one in Profile — the response body names the fix. |
401 with no error_description | No Authorization header reached the server. Check the header is quoted as one argument: --header "Authorization: Bearer ...". |
invalid_client_metadata during OAuth | The client registered a non-loopback, non-hosted redirect URI. Use the token header instead. |
invalid_target during OAuth | The configured URL must be exactly https://mcp.runcomfy.com/mcp — no trailing slash. RFC 8707 binds the token to that exact resource. |
503 with Retry-After | RunComfy's API could not be reached to verify the token. Retry. |
429 | More than 600 token-authenticated requests a minute from one IP. |
Revoke access by regenerating the token in your RunComfy Profile. That invalidates the token header and any OAuth grant built on it, because every MCP request revalidates the token upstream.
One RunComfy token authenticates all three products, so the same credential resolution covers every tool.
Both credential kinds converge on the same request-scoped identity header
before the container is reached. They are told apart by shape: OAuth access
tokens are always userId:grantId:secret, and a RunComfy API token never
contains a colon.
src/index.ts) — OAuth 2.1 authorization server and protected-resource boundary. Missing, invalid, expired, or wrong-audience credentials are rejected before MCP initialization or tool discovery.src/index.ts) — a RunComfy Profile token presented as Authorization: Bearer is revalidated against api.runcomfy.net on every request, rate-limited per source IP, and never forwarded as-is.src/oauth-bridge.ts) — validates an existing RunComfy Profile token, stores it only in encrypted OAuth grant data, and issues a separate audience-bound MCP access token. Dynamic client registration accepts loopback callbacks (Claude Code and other local clients) plus an exact allowlist of hosted client callbacks.server.py) — FastMCP app with 31 tools across the Serverless, Model, and Trainer APIs. It has no shared/operator credential and fails closed unless the authenticated edge supplies the current user's request-scoped RunComfy token.Local endpoints:
http://127.0.0.1:8000/healthzhttp://127.0.0.1:8000/mcpThe local Python endpoint intentionally has no shared fallback credential. Protected tool calls must go through the authenticated Worker boundary.
Pushing to main deploys automatically via .github/workflows/deploy.yml:
typecheck, Worker tests, and container tests must pass, then
wrangler deploy --containers-rollout immediate ships the Worker and the
Python container together. Pull requests run the same checks without
deploying. The workflow can also be run by hand from the Actions tab.
One repository secret is required:
| Secret | Purpose |
|---|---|
CLOUDFLARE_API_TOKEN | A token with Edit Cloudflare Workers permission on the account in wrangler.jsonc |
CLOUDFLARE_ACCOUNT_ID | Optional. account_id is already committed in wrangler.jsonc; set this only to deploy under a different account. |
To deploy by hand (requires Cloudflare Workers Paid plan with Containers enabled):
The MCP endpoint goes live at https://mcp.runcomfy.com/mcp (custom domain configured in wrangler.jsonc).
There is deliberately no shared RunComfy API-key secret. OAuth state is kept
in the OAUTH_KV binding and every upstream request is tied to the user who
authorized the OAuth grant.
wrangler.jsonc)| Name | Default | Description |
|---|---|---|
CONTAINER_INSTANCE_NAME | runcomfy-unified | Durable Object instance name |
CONTAINER_STARTUP_TIMEOUT_MS | 15000 | Max wait for container start |
CONTAINER_PORT_READY_TIMEOUT_MS | 30000 | Max wait for port ready |
MCP_MAX_BODY_BYTES | 1048576 | Max request body size |
OPENAI_APPS_CHALLENGE | Current submission token | Public OpenAI domain-verification token, served verbatim at GET /.well-known/openai-apps-challenge; unset or empty returns 404. Verify ownership of any existing token before replacing it. |
MCP_DIRECT_TOKEN_RATE_LIMITER | 600 / 60s | Per-IP cap on API-token-authenticated /mcp requests |
RUNCOMFY_SERVERLESS_BASE_URL | https://api.runcomfy.net | Serverless API base URL |
RUNCOMFY_MODEL_API_BASE_URL | https://model-api.runcomfy.net | Model API base URL |
RUNCOMFY_TRAINER_API_BASE_URL | https://trainer-api.runcomfy.net | Trainer API base URL |
.env file)| Name | Required | Description |
|---|---|---|
RUNCOMFY_SERVERLESS_BASE_URL | No | Override Serverless base URL (default: https://api.runcomfy.net) |
RUNCOMFY_MODEL_API_BASE_URL | No | Override Model API base URL (default: https://model-api.runcomfy.net) |
RUNCOMFY_TRAINER_API_BASE_URL | No | Override Trainer API base URL (default: https://trainer-api.runcomfy.net) |
RUNCOMFY_MCP_MOUNT_PREFIX | No | Path prefix for MCP mount (default: empty) |