MCP standard generation workflow

Availability gate

The official MCP is live in public beta at https://api.animgen.com/mcp. Complete client setup with OAuth and a verified AnimGen account. A connection or model query does not approve a paid generation.

1. Discover models

Call list_models with an empty argument object. Select an actual returned model ID and supported settings. Do not assume all models accept last frames, reference images, negative prompts, seeds, or the same duration and ratio.

2. Transfer a local image

A local path is not an ImageInput. The upload bridge has three distinct steps:

1. Call prepare_image_upload with filename, mime_type, and the exact byte_size.
2. Send the actual bytes with the returned HTTP method, upload_url, and headers, before expires_at. This transfer is performed by an authorized client capability, not by supplying a path to MCP.
3. Call complete_image_upload with upload_id. Use its returned file_id in the generation request.

Do not add your MCP token or API key to an upload destination. Use only the headers returned for that upload. Treat upload URLs as sensitive. If your client cannot upload bytes, use a supported approved client capability, a permitted public HTTPS image, or inline Base64 within the image limits; do not pretend upload succeeded.

3. Construct the request and quote it

The following is the argument shape for quote_animation. The UUID is a placeholder; replace it with a completed upload's file_id. Set the model and its valid options for a real request.

{
  "request": {
    "input": {
      "first_frame": {
        "type": "file",
        "file_id": "00000000-0000-4000-8000-000000000001"
      }
    },
    "prompt": "A character runs in place, side view, fixed camera.",
    "selection": {"mode": "full"},
    "export": {
      "output_formats": ["frames_zip"],
      "frame_count": 24,
      "output_width": 512,
      "output_height": 512
    }
  }
}

The result includes quote_id, credits, breakdown, and expires_at. Quoting does not start generation. Explain the intended output and cost to the user and obtain approval before moving on.

4. Generate only after approval

Call generate_animation with the same request, a persisted idempotency_key, and the approved quote_id and/or max_credits. These three fields are tool arguments beside request, not fields inside it.

Use both a fresh quote and a maximum when appropriate. The maximum must come from the user's approval, not from an amount the AI invents. Read spending safeguards before implementing retries.

Persist the returned task ID. A returned task is asynchronous, not a completed download.

5. Poll to a terminal state

Call get_animation with animation_id. Use a bounded polling interval (start around five seconds) and a deadline. Tool results are structured JSON; do not assume the MCP transport exposes the API's HTTP Retry-After header.

Keep polling during queued, running, or cancelling. Stop at succeeded, failed, or cancelled. Inspect outputs even after failure: a source video may exist when export fails.

6. Download actual bytes

For each usable asset, call download_asset with asset_id. It returns asset metadata and a signed download URL; it does not automatically save a local file.

Use an approved client download capability without forwarding OAuth or API credentials. Save the file privately and report its local location or an appropriate user-facing attachment, not the raw signed URL. Refresh metadata with download_asset if the URL expires.

If a task needs cancellation, call cancel_animation with its animation_id, then poll. Cancellation is best effort and does not imply a full refund.