Skip to main content
Glama

Server Details

AI image + video generation for agents: --flag prompt DSL, async generate/poll, x402 pay-per-use.

If you are the author of this connector, you can claim ownership by verifying the domain or GitHub account it belongs to. Claimed connector authors can inspect health checks, view analytics, and manage their listing.
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

A4.2/5.0

Scored across 16 tools

Disambiguation4/5

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).

Naming Consistency5/5

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.

Tool Count4/5

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.

Completeness4/5

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 tools
check_account_statusCheck account statusA
Read-onlyIdempotent
Inspect

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 keyA
Idempotent
Inspect

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 accountA
Destructive
Inspect

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 balanceA
Read-onlyIdempotent
Inspect

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 generationA
Read-onlyIdempotent
Inspect

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 parameterA
Read-onlyIdempotent
Inspect

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 productsA
Read-onlyIdempotent
Inspect

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 parametersA
Read-onlyIdempotent
Inspect

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 keyA
Destructive
Inspect

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 parametersA
Read-onlyIdempotent
Inspect

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 imageA
Idempotent
Inspect

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 generationA
Read-onlyIdempotent
Inspect

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

    Related MCP Servers

    Try in Browser

    Glama MCP Gateway

    Add one secure layer between your agents and this server.