maginary-mcp
Server Details
AI image + video generation for agents: --flag prompt DSL, async generate/poll, x402 pay-per-use.
- Status
- Healthy
- Uptime
- 100.0% over the last 24 hours
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-11-25
- URL
- Repository
- maginaryai/maginary-mcp
- GitHub Stars
- 1
- Server Listing
- maginary-mcp
- ChatGPT
- –
- Claude
- –
TDQS
Scored across 16 tools
Each tool has a clearly distinct purpose: account management, billing, generation, polling, parameter lookup, and upload are all separated. The only potential overlap is between get_generation and wait_for_generation, but wait_for_generation explicitly wraps polling, and the descriptions distinguish them well (one-shot fetch vs backoff polling).
All tool names follow a consistent verb_noun pattern (check_account_status, create_account, get_balance, manage_api_key, etc.) with no deviations in case or style. The pattern is predictable and readable throughout.
16 tools is slightly higher than typical but justified by the breadth of the domain (account lifecycle, billing, generation, parameters, upload, follow-up actions). It's not bloated; each tool appears to earn its place, though a few (e.g., get_parameter vs list_parameters vs search_parameters) could arguably be consolidated.
The surface covers account creation, authentication, API key management, balance checking, product listing, checkout, image generation, polling, follow-up actions, upload, and parameter introspection. Minor gaps exist: no explicit cancel/delete generation tool, and no direct way to update account details, but agents can work around these.
Available Tools
16 toolscheck_account_statusCheck account statusARead-onlyIdempotentInspect
Check account verification status, credit balance, and API key count.
Use this after ``create_account`` to poll whether the user has clicked the
verification link. Pass ``email`` + ``password`` (from ``create_account``)
for Basic auth, or omit both to use the configured API key.
Args:
email: Account email (for Basic auth).
password: Account password (for Basic auth).
Returns:
Dict with ``verified`` (bool), ``email``, ``api_key_count``,
``credits_remaining``, ``uploads_remaining``.
Inputs: email, password. Returns: object
checkoutCreate checkout linkAInspect
Create a Stripe checkout session for purchasing a product.
Returns a ``checkout_url`` — the user must open it in a browser to
complete payment. After payment, credits are provisioned automatically
via webhook. **Present the URL exactly as returned, including the
``#fragment`` — do not truncate, reformat, or strip any part of it.**
If the agent has a USDC wallet, skip this entirely — just call
``generate`` and the x402 protocol handles payment on-chain.
Args:
product_id: Product ID from ``get_products``.
email: Account email (for Basic auth during onboarding).
password: Account password (for Basic auth during onboarding).
Returns:
Dict with ``checkout_url``. On failure, an ``isError`` result — e.g.
``error: "email_not_verified"`` until the user clicks the
verification link, or ``"auth"`` / ``"failed"``.
Inputs: product_id (required), email, password. Returns: object
configure_api_keyConfigure API keyAIdempotentInspect
Activate an API key. Local (stdio) servers persist it; hosted does not.
Call this after ``manage_api_key(action='create')`` returns a ``raw_key``.
On a local server the key is saved to ``~/.config/maginary/api_key``
(chmod 600) and survives restarts. On the hosted server
(mcp.maginary.ai) nothing can be stored — auth is per-request: the
response will say ``persisted: false`` and the key must be sent as an
``Authorization: Bearer <key>`` header on every request (set it in the
MCP client's connection config).
Args:
api_key: The full API key string returned by ``manage_api_key``.
Returns:
Confirmation dict.
Inputs: api_key (required). Returns: object
create_accountCreate accountAInspect
Create a new Maginary account for the given email address.
Returns the auto-generated password — display it to the user ONCE so they
can save it. A verification email is sent; the user must click the link
before the account can generate images.
After verification, use ``manage_api_key(action='create')`` with
``email`` + ``password`` to get an API key, then ``configure_api_key``
to activate it.
Args:
email: The user's email address.
Returns:
Dict with ``email``, ``password``, and ``message``. On failure, an
``isError`` result — e.g. ``error: "already_exists"`` (email taken:
ask the user for their password or a different email),
``"rate_limited"``, or ``"failed"``.
Inputs: email (required). Returns: object
create_wallet_accountCreate wallet accountADestructiveInspect
Create (or access) a Maginary account using a wallet signature.
Sign the message ``Maginary: authenticate <address> at <timestamp>.
This does not move funds.`` with EIP-191 ``personal_sign`` and pass all
three values. On success, an API key is returned immediately — no email
verification needed.
Use this when you have a wallet but no email. The returned ``api_key``
should be passed as ``Authorization: Bearer <key>`` in the MCP client
config, or via ``configure_api_key`` (stdio) / ``_meta["maginary/api_key"]``
(hosted, per-call).
If the wallet already has an account, returns the existing account with
a fresh API key.
Args:
address: EVM wallet address (0x..., 42 chars).
signature: Hex-encoded EIP-191 personal_sign of the auth message.
timestamp: Unix epoch seconds used in the signed message (must be
within the last 5 minutes).
Returns:
Dict with ``address``, ``api_key`` (full key — show once),
``key_prefix``, ``created`` (bool), ``message``.
On failure: ``isError`` with ``error`` = ``"validation"``,
``"signature_failed"``, or ``"rate_limited"``.
Inputs: address (required), signature (required), timestamp (required). Returns: object
execute_actionRun action on imageAInspect
Run a follow-up action on a completed generation's image.
After ``generate`` → ``wait_for_generation``, the response's
``processing_result.available_actions`` lists what's possible per slot.
Call this tool with one of those action types.
Args:
generation_uuid: UUID of the parent generation (from ``generate``).
action_type: One of the values from ``available_actions`` — e.g.
``"upscale_2x"``, ``"upscale_1_5x"``, ``"vary_strong"``,
``"vary_subtle"``, ``"pan_left"``, ``"pan_right"``,
``"pan_up"``, ``"pan_down"``, ``"zoom_out_2x"``,
``"zoom_out_1_5x"``, ``"img2img_basic"``, ``"img2img_inpaint"``,
``"img2vid_basic"``, ``"reroll"``.
parent_image_index: The slot index of the image to act on (0, 1,
2, or 3 for a 4-image grid). Required for per-slot actions;
omit for ``"reroll"`` (global action).
prompt: Required for ``img2img_basic``, where it is the edit
instruction (e.g. ``"make the hat red"``; flags such as ``--2``
or ``--flagship`` may follow it), and for ``img2img_inpaint``,
where it is the instruction followed by ``--mask <shapes>``
(e.g. ``"make the hat red --mask rect(.2,.1 .8,.4)"``; the
instruction may be empty to just redo the area). Optional otherwise: for
``vary_*`` you can steer the variation with a new prompt; for
``img2vid_basic`` you can describe the desired motion.
callback_url: Optional webhook URL (same as ``generate``).
Returns:
The newly created child generation record (same shape as
``generate``'s return — poll it with ``wait_for_generation``).
On failure, same ``isError`` contract as ``generate``:
``"auth"``, ``"payment_required"`` (with x402 challenge),
or ``"failed"``.
Inputs: action_type (required), generation_uuid (required), prompt, callback_url, +1 more. Returns: object
generateGenerate image or videoAInspect
Kick off a generation via POST /api/gens/.
Args:
prompt: The user's words, passed through as-is. Do NOT add flags the
user did not ask for — no ``--ar``, no ``--flagship``, no model
flags. Every extra flag costs credits; adding them unrequested is
wrong. Standard quality is the default and is cheap; ``--flagship``
is ~4× more expensive and must only be used when the user
explicitly asks for best quality.
If the user asks about quality or aspect ratio: ask them first
(standard vs flagship, landscape vs portrait) before generating.
Flags go at the END, only when the user asked:
``--1``/``--2``/``--3``/``--4`` = image count (default 4),
``--ar 16:9`` = aspect ratio, ``--flagship`` = best quality.
Unknown flag: call ``get_parameter(name)`` first — never guess.
Examples — user says "a fox": prompt is ``"a fox"``.
User says "a fox, landscape, best quality":
prompt is ``"a fox --ar 16:9 --flagship"``.
**Image-to-image (img2img):** Place one or more public image URLs
in the prompt, followed by editing instructions:
``"https://cdn.example.com/photo.webp reimagine as oil painting --ar 16:9"``
The engine extracts URLs automatically and switches to img2img mode.
Multiple URLs trigger multi-input mode (compositing/combining).
Use ``upload_image`` first if images aren't already hosted.
**Image-to-video:** Place an image URL in the prompt AND add
``--mp4`` plus video flags (``--5sec``, ``--1080p``). Or use
``execute_action`` with ``action_type="img2vid_basic"`` on a
completed generation's image.
**Style reference (--sref) is NOT img2img:** ``--sref <url>``
copies the visual *style* of a reference image (colors, mood,
composition) without using the image content as input. A bare URL
in the prompt edits the actual image; ``--sref`` transfers style.
callback_url: Optional HTTPS URL that will receive a webhook when the
generation reaches done / failed. See
https://maginary.ai/blog/webhooks-guide for signature verification.
Returns:
On success, the created generation record. Key fields: ``uuid`` (use
to poll), ``action_type``, ``processing_state``,
``expected_output_count``.
On failure, an ``isError`` result instead (nothing is raised), with a
JSON body whose ``error`` field is one of:
- ``"auth"`` — no/invalid API key. Surface the message directly to
the human.
- ``"payment_required"`` — out of credits. The body carries
``billing_url`` and top-level x402 fields (``accepts``,
``resource``): either send the human to ``billing_url`` to top up,
or pay programmatically via x402 (settle ``accepts[0]`` with USDC
on Base and retry).
- ``"demo_not_found"`` — ``--demo`` prompt has no matching seeded
generation. ``available_demos`` lists valid prompts.
- ``"failed"`` — anything else (invalid prompt, rate limit, backend
or network error); see ``message``.
x402 over MCP: a ``payment_required`` result also carries the x402
fields at the top level (``accepts``, ``resource``); an x402-capable
client signs ``accepts[0]`` and calls this tool again with the payment
in ``_meta["x402/payment"]``. The settled call returns the generation
with ``x402_receipt`` (and ``_meta["x402/payment-response"]``); a
wallet's first settlement creates its account. Subsequent requests
use wallet-signed auth headers (X-Wallet-Address/Signature/Timestamp)
or pass an API key as ``_meta["maginary/api_key"]``.Every flag that exists, and its state: Flags, live (35): --ar, --output-count (--1/--2/--3/--4), --seed, --transparent, --sref, --sw, --png, --jpg, --webp, --svg, --2k, --4k, --upscale, --vary, --varysubtle, --varystrong, --panleft, --panright, --panup, --pandown, --zoomout, --mp4, --video-resolution (--480p/--540p/--720p/--1024p/--1080p/--2160p / --4k (4k, Seedance 2 Pro)/--480p24 / --480p24fps/--540p24 / --540p24fps/--720p24 / --720p24fps/--1024p30 / --1024p30fps/--1080p24 / --1080p24fps), --video-fps (--24fps/--30fps/--50fps/--60fps), --video-duration (--4s / --4sec/--5s / --5sec/--6s / --6sec/--8s / --8sec/--10s / --10sec/--12s / --12sec), --flagship, --sora, --soralite, --nanobananapro, --nb2, --gpt2, --gpt2high, --seedance2, --seedance2pro, --demo. Partial (4, only some models honour them): --no, --zoomout2x, --zoomoutexpand, --zoomoutexpand2x. Reserved (2, the parser rejects them): --cref, --cw. Any other --flag is rejected with Unrecognized parameter. Details: get_parameter(name).
Inputs: prompt (required), callback_url. Returns: object
get_balanceGet balanceARead-onlyIdempotentInspect
Check remaining credits and uploads for the authenticated account.
Args:
email: Account email (for Basic auth).
password: Account password (for Basic auth).
Returns:
Dict with ``credits_remaining`` and ``uploads_remaining``.
Inputs: email, password. Returns: object
get_generationGet generationARead-onlyIdempotentInspect
Fetch a generation by UUID (GET /api/gens/{uuid}/).
Args:
uuid: The UUID returned by ``generate``.
Returns:
The full generation record. If terminal, ``image_urls[]`` holds the
finished outputs and ``processing_result.slots[]`` the per-slot detail.
NOTE: a generation that failed server-side is a SUCCESSFUL tool call
returning ``processing_state: "failed"`` — always check the state,
never infer success from the absence of a tool error.
**Follow-up actions:** A completed generation's
``processing_result.available_actions`` maps slot indices to valid
action types. E.g. ``{"0": ["upscale_2x", "vary_strong", ...],
"global": ["reroll"]}``. Use ``execute_action`` with the ``uuid``,
a chosen ``action_type``, and the ``parent_image_index`` (the slot
key as an int) to run an action.
Hosted: a key obtained mid-session may be passed as
``_meta["maginary/api_key"]``.
Inputs: uuid (required). Returns: object
get_parameterGet parameterARead-onlyIdempotentInspect
Return the full record for a single parameter (canonical name or alias).
Args:
name: Parameter name with or without leading ``--`` (e.g. ``ar``,
``--ar``, ``aspect``). Case-insensitive.
Returns:
The parameter dict. Not-found is an ``isError`` result — surface it
rather than fabricating a param.
Inputs: name (required). Returns: object
get_productsGet productsARead-onlyIdempotentInspect
List available Maginary products/plans with pricing.
No authentication required. Use this to present purchase options to the
user. The ``novice_pack`` ($10, 150 credits) is the recommended starting
point.
Returns:
Dict with ``count`` and ``products`` — each product carries ``id``,
``short_name``, ``title``, ``description``, ``price_cents``,
``credits``, ``uploads``, ``is_subscription``. (The backend sends a
bare array; it is wrapped here because FastMCP validates tool output
against the dict annotation and rejects a top-level list.)
Inputs: no named parameters. Returns: object
list_parametersList parametersARead-onlyIdempotentInspect
List Maginary prompt-DSL parameters.
Args:
category: Restrict to one category (e.g. ``composition``, ``video``,
``model``, ``outpaint``). Call with no filters once — the response's
``categories`` / ``statuses`` maps are the full taxonomy.
status: Restrict to one status (``live``, ``mostly-dead``,
``unimplemented``).
include_reserved: When False (default) drop ``unimplemented``
(recognized-but-blocked) parameters from the result.
Returns:
A dict with ``count``, ``source`` (``live`` vs. ``bundled-snapshot``),
``categories`` / ``statuses`` (the filter taxonomy), and ``parameters``
(the array of matching entries).
Inputs: status, category, include_reserved. Returns: object
manage_api_keyManage API keyADestructiveInspect
Create, list, or revoke Maginary API keys (up to 10 per account).
Auth: pass ``email`` + ``password`` for Basic auth (onboarding), or omit
both to use the configured API key (normal operation).
Args:
action: One of ``create``, ``list``, ``revoke``.
name: Key name (required for ``create``).
key_prefix: 8-char prefix of the key to revoke (required for ``revoke``).
email: Account email (for Basic auth).
password: Account password (for Basic auth).
Returns:
For ``create``: dict with ``raw_key`` (the full key — show once, then
use ``configure_api_key`` to activate it), ``key_prefix``, ``name``.
For ``list``: dict with ``keys`` array.
For ``revoke``: success/error message.
Inputs: action (required), name, email, password, +1 more. Returns: object
search_parametersSearch parametersARead-onlyIdempotentInspect
Text-search over parameter names, aliases, descriptions, values, examples.
Args:
query: Substring match, case-insensitive.
category: Optional single-category restriction.
include_reserved: Whether to include ``unimplemented`` parameters.
Returns:
Dict with ``count``, ``source`` (``live`` vs. ``bundled-snapshot``),
and ``parameters`` (ordered as they appear in the catalog).
Inputs: query (required), category, include_reserved. Returns: object
upload_imageUpload imageAIdempotentInspect
Upload a local image and get a CDN URL for img2img or --sref.
Only available on local (stdio) connections. On hosted/remote
connections, place an existing image URL directly in the prompt.
Place the returned ``url`` in a ``generate`` prompt:
``generate("https://cdn.maginary.ai/…/photo.webp reimagine as oil painting")``
Args:
file_path: Path to an image file on disk (JPEG, PNG, WebP, HEIC).
filename: Original filename. Inferred from ``file_path`` if omitted.
Returns:
Dict with ``url`` (the public CDN URL), ``exists`` (deduplicated),
``credits_deducted``, and ``message``.
Inputs: file_path (required), filename. Returns: object
wait_for_generationWait for generationARead-onlyIdempotentInspect
Poll get_generation on a backoff until it reaches done / failed.
Args:
uuid: The UUID returned by ``generate``.
timeout_s: Return after this many seconds even if still running.
Default 45 stays under the 60 s per-call limit most MCP clients
enforce; a ``timeout`` result just means "call again". Only raise
it (e.g. for video) on clients you know allow long tool calls.
Returns:
The terminal generation record — which includes generations that
failed server-side: those are SUCCESSFUL tool calls returning
``processing_state: "failed"`` with empty ``image_urls``, so always
check the state. On tool failure, an ``isError`` result whose
``error`` field is ``"timeout"`` (``message`` names the last
observed state — the generation keeps running server-side and can be
re-fetched with ``get_generation`` later), ``"auth"``, or
``"failed"``.
**Follow-up actions:** A ``done`` generation's
``processing_result.available_actions`` maps slot indices to valid
action types — e.g. ``{"0": ["upscale_2x", "vary_strong",
"pan_left", "zoom_out_1_5x", "img2img_basic", "img2img_inpaint",
"img2vid_basic", ...],
"global": ["reroll"]}``. Use ``execute_action`` with the ``uuid``, a chosen
``action_type``, and the ``parent_image_index`` (the slot key as an
int) to run an action on a specific output image.
Inputs: uuid (required), timeout_s. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Paid AI image/video generation for agents — x402 USDC or API key, no account needed.
Create images & video from any MCP agent — 17 models, spend limits, one URL.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
AI video, image and audio generation with 140+ AI models from any MCP agent
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to analyze images and videos, and generate optimized prompts for AI video generation systems.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to generate cinematic video and image assets and perform autonomous timeline assembly, multi-track audio editing, chroma-key compositing, and local draft manipulation from conversational prompts.3MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to generate images from text prompts, list available models, and view past generation history via stdio, SSE, or Streamable HTTP transports.-
- AlicenseNot gradedqualityDmaintenanceExposes litmedia.ai text-to-image and image-to-video generation tools via MCP, enabling AI agents to generate images and videos directly from prompts.2MIT
Glama MCP Gateway
Add one secure layer between your agents and this server.