Tutorial

use maginary from claude, cursor, or any mcp client

· by luke · 6 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)

two ways in. the hosted url for clients that can send a header, the local server for Claude Desktop

Claude Desktop — open the config from inside the app: settings → developer → edit config. that reveals claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, windows: %APPDATA%\Claude\). paste this, save, restart claude:

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

that’s pip install maginary-mcp under the hood. it needs python 3.10+ and uv (brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh); if the server shows a red dot in claude’s tool menu, that’s the usual cause. why local for claude desktop: the hosted server doesn’t ask you to log in yet, and the “request headers” section in claude’s add-connector dialog is a beta not every account has, so for some people the hosted url would be catalog-only there. the local server also remembers the key it creates for you in-chat (next section). same tools, plus upload_image for files on disk. if your dialog does show request headers: add the hosted url with “no sign-in” and the header Authorization: Bearer <your api key>, and skip the install

Claude Code — hosted, nothing to install:

claude mcp add --transport http maginary https://mcp.maginary.ai/mcp 
  --header "Authorization: Bearer <your api key>"

Cursor — ~/.cursor/mcp.json, or the add-to-cursor button and then add the key in the server’s settings:

{
  "mcpServers": {
    "maginary": {
      "url": "https://mcp.maginary.ai/mcp",
      "headers": { "Authorization": "Bearer <your api key>" }
    }
  }
}

VS Code (copilot agent mode):

code --add-mcp '{"name":"maginary","type":"http","url":"https://mcp.maginary.ai/mcp","headers":{"Authorization":"Bearer <your api key>"}}'

keys come from the dashboard. leave the header out and the hosted url still serves the catalog tools, and an x402 wallet can pay per call (last section)

any other client or agent — the same hosted url, plain streamable http:

{
  "mcpServers": {
    "maginary": { "command": "uvx", "args": ["--upgrade", "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 — put a key from the dashboard in the client config (the headers / env lines above)
  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. on the local server (Claude Desktop) it also saves that key, so you never leave the chat. on the hosted url you paste the key it made into your client once, because the hosted server stores nothing per user
  3. your agent has a wallet — it pays per image in USDC, no email, no key 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_