Connect from your client

Pick your MCP-aware editor or AI client. Each tab has the exact JSON snippet to paste and one-line instructions.

// .cursor/mcp.json  — no API key needed, OAuth handles auth
{
  "mcpServers": {
    "artemotion": {
      "url": "https://mcp.artemotion.ai/api/mcp"
    }
  }
}

// .cursor/mcp.json  — static API key (alternative)
{
  "mcpServers": {
    "artemotion": {
      "url": "https://mcp.artemotion.ai/api/mcp",
      "headers": { "Authorization": "Bearer ae_live_…" }
    }
  }
}

// ~/.codeium/windsurf/mcp_config.json  — no API key needed
{
  "mcpServers": {
    "artemotion": {
      "serverUrl": "https://mcp.artemotion.ai/api/mcp"
    }
  }
}

// ~/.codeium/windsurf/mcp_config.json  — static API key (alternative)
{
  "mcpServers": {
    "artemotion": {
      "serverUrl": "https://mcp.artemotion.ai/api/mcp",
      "headers": { "Authorization": "Bearer ae_live_…" }
    }
  }
}

NEW What's new in 0.6

0.3 Earlier — discover & recommend

Prerequisites

• Node.js 20 or newer — required by the MCP server. Already installed on most dev machines.
• An ArtEmotion API key — generate one at Settings → API keys. Keys look like ae_live_….
• Credits on your account — each generation deducts from your balance, same as the REST API. list_*, recommend_model, and scaffold_pipeline don't cost credits.

Available tools

The hosted MCP endpoint exposes 81 tools. Tools are grouped by intent — Discover, Generate, Pipeline, Mix, Account & Library, Utility, LoRA & advanced, Job recovery, Studio tools, and Community & ratings.

Discover

Generate

Pipeline + Mix

Account & library

Utility

LoRA & advanced

Job recovery

Studio tools

Community & ratings

Example responses

// list_models { kind: "image", sort: "cheapest", search: "nano-banana" }
{
  "count": 3,
  "total_catalog": 365,
  "sort": "cheapest",
  "models": [
    { "id": "fal-ai/nano-banana",     "name": "Nano Banana",     "kind": "image", "base_credits": 8  },
    { "id": "fal-ai/nano-banana-pro", "name": "Nano Banana Pro", "kind": "image", "base_credits": 38 },
    { "id": "fal-ai/nano-banana-2-pro","name": "Nano Banana 2 Pro","kind": "image","base_credits": 64 }
  ]
}

// recommend_model { description: "Photoreal sunset cityscape", prefer: "best" }
{
  "recommendation": {
    "id": "fal-ai/nano-banana-pro",
    "name": "Nano Banana Pro",
    "kind": "image",
    "base_credits": 38,
    "has_image_input": true
  },
  "reason": "Top-tier image model with 4K output and web-search grounding — strongest fit for a photorealistic cinematic scene.",
  "alternatives": [
    { "id": "fal-ai/flux-2-pro", "name": "FLUX 2 Pro", "base_credits": 28 }
  ]
}

// start_generation { model_id: "fal-ai/nano-banana-pro", prompt: "...", aspect_ratio: "16:9" }
{
  "job_id":      "019e2d09-260…",
  "model_id":    "fal-ai/nano-banana-pro",
  "kind":        "image",
  "status":      "queued",
  "credits_used": 38,
  "credits_left": 47462,
  "poll_url":    "https://app.artemotion.ai/api/v1/jobs/019e2d09-260…?model_id=fal-ai%2Fnano-banana-pro"
}

// scaffold_pipeline { prompt: "10s coffee channel intro", include_music: true, include_voice: true }
{
  "scaffold": {
    "name": "Coffee Brew Intro",
    "totalDurationSec": 10,
    "scenes": [
      { "id": "scene-1", "title": "Beans pouring", "kind": "video",
        "model": "fal-ai/kling-video/v3/standard/text-to-video",
        "settings": { "duration": "5", "aspect_ratio": "16:9" },
        "prompt": "Close-up of dark roasted coffee beans pouring..." }
    ],
    "musicTrack": { "prompt": "warm lo-fi jazz", "model": "cassetteai/music-generator", "durationSec": 10 },
    "voiceTrack": { "script": "Welcome to my channel...", "model": "fal-ai/orpheus-tts", "voice": "warm" }
  }
}

Try saying…

Drop these into Claude Desktop / Cursor / Zed once you've wired up the server. The model picks the right tools on its own.

Environment variables

UPDATE Upgrading from an older version

The MCP server is published as artemotion-mcp on npm and runs via npx on every client launch. Whether you have to do anything when a new version ships depends on how your config is written.

Recommended: pin to the latest tag

For deterministic upgrades, pin to @latest (always resolves to the newest published version) or to a specific release (so a future minor bump doesn't change your tool surface without warning).

{
  "mcpServers": {
    "artemotion": {
      "command": "npx",
      "args": ["-y", "artemotion-mcp@latest"],
      "env": { "ARTEMOTION_API_KEY": "ae_live_…" }
    }
  }
}

Force-refresh the npx cache

If you've relaunched the client and the new tools still don't show up, your local npx cache is holding the old bundle. One-line fix, then quit + relaunch:

rm -rf "$(npm config get cache)/_npx"

On Windows: rd /s /q "%LOCALAPPDATA%\\npm-cache\\_npx".

How to tell which version is running

Ask the model "What MCP tools does ArtEmotion expose?" — the count and tool names give it away. The current server exposes 81 tools, including list_studios and the 13 grouped run_*_studio controllers alongside generation, pipelines, editing, library, account, and community tools. If the Studio controllers are missing, reconnect the client so it refreshes the tool catalog.

Troubleshooting

• "Server failed to start" / no tools appear. Check the client's MCP logs for the actual error. The most common cause is a missing or mistyped ARTEMOTION_API_KEY — the server crashes early with a clear message.
• 401 / "Invalid or revoked API key." The key was rotated or revoked. Generate a new one at Settings → API keys.
• 402 / "Insufficient credits." Top up your balance from the pricing page, or upgrade your plan from pricing.
• 402 / "COST_CAP_EXCEEDED". You passed max_credits to start_generation and the estimate was higher. Raise the cap or pick a cheaper model with list_models { sort: "cheapest" }.
• 403 / "Editor requires Pro plan ($54/mo)". start_edit + uploaded clips in the editor are gated. Upgrade or stick to combine_videos (no plan gate).
• 429 / "Rate limited." You're hitting the per-key rate limit on /api/v1/*. The server surfaces the same limit — back off and retry.
• 404 on a tool that should exist. Your client is talking to a server that hasn't been redeployed with the new endpoints. See the Upgrading section.
• npx hangs the first time. First-run downloads ~10 MB. After the initial install it's cached and starts instantly.
• Tools didn't refresh after an upgrade. See Upgrading from an older version — usually a quit-and-relaunch is enough, sometimes you need to wipe the npx cache.