give your agent eyes

image + video generation for claude, cursor, and any mcp client. one hosted url for clients that take a key, one json block for claude desktop. your agent can sign up, generate, upscale, animate (and pay for itself).

add to cursor add to vs code

catalog tools work with no account. generation needs one (your agent can create it in-chat).

connect in 30 seconds

pick your client. hosted is the default. it is the same server for everyone, scoped per request to whoever is calling.

claude desktop → settings → developer → edit config. that opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, windows: %APPDATA%\Claude\). paste, save, restart claude.

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

needs python 3.10+ and uv (brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh). no account? say "sign me up, my email is …" and claude creates one, saves the key, and buys a pack, all in the chat. prefer the hosted url? if your "add custom connector" dialog shows a request headers section (beta), add it with no sign-in and the header Authorization: Bearer <your api key>; without that section the hosted url is catalog-only in claude until we ship the login flow.

in any terminal, once. it writes ~/.claude.json for you.

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

hosted, nothing to install. key from your dashboard. drop the --header line for catalog-only, or if your agent pays with x402.

cursor → settings → mcp → add new global mcp server. that opens ~/.cursor/mcp.json (or .cursor/mcp.json inside a project).

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

~/.cursor/mcp.json, or the one-click button above (then add the key under the server's settings).

in a terminal, once. it writes the server into your user mcp.json.

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

copilot agent mode. or the one-click button above, then add the header in .vscode/mcp.json.

https://mcp.maginary.ai/mcp
Authorization: Bearer <api key>      # humans
_meta["x402/payment"]               # wallets, no account (x402 sdk does this)

plain streamable http. catalog tools need nothing. an x402-aware client pays inside the tool call and the first payment creates the account.

then just talk.

"generate a fox in autumn foliage, 16:9" → four images inline.

"upscale the second one" → done.

"now animate it" → a clip.

already have an api key? add "headers": { "Authorization": "Bearer …" } to the hosted entry, or "env": { "MAGINARY_API_KEY": "…" } to the local one. keys live in your dashboard.

16 tools

everything the rest api does, as tools your agent discovers on its own. the full --flag catalog is in the server instructions, so the model knows which flags exist before it writes a prompt.

create

generate — text → image or video. flags ride in the prompt: --ar 16:9, --flagship, --mp4
execute_action — upscale, vary, pan, zoom out, animate — on any finished image
wait_for_generation — poll until done. returns image urls, shown inline in the chat
get_generation — one record: state, slots, available actions
upload_image — local file → cdn url for image-to-image (local mode only)

catalog (no auth)

list_parameters — every --flag, by category and status
search_parameters — free-text search over names, aliases, examples
get_parameter — one flag in full: values, models, examples

account

create_account — sign up in-chat with an email
create_wallet_account — sign up with a wallet signature, no email
check_account_status — is the email verified yet?
manage_api_key — create / rotate / revoke
configure_api_key — bind a key to this session (local mode)

billing

get_balance — credits left, plan, renewal
get_products — packs and subscriptions
checkout — stripe checkout link

three ways to pay

same credits, same prices as the app. 1 credit ≈ 7¢ ≈ one standard image. a 4-image grid is 4 credits, a premium --flagship image is 6, video starts at 9. the exact price of any prompt comes back in the response before anything runs.

your api key

one key from the dashboard in your client's config. uses the credits you already have — packs from $10 or a monthly plan.

agent signs up

no account? the agent calls create_account with your email, you click the verification link, it buys a pack via stripe. on the local server it keeps the key too, so you never leave the chat. on the hosted url you paste the key it made into your client once.

agent pays itself

x402: out of credits, the server answers 402 with the exact price in usdc on base. the agent's wallet signs, the call retries, the image comes back. no email, no card, no human. the wallet is the account.

claude skill (works without the mcp too)

a single skill file that teaches claude the --flag language, model choice, and the generate → poll flow over plain rest. with the mcp connected it calls the tools; without it, curl.

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

→ the launch post: use maginary from claude, cursor, or any mcp client → agentic payments: your agent pays for images with usdc → docs hub → every --flag → source on github (mit) → pypi: maginary-mcp → openapi spec (for non-mcp agents) → llms.txt