Tutorial

use maginary from claude, cursor, or any mcp client

· by luke · 5 min read

I said in the seedance post that I’d announce the MCP separately. this is that

the short version: https://mcp.maginary.ai/mcp. paste it into your MCP client and your assistant has every model in maginary, the whole --flag language, and the follow-up actions (upscale, vary, pan, zoom, animate). the long version is maginary.ai/mcp. this post is the walkthrough

what an mcp server is, in one paragraph

MCP is the plug standard for AI assistants: a server describes its tools, the assistant reads the descriptions and calls them when they fit. so instead of me writing “here’s how to wire maginary into your chatbot” docs for every framework, I ship one server and Claude, Cursor, Continue, Cline, VS Code, ChatGPT-with-apps and whatever comes next all speak to it the same way. you don’t write glue code. you talk

connect (30 seconds)

Claude Desktop / claude.ai — settings → connectors → add custom connector, url https://mcp.maginary.ai/mcp. or in claude_desktop_config.json:

{
  "mcpServers": {
    "maginary": { "url": "https://mcp.maginary.ai/mcp" }
  }
}

Claude Code — one line:

claude mcp add --transport http maginary https://mcp.maginary.ai/mcp

Cursor — same json in ~/.cursor/mcp.json, or the add-to-cursor button on the mcp page

VS Code (copilot agent mode):

code --add-mcp '{"name":"maginary","type":"http","url":"https://mcp.maginary.ai/mcp"}'

local, on your machine — if you’d rather run it yourself (or want to upload files from disk):

{
  "mcpServers": {
    "maginary": { "command": "uvx", "args": ["maginary-mcp"] }
  }
}

that’s pip install maginary-mcp under the hood; source is on github, MIT

first chat: no account needed to start

the catalog tools work with nothing. ask “what flags does maginary support for video?” and the assistant calls search_parameters and answers from the live catalog

to actually generate, you need credits. three ways, and the assistant handles all of them:

  1. you already have an account — hit “connect” in Claude and sign in (oauth), or drop an api key from the dashboard into the config as "headers": { "Authorization": "Bearer …" }
  2. you don’t — say “sign me up, my email is x”. the assistant calls create_account, you click the verification link, it creates a key and offers you the $10 novice pack via stripe. you never leave the chat
  3. your agent has a wallet — it pays per image in USDC, no email at all. that’s x402, and it gets its own post

what it looks like

“generate a fox in autumn foliage, cinematic, 16:9”

the assistant writes a fox in autumn foliage, cinematic --ar 16:9, calls generate, then wait_for_generation. four images show up inline in the chat, not as links. ~30 seconds

“upscale the second one”

it reads available_actions off the finished generation, sees upscale_2x is valid for slot 1, calls execute_action. new image, inline

“now make it a 5 second video”

execute_action again, img2vid_basic this time. a clip comes back. same prompt bar as the app, same three lanes for picking a model: plain prompt (maginary picks), --flagship (premium pool), or a model by name. the assistant knows the lanes because the whole flag map is in the server instructions — it doesn’t guess flags, and if it tries one that doesn’t exist the server says exactly which one

“make this photo a watercolor” (you paste an image url)

urls in the prompt are image-to-image. on the local server you can also attach a file and it goes through upload_image first

the 16 tools

  • create: generate, execute_action, wait_for_generation, get_generation, upload_image (local only)
  • catalog, no auth: list_parameters, search_parameters, get_parameter
  • account: create_account, create_wallet_account, check_account_status, manage_api_key, configure_api_key
  • billing: get_balance, get_products, checkout

every failure is a structured result the assistant can act on — auth, payment_required (with a top-up link), timeout (still running, call again), validation (the exact flag that was wrong). no stack traces, no guessing

pricing

same credits as the app, same prices. 1 credit ≈ 7¢ ≈ one standard image. a 4-image grid is 4 credits, a --flagship image is 6, video starts around 9. nothing runs before the price is known — the estimate comes back first, and get_balance tells the assistant what’s left

the skill, for hosts without mcp

not every place Claude runs supports MCP servers. so the package also ships an agent skill: one markdown file that teaches the --flag language, model choice, and the generate → poll flow over plain rest

uvx maginary-mcp --install-skill   # → ~/.claude/skills/maginary-image-gen/SKILL.md

with the server connected Claude calls the tools; without it, curl. same mental model either way

why I built it this way

hosted-first, because agents live in Claude Desktop, Cursor and hosted apps, and “pip install this on your box” is fine for one dev poking around but not for anyone else. multi-tenant, because one server for everyone means the url in every directory and every tutorial is the same one, forever. thin, because the server holds zero business logic — it’s a typed window onto the same rest api you can curl. if the api can do it, the mcp can do it, and I can’t accidentally ship two products

next up: agentic payments — what happens when the thing calling generate has no email, no card, and a wallet

connect: maginary.ai/mcp

follow my progress: @xucian_