CNAPS.ai MCP Server — User Guide

Run 80+ AI models and 80+ processing tools on cnaps.ai with a single natural-language request — directly from Claude.

1. What is the CNAPS.ai MCP Server?

The Model Context Protocol (MCP) is a standardized interface that lets AI assistants call external services and tools directly. Once you connect the CNAPS.ai MCP Server, Claude can build and run CNAPS.ai's image, video, and text pipelines mid-conversation — no dashboard, no manual node-wiring.

Already using ComfyUI? See how to use the Comfy and CNAPS Studio MCP servers together.

💡 Core value Describe what you want in plain language ("upscale this photo 4x", "remove the person in the background", "배경 제거해줘") and the assistant selects the right model(s), wires them into a flow, and runs it for you.

At a glance

2. Quick Start (5 minutes)

Step 1: Connect the MCP Server

Claude.ai (Web)

1. Go to Customize → Connectors
2. Click + Add → Add custom connector

3. Enter the server URL: https://mcp.cnaps.ai/mcp
4. Complete authentication with your CNAPS.ai account when prompted. Before you approve. The consent screen shows two things you can't see anywhere else: the redirect host (where you'll be sent back to — if it isn't the assistant you meant to connect, close the window) and an unverified-app warning when it applies. Anyone can build an MCP client against our server; a warning means we haven't verified this one.

Claude Desktop

Add the following to claude_desktop_config.json:

json

{
  "mcpServers": {
    "cnaps-ai": {
      "url": "https://mcp.cnaps.ai/mcp",
      "transport": "http"
    }
  }
}

📁 Config file location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Your first run

Once connected, just ask:

💬 "Upscale this image 4x at the highest quality you can."

The assistant will typically:

1. upload_file() with no arguments → gets an upload link → shows it to you
2. upload_file({ token }) → waits for your upload → returns the file URL
3. suggest_flow({ task: "upscale image 4x, highest quality" }) → gets the recommended model and parameters
4. create_flow({ nodes, parameters, input_files, run: true }) → builds and starts in one call
5. get_flow({ flow_id, view: "status" }) → polls until complete, returns the output URL

3. Tool Reference (34 tools)

The server exposes 34 tools, and the set is identical whether you connect via OAuth or an x-api-key. Workspace API key management is deliberately not among them — keys are created, regenerated, and deleted in the web console only, so an automated agent cannot issue itself a key or delete one your integrations depend on.

3.1 Discovery & planning

3.2 Flow creation & editing

⚠️ update_flow vs edit_flow — update_flow changes a flow's name, tags, and node parameter values. edit_flow changes the graph itself: nodes, models, and connections. Neither requires creating a new flow.

3.3 Execution

3.4 Reading & diagnosing

3.5 Files

⚠️ You cannot send bytes from the chat through MCP. Even when the assistant can see an image in the conversation, it must use the link flow.

3.6 Community & templates

3.7 Account & workspace

📌 API keys are not managed here. Create, regenerate, and delete workspace API keys in the web console under API Key in the left sidebar. No MCP tool can do this.

4. Core Concepts

4.1 Flows

A flow is the workflow object: a graph of input, model, and output nodes with explicit connections.

You almost never build that graph by hand. Pass create_flow an ordered list of model IDs and it generates the input/output nodes and wires everything by matching port types (a model's image output connects to the next model's image input). The original input is shared via fan-out when several models need it.

javascript

// Shorthand — the common case
create_flow({ nodes: '["SISR-PiSA-SR"]' })

// Full form — when you need explicit node IDs or inline parameters
create_flow({ nodes: '[{"id":1,"type":"ai_model","model_id":"SISR-PiSA-SR","parameters":{"scale_factor":4}}]' })

Use the connections parameter only to override the automatic port-type wiring.

parameters is keyed by node ID. The parameters object uses node IDs as keys, not model IDs. When supplying parameter overrides, assign explicit IDs in nodes and use those same IDs in parameters. This also lets you configure multiple nodes that use the same model independently.

4.2 The include_optional decision

Both create_flow and preview_flow take include_optional (default true): every optional model input port also gets its own loader node.

Decide this yourself from the task — don't ask the user.

• Set false when the goal clearly uses only some modalities (e.g. "summarize this text" on a text+optional-image model → skip the image loader), or when the user's input_files cover only the required ports.
• Keep true when the goal is genuinely multimodal, when the user supplied inputs for optional ports, or when you're unsure — so no modality is silently dropped.

4.3 Recommended build order

1. suggest_flow({ task: "..." }) — let it pick the models and parameters
2. preview_flow (optional) — verify wiring if you assembled the model list yourself
3. create_flow({ ..., run: true }) — build and start in one call
4. get_flow({ flow_id, view: "status" }) — poll until completed or failed
5. diagnose_error({ flow_id }) — if it failed

4.4 Getting files in

javascript

Resulting URLs go into create_flow's input_files or run_flow's inputs.

4.5 Asynchronous polling

All runs are asynchronous.

javascript

while (true) {
  const s = await get_flow({ flow_id, view: "status" })
  if (s.state === "completed") break
  if (s.state === "failed") { await diagnose_error({ flow_id }); break }
  await sleep(3000)
}

💡 GPU-heavy models (QWEN Edit, DeblurDiff, SeedVR2, video generation) can take 1–15 minutes.

5. Model Catalog Highlights

The catalog is queryable live — always confirm parameters with get_model_parameters before assuming defaults.

⚠️ Filter by tag, not by an invented sub_category. sub_category values are the platform's own strings ("Image Upscaling", "Video Upscaling", "Object Detection", …). Guessing at a label like "Super Resolution" returns nothing. When in doubt, filter by tag (e.g. "super-resolution", "deblur", "inpainting") or by input_type/output_type.

Upscaling

For every other category (restoration, generation & editing, detection & segmentation, OCR & VLM, video generation, external cloud models, and the supporting tool nodes), query list_models with the appropriate tag or input_type/output_type filter rather than relying on a hardcoded list.

External (cloud) models

llm-claude, llm-openai, llm-gemini, llm-openai-gpt-image, llm-gemini-nano-banana-pro, llm-gemini-veo, llm-gemini-video, llm-gemini-omni, llm-gemini-tts ,llm-gemini-lyriallm-gemini-transcriberequire the corresponding provider's API key on the workspace. Check with list_llm_providers first.

6. Example Recipes

6.1 4x upscale

💬 "Upscale this photo 4x, highest quality."

javascript

create_flow({
  nodes: '[{"id":1,"type":"ai_model","model_id":"SISR-PiSA-SR"}]',
  parameters: '{"1":{"scale_factor":4}}',
  input_files: '["https://storage.../photo.png"]',
  run: true
}

⚠️ Without an explicit scale_factor: 4, SISR-PiSA-SR stays at its 2x default. ⚠️ On a 2K+ input, use SISR-SMFANet-Plus instead.

6.2 Background removal

💬 "Cut this person out with a clean transparent background."

javascript

create_flow({
  nodes: '[{"id":1,"type":"ai_model","model_id":"Segmentation-BiRefNet"}]',
  parameters: '{"1":{"extract_foreground":true}}',
  input_files: '["https://storage.../photo.png"]',
  run: true
})

6.3 Contract OCR → summary (multi-model chain)

💬 "Pull the text from this contract photo and summarize the key clauses in 3 lines."

javascript

The OCR node's text output wires into the LLM node's text input automatically.

6.4 Batch processing

💬 "Upscale all five of these photos the same way."

javascript

// Reuse an existing flow — get its input node ID from get_flow(view: "detail")
run_batch({
  flow_id: "my-upscale-flow",
  inputs: '{"1001":["https://.../img1.jpg","https://.../img2.jpg"]}'
})                                             // → batch_run_id

get_batch_status({ batch_run_id })

6.5 Start from the community instead of from scratch

javascript

search_community({ query: "background removal", sort: "most_forked" })
get_community_post({ post_id })                // preview
fork_community_flow({ post_id })               // → your own flow_id
run_flow({ flow_id, inputs: '{"1001":["https://..."]}' })

7. Tips & Common Mistakes

Model selection cheat sheet

Common mistakes

• ⚠️ Reaching for list_models first. suggest_flow handles model selection and parameter inference — start there.
• ⚠️ Expecting update_flow to change the graph. It changes parameters, name, and tags only — use edit_flow to add, remove, or rewire nodes. Rebuilding with create_flow is not necessary.
• ⚠️ Calling update_flow on a running flow. It is rejected — cancel_flow first.
• ⚠️ Guessing at sub_category strings. Filter by tag instead.
• ⚠️ Trying to pass a chat attachment through MCP. Always use the upload_file link flow.
• ⚠️ Not specifying scale_factor — SISR-PiSA-SR stays at 2x.
• ⚠️ Running PiSA-SR or DeblurDiff on 2K+ images — very slow or OOM.
• ⚠️ Referencing an llm-* model without checking list_llm_providers for a configured API key.
• ⚠️ Treating optimize_flow output as auto-applied. The patches are advisory — apply them with edit_flow.

8. FAQ

Can I attach an image directly in the chat? No. MCP cannot transfer file bytes from the chat. Use upload_file — pass file_url if the file already has a public URL, or call it with no arguments to get an upload link.

How do I run the same flow again? Create it once, then reuse the same flow_id with run_flow. Use run_batch for multiple input sets in one go.

How do I change which models are in a flow? Use edit_flow with a replace_model operation. Read the flow with get_flow first to get the node ID. edit_flow also adds and removes nodes and rewires ports; update_flow covers parameters, name, and tags only.

A run failed — how do I debug it? get_flow(view: "status") for the error, then diagnose_error({ flow_id }) for a root cause and suggested fix. Common causes: GPU unavailability, or an input exceeding a model's supported resolution.

How do I add Claude, GPT, or Gemini to a flow? Register the provider's API key under your avatar → Workspace Settings → Integrations, confirm with list_llm_providers, then reference llm-claude / llm-openai / llm-gemini as a model ID.

Something in this guide is wrong or a tool is confusing. Ask the assistant to call report_issue — it routes straight to the CNAPS.ai team with the full call context.

9. Managing your connection

Connecting an assistant with OAuth

Technical details. The server supports OAuth 2.1 with dynamic client registration and PKCE (S256), advertised at /.well-known/oauth-protected-resource. Available scopes: models:read, flows:read, flows:write, files:write, batches:read, batches:write, workspace:read, community:write.

When you connect an assistant to CNAPS.ai with OAuth, a consent screen opens. Read it before you approve — it tells you two things you can't see anywhere else:

• The redirect host. Where you will be sent back to after approving. If that host isn't the assistant you meant to connect, stop and close the window.
• An unverified-app warning, when it applies. Anyone can build an MCP client against our server. A warning means we have not verified this one; it does not mean the app is malicious, but it does mean you are trusting it on your own judgment.

Approving gives that app the ability to act on your account — create and run flows, upload and generate content, and consume your usage capacity.

Anything the assistant does counts as you

Under Section 6A of the Terms of Service, an action taken through a connected assistant is treated as your own action: creating, running, or modifying flows, uploading or generating content, incurring usage or charges, or invoking any model. The Prohibited Activities in Section 4 apply to it in full.

That cuts both ways. It means your flows and results are genuinely yours regardless of which interface made them — and it means you are responsible for what a connected assistant does with your account, including charges it runs up. Review what you are approving, and connect only assistants you actually use.

Seeing and removing connected apps

Your connected apps are listed under your avatar → Account Settings → Security → Connected apps. Each row shows the app and its domain, the workspace it can reach, its access scopes (Show all), and when it was last used. Disconnect anything you don't recognize or no longer use.

Disconnecting revokes that app's tokens immediately — its access stops at once, not at the next token expiry. Deleting an OAuth client does the same. Disconnecting stops future requests; it does not undo or delete anything the app already did.

An API key is a separate thing: keys are created, regenerated, and deleted under API Key in the left sidebar, and key management is deliberately not exposed as an MCP tool, so a connected assistant cannot issue itself a key or delete one you depend on.

10. Support & policies

• Questions or issues: support@cnaps.ai
• In-chat reporting: ask Claude to use the report_issue tool
• Privacy Policy · Terms of Service
• Using n8n or Zapier? See Connect CNAPS.ai to n8n and Connect CNAPS.ai to Zapier.

© 2026 CNAPS.ai Inc. · mcp.cnaps.ai · cnaps.ai