Documentation

MCP Setup & Agent Guide

MakeFX exposes a remote Streamable HTTP MCP server at https://makefx.app/mcp. It operates on the same Spaces, Assets, Variants, Recipes, References, Collections, Drafts, Bindings, canvas organization, and permissions as the web app.

Use MCP for structured agent work. Use the MakeFX CLI when an operation needs a caller-local file.

Connect

claude mcp add --transport http makefx https://makefx.app/mcp

Complete browser OAuth when prompted. MCP uses makefx:read, makefx:write, makefx:generate, and makefx:delete; Space roles independently authorize the selected Space. Connectors initially request makefx:read; selected write, generation, or deletion tools request their action scope as a step-up. Existing tokens with all four scopes remain valid, and omitted action scopes are never silently granted.

OAuth discovery is /.well-known/oauth-protected-resource; the /mcp-suffixed path is an identical compatibility alias.

Official Registry identity: app.makefx/make-effects. Its published metadata is also available directly at https://makefx.app/server.json.

After connecting, call tools/list. Its live schemas are authoritative. Use list_models and get_model to choose a public model and read the typed inputs available for the intended operation.

Protocol negotiation

The same URL supports legacy 2025-06-18 and stateless 2026-07-28. Modern clients use server/discover; clients declaring io.modelcontextprotocol/tasks receive a durable Task and poll tasks/get using pollIntervalMs. Other clients receive ordinary variant_ref, asset_ref, and status results and continue with get_variant. Polling cadence is server-owned.

Product references

An Asset reference identifies the durable creative object. A Variant reference identifies one exact result:

asset:name~prefix
asset:name~prefix@variant

Use exact Variant references for Derive, Regenerate, Fork, Copy, activation, and completed media. get_asset returns each Variant's Recipe plus typed direct parents and children. get_variant_history computes a larger bounded ancestor/descendant view from those immutable Recipes.

Agent workflow

  1. Discover the live tool and model schemas.
  2. Find or create a Space.
  3. Inspect existing Assets and exact Variants.
  4. Choose the exact continuation verb: Generate, Derive, Regenerate, Fork, Copy, or failed-only Retry.
  5. Read the returned Variant until it is completed or failed.
  6. Inspect the result and activate the chosen Variant.
  7. Organize the Asset or exact Variant in Collections.

Without the negotiated Tasks extension, every generation, regeneration, and retry tool returns the same durable resume fields: variant_ref, asset_ref, and status. A queued or running response also includes the server-owned next_poll_seconds hint. MCP clients should wait for that interval and call get_variant with the returned reference.

Example:

list_models({media_kind: "image", operation: "generate", available_only: true})
get_model({model: "pro"})
generate_image({
  space_id: "<space-id>",
  name: "Market",
  asset_type: "scene",
  prompt: "A painted market at dusk",
  model: "pro"
})
get_variant({space_id: "<space-id>", variant_ref: "<returned-variant-ref>"})
activate_variant({space_id: "<space-id>", variant_ref: "<chosen-variant-ref>"})

The live schema, not this example, owns optional fields and current limits.

Continuation verbs

  • Generate creates a new Asset without Variant inputs.
  • Derive generates a new Asset from one or more exact Variant inputs. Use derive_image or derive_video; reference-backed work is never Generate.
  • Regenerate replays a completed Variant's Recipe as a sibling Variant of the same Asset, with optional changes.
  • Fork replays a completed Variant's editable Recipe into a new Asset.
  • Copy creates a new Asset that reuses the exact completed media and starts no generation.
  • Retry reruns a failed Variant unchanged and preserves its identity.
  • Activate selects which existing Variant represents its Asset; it creates nothing.

All generation-starting tools return compact asset_ref and variant_ref resume handles. History returns compact Variant refs for available nodes and response-local history:N node refs for unavailable historical nodes; raw database identifiers and storage keys are never exposed.

drafts_create accepts optional bindings without running. Pass a completed exact from_variant_ref to map its Recipe and references into exact-Variant Bindings; name and destination_kind override mapped defaults. drafts_get reads one Draft with Binding broken/broken_reason and latest run Variant.

Call drafts_run with stable request_id. If queued/running, wait next_poll_seconds and replay the same pair; it returns current status and Variant without another run.

Graph approvals

For an approved Draft graph, call graph_run with require_approval: true and a stable request_id; no generation starts until a human decides in the web Space. Poll graph_approval_status, then poll its returned run_ref with graph_run_status. Rejection starts nothing. graph_cancel affects only pending or blocked work, never provider work already in flight.

Activation, organization, and deletion

Activation is first-class because choosing the result that represents an Asset is a deliberate product decision.

The public guides to Variant comparison and reproducible media records show how that decision connects to Recipes and References.

Collections support ordinary create, read, update, and delete behavior plus ordered Asset or exact-Variant membership. Moving work between Collections is expressed by removing one membership and adding another.

Deletion is permanent. Owners may delete Spaces, Assets, and eligible terminal Variants. Activate another Variant before deleting the current one; delete the Asset to remove its only Variant.

Local files

MCP import preparation returns a one-use URL and exact authorization header so media bytes stay outside model context. Use the CLI for caller-local files.

Call get_variant to obtain a fresh authenticated link and resource_link for a completed Variant. Call get_variant again when the link expires; do not repeat media creation.

Recovery

  • Correct invalid inputs rather than repeating them unchanged.
  • Refresh tools/list, list_models, and get_model when remembered schemas disagree with the server.
  • Read an accepted Variant again after disconnect.
  • Use Retry only for an unchanged failed Variant.
  • Use typed Regenerate operations for a new creative direction.

Errors include stable codes, safe messages, and retryability where applicable. Provider credentials, storage details, raw upstream responses, and internal identifiers never appear in public output.