CNAPS.ai MCP Server — User Guide

Run 70+ AI models and 50+ 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.

💡 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 claude.ai → Settings → Connectors
2. Click Add custom connector
3. Enter the server URL:

https://mcp.cnaps.ai/mcp

1. Complete authentication with your CNAPS.ai account when prompted.

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 (33 tools)

The server exposes 33 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

⚠️ No MCP tool changes a flow's graph topology. update_flow changes node parameters, name, and tags only. To change which models are in the flow or how they connect, rebuild it with create_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 Dashboard → API Key. 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.

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 — verified 2026-08-10

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-openai-sora2, llm-gemini-veo, llm-gemini-video, llm-gemini-omni, llm-gemini-tts require 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

⚠️ 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: '["Segmentation-BiRefNet"]',
  parameters: '{"Segmentation-BiRefNet":{"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; rebuild with create_flow to change topology.
• ⚠️ 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.

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? Rebuild it with create_flow. No MCP tool edits a flow's graph. update_flow covers parameters, name, and tags.

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 in workspace settings, 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. Support & policies

• Questions or issues: support@cnaps.ai
• In-chat reporting: ask Claude to use the report_issue tool
• Privacy Policy · Terms of Service
• Also listed on the MCP Registry, Smithery, and Glama
• Using n8n? See Connect CNAPS.ai to n8n

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