MCP User Guide

Run 100+ AI models 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," "extract text from this contract and summarize it" — and the assistant selects the right model(s), wires them into a pipeline, and runs it for you.

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 (local config)

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 — natural-language upscaling

Once connected, just ask:

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

The assistant will typically:

1. Call upload_image (no token) → get an upload link → show it to you
2. Call upload_image again (with token) → wait for your upload → get the file URL
3. Call suggest_pipeline (or go straight to create_and_run_pipeline) with the task description
4. Poll get_flow_status until the run completes, then return the result URL

3. MCP Tool Reference

The CNAPS.ai MCP Server currently exposes 48 tools, grouped below.

Pipeline building & discovery

Flow lifecycle management

Execution

File I/O

Model & parameter discovery

Community & templates

Workspace, account & notifications

4. Core Concepts

Flow vs. Pipeline

• A flow is the underlying workflow object — a graph of input, model, and output nodes with explicit connections. create_flow gives you full control over this graph.
• A pipeline is a shorthand: an ordered list of model IDs. create_pipeline / create_and_run_pipeline auto-generate the input/output nodes and wire everything by matching port types (e.g., a model's image output connects to the next model's image input). Use pipelines for the vast majority of tasks; drop down to create_flow only for custom wiring.

Recommended build order

1. suggest_pipeline({ task: "..." }) — let the assistant figure out the model sequence and parameters
2. check_pipeline_compatibility (optional, if you assembled the model list yourself) — verify it wires up
3. dry_run_flow (optional) — preview the graph before committing
4. create_and_run_pipeline — build and run in one step
5. get_flow_status — poll until state: "completed" (or "failed")

Two-step upload pattern

Files always upload in two calls: the first call (no token) returns an upload link; the second call (with the returned token) blocks until the user finishes uploading and returns the file URL(s).

js

// Step 1: create an upload session
upload_image()
→ { upload_url: '...', token: 'abc123' }
// → show upload_url to the user

// Step 2: wait for the upload to complete
upload_image({ token: 'abc123' })
→ { file_urls: ['https://storage.../image.png'] }

5. Model Catalog Highlights

The full catalog is queryable live via list_models (with category, sub_category, input_type, output_type, and tag filters) and get_model_parameters. Below is a curated overview; treat model IDs as illustrative — always confirm current parameters with get_model_parameters before assuming defaults.

Image Upscaling (Super Resolution)

Image Restoration

Image Generation & Editing

Detection, Segmentation & Classification

OCR & Image Understanding

Video Generation & Upscaling

External (Cloud) Models — require an API key on the workspace

Supporting Tool Nodes

46 additional lightweight tool nodes cover blending, masking, cropping/resizing, color adjustments, text overlay, list/frame extraction, and Shorts/Reels editing utilities (reframe to 9:16, subtitle burn-in, silence removal, cold-open hooks). These are typically inserted automatically by create_pipeline when models need to be connected through a compatible intermediate step.

6. Example Recipes

Recipe 1: 4x upscale

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

1. upload_image() → upload link
2. upload_image({ token }) → file_url
3. create_and_run_pipeline({
     models: ["SISR-PiSA-SR"],
     parameters: { "SISR-PiSA-SR": { scale_factor: 4 } },
     input_files: [file_url]
   })
4. get_flow_status({ flow_id }) → result image URL

⚠️ SISR-PiSA-SR defaults to scale_factor: 2. Specify scale_factor: 4 explicitly for 4x.

Recipe 2: Remove the background, keep the subject

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

create_and_run_pipeline({
  models: ["Segmentation-BiRefNet"],
  parameters: { "Segmentation-BiRefNet": { extract_foreground: true } },
  input_files: [file_url]
})

Recipe 3: Contract OCR → summary

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

create_and_run_pipeline({
  models: ["OCR-DeepSeek-OCR-LT", "llm-claude"],
  parameters: {
    "llm-claude": {
      system_prompt: "Summarize the key clauses of this contract text in 3 lines.",
      model: "claude-sonnet-4-5"
    }
  },
  input_files: [file_url]
})

Recipe 4: Batch processing

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

input_urls = ["https://.../img1.jpg", "https://.../img2.jpg", /* ... */]

run_batch({
  flow_id: "my-upscale-flow",
  inputs: { "1001": input_urls }
})
→ { batch_run_id: "batch_abc" }

get_batch_status({ batch_run_id: "batch_abc" })

7. Tips & Common Mistakes

Model selection cheat sheet

Asynchronous polling pattern

All model runs are asynchronous. Poll get_flow_status after run_flow / create_and_run_pipeline until it resolves:

js

while (true) {
  const status = await get_flow_status({ flow_id })
  if (status.state === "completed") break
  if (status.state === "failed") throw new Error(status.error)
  await sleep(3000)
}

💡 GPU-heavy models (QWEN Edit, DeblurDiff, video generation) can take 1-10 minutes. For 4K+ images, prefer LatticeNet over PiSA-SR.

Common mistakes

• ⚠️ Not specifying scale_factor leaves SISR-PiSA-SR at its 2x default.
• ⚠️ Running PiSA-SR or DeblurDiff on 2K+ images can be very slow or run out of memory.
• ⚠️ Some models require a paid plan tier — check min_required_plan via list_models or get_model.
• ⚠️ External models (llm-claude, llm-openai, llm-gemini-*, etc.) require the corresponding provider's API key to be configured on the workspace — check with list_llm_providers first.
• ⚠️ Chat attachments cannot be transferred to CNAPS.ai directly — always use upload_image / upload_file, even if the assistant can "see" the image in the conversation.

8. FAQ

Q: Can I attach an image directly in the chat? No. MCP does not support transferring file bytes from the chat to CNAPS.ai. Always use upload_image to get an upload link, or upload_file if the file already has a public URL.

Q: How many times can I run the same flow? As many as you like. Create it once with create_pipeline/create_flow, then reuse the same flow_id with run_flow for subsequent runs.

Q: How do I add external models like Claude, GPT, or Gemini to a pipeline? Register the provider's API key in your workspace settings, then check availability with list_llm_providers before referencing llm-claude, llm-openai, llm-gemini, etc. as a model ID.

Q: A run failed — how do I debug it? Check get_flow_status for state: "failed" and its error message, then call diagnose_error for a suggested fix. Common causes are GPU unavailability or input images exceeding a model's supported resolution.

Q: What's the difference between create_pipeline and create_flow?create_pipeline takes a simple ordered list of model IDs and auto-wires everything — use this for almost everything. create_flow exposes the full node/connection graph for cases that need custom wiring create_pipeline can't express.

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