maginary-mcp

Model Context Protocol server for Maginary — an abstracted OpenRouter for images and video: ~20 model families (GPT-image-2, Seedance 2, Sora 2, Nano Banana Pro, Flux…) behind one Midjourney-style --flag prompt. 16 tools: full flag catalog, generate / upscale / vary / animate, in-chat signup, billing, and x402 pay-per-use for agents with a wallet.

Watch the demo →

why

Maginary uses a Midjourney-style --flag prompt DSL over an async HTTP API. This server:

• surfaces the full parameter catalog to your LLM so it can pick the right flags
• offers a one-shot generate tool that hits POST /api/gens/
• offers get_generation + wait_for_generation for polling to a terminal state
• works offline for the catalog tools (ships a bundled snapshot; refreshed from the live docs endpoint at startup when reachable)

connect

This is an MCP server — you don't run it directly; your AI client (Claude Desktop, Cursor, etc.) launches and talks to it behind the scenes. Just add one config block and start chatting.

Claude Desktop

In Claude Desktop: settings → developer → edit config. That opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). Add:

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

Restart Claude Desktop. Ask it to generate an image — it will see Maginary's tools automatically.

No account yet? No problem — Claude will walk you through signup (just give it your email). Already have an API key? Add it to skip that step:

"env": { "MAGINARY_API_KEY": "sk-mag-…" }

Requires Python 3.10+ and uv. Alternatively: pip install maginary-mcp.

configuration

Nothing is required. For the stdio server you'll at most set one variable:

The rest only apply when you run the hosted server yourself (maginary-mcp-http, see below). Directory pages that scan the code list them too; ignore them for local use.

hosted (no-install) — Streamable HTTP

Connect a client straight to the hosted server at https://mcp.maginary.ai/mcp. Zero install — the server is multi-tenant, so each request is scoped to whatever credential it arrives with. Two ways to authenticate, pick whichever fits the client:

Connect (OAuth) — for Claude Desktop, claude.ai, and any other client that speaks MCP's OAuth spec. Add the server with no headers at all:

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

Click "Connect" in the client. It opens a login page on app.maginary.ai, you sign in and approve the requested scopes, and the client holds the token from then on — no key to generate or paste. Requires the server to be running with MAGINARY_MCP_REQUIRE_AUTH=1; without it, no login is asked for at all.

API key — for any client that doesn't do the OAuth dance (or if you'd rather not click through a login), generate a key at app.maginary.ai/dashboard#api-keys and send it yourself:

{
  "mcpServers": {
    "maginary": {
      "url": "https://mcp.maginary.ai/mcp",
      "headers": { "Authorization": "Bearer sk-mag-…" }
    }
  }
}

Both are equivalent once connected — same tools, same account. Catalog tools work with no credential either way; generate / get_generation / wait_for_generation need one. Run the hosted server yourself with:

paying inside the tool call (x402 over MCP)

No key at all? Call generate anyway. Out of credits (or no account), the result is isError: true with the x402 PaymentRequired at the top level (accepts, resource, …) plus error: "payment_required". An x402-capable MCP client — the x402 SDK's x402MCPSession — signs accepts[0] and calls the same tool again with the payment in _meta["x402/payment"]. The server forwards it to the backend as PAYMENT-SIGNATURE; the backend verifies, settles on Base and, for a wallet with no account, creates one. The settled result carries the on-chain receipt in _meta["x402/payment-response"] and x402_receipt. No API key is returned — subsequent requests use wallet-signed auth headers (X-Wallet-Address, X-Wallet-Signature, X-Wallet-Timestamp) instead. The server holds no payment logic; everything is decided by the backend's /api/gens/ contract.

wallet-signed authentication

After the first x402 payment creates the wallet's account, all subsequent requests are authenticated by signing a short message with the wallet's private key. Three headers on every request:

The challenge string is:

Maginary: authenticate <address> at <timestamp>. This does not move funds.

with <address> lowercased and <timestamp> the same unix seconds sent in the header. The timestamp must be within 5 minutes of the server's clock (30 s of future skew tolerated). No API key management needed — the wallet is the credential.

pip install "maginary-mcp[http]"
maginary-mcp-http          # serves /mcp on 0.0.0.0:8642 (MAGINARY_MCP_PORT to change)
# — or —
docker build -t maginary-mcp . && docker run -p 8642:8642 maginary-mcp

The hosted server sets no MAGINARY_API_KEY (keys come per-request). It also serves /health, a human page at GET /, the OAuth protected-resource metadata and an MCP server card at /.well-known/mcp/server-card.json (live tool list, auth posture) for directories that scan a bare URL.

Claude Skill

The server ships an Agent Skill that teaches the --flag DSL, model selection, and the async generate→poll flow:

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

The skill stands on its own — hosts without MCP get the DSL plus the raw REST calls (POST /gens/ → poll). With the server connected, Claude instead calls search_parameters for the authoritative flag list and generate/wait_for_generation natively. Re-running updates it; local edits are protected unless you pass --force. Source: src/maginary_mcp/SKILL.md.

tools

catalog (no auth)

• list_parameters(category?, status?, include_reserved=false) — enumerate the catalog
• search_parameters(query, category?, include_reserved=false) — text search over names / aliases / desc / examples
• get_parameter(name) — full record for one flag (canonical name or alias)

list_parameters responses include the categories / statuses taxonomy, and both list/search responses carry source (live vs bundled-snapshot).

generation (auth required)