# Make Effects - Focused Agent Documentation > Durable operational context for starting with the MakeFX CLI or hosted MCP, producing image, video, and audio Assets, and recovering failed work. Use CLI help and MCP live discovery for current contracts. ## Linked reference estate - [Documentation index](https://makefx.app/docs.md) and [product overview](https://makefx.app/index.md). - [Quickstart](https://makefx.app/docs/quickstart.md), [variant review](https://makefx.app/docs/ai-media-variants.md), and [audio playbook](https://makefx.app/docs/audio-playbook.md). - [Pricing](https://makefx.app/pricing.md), [Terms](https://makefx.app/terms.md), and [Privacy](https://makefx.app/privacy.md). - [Developer portal](https://makefx.app/developers.md), [About](https://makefx.app/about.md), and [Contact](https://makefx.app/contact.md). ## Foundation --- Source: https://makefx.app/docs/concepts.md # Core Concepts Make Effects gives media generation a shared project record. The goal is simple: generate freely, compare Variants, understand how each result was made, choose the main result, and continue from exact media. ## Space A Space is a collaborative project boundary. It owns Assets, Variants, Recipes, References, Collections, chat, and real-time sync. Use one Space for a game, episode, trailer, campaign, or other project where people and agents need shared context. ## Asset An Asset is the named thing you care about: a character, scene, item, music bed, sound effect, dialogue take, animation, or reference. Assets have mutable metadata such as name and type, plus one main Variant. ## Variant A Variant is an immutable media result attached to an Asset. Variants can be images, audio files, or video files. A completed Variant stores the public media facts needed to review and reuse it. ## Recipe A Recipe records the prompt, public model, exact Variant references, and typed media-family settings used to make a Variant. Recipes let people and agents regenerate a completed result unchanged, vary it with explicit changes, or retry a failed Variant unchanged. ## Reference A Reference is an exact Variant used as generation input. It identifies what the result came from; it does not decide whether the result becomes a new Asset or a sibling Variant. ## Collection A Collection is ordered, mutable organization. It may contain Assets or exact Variants. Collection membership does not change media or Recipe References. ## Actions - Generate creates a new Asset. - Regenerate replays a completed Recipe unchanged; Vary creates a sibling with deliberate changes. - Retry repeats only a failed Variant in place. - Activate explicitly chooses the main Variant. - Copy creates a new Asset from existing media without generation. - Update changes mutable metadata or Collection ordering. - Delete is permanent; there is no trash or restore. Regenerate keeps the current main Variant while work is running. On success, the sibling becomes main only if nobody selected another Variant after submission. Failure never changes the selection. Retry keeps both the Variant identity and Recipe unchanged. ## Shared state The authoritative Space state is shared by the web app, MakeFX CLI, and hosted MCP server. Agents should use the CLI or MCP instead of internal databases, storage, or execution APIs. Apply these concepts in [the reproducible media record](/docs/reproducible-ai-media), or follow [the Variant review and selection workflow](/docs/ai-media-variants). ## Interfaces --- Source: https://makefx.app/docs/web-workspace.md # Web Workspace Use the web app when people need to see the media, compare actual results, make the selection, organize the Space, or collaborate. The CLI and MCP operate on the same state; changes appear across all three interfaces. ## Review a Space Open a Space to see its Assets on the full-screen canvas. Search by Asset name, open an Asset to compare its Variants, and open Variant details to inspect its prompt, Recipe, References, status, and media facts. The main Variant represents the Asset on the Space canvas. From a completed non-main Variant, choose **More → Use as main variant** to change that selection explicitly. ## Continue or replay a Variant Use **Vary…** to restore a completed Variant's Recipe in Forge and change its prompt, model, References, or media settings. Vary creates a sibling Variant in the same Asset. Use **More → Regenerate unchanged** to run the exact Recipe again without opening Forge. Use **Fork into new Asset** to restore and edit the Recipe while branching into a new Asset. Use **Derive new Asset** when the selected Variant should become an explicit input to a new Recipe. Use **Copy to new Asset** for the same media bytes and no provider call. A failed Variant remains visible. Use **Retry** when the same Recipe should run again unchanged. If the creative instruction or settings should change, start Vary from a completed Variant instead. Generation started through the CLI or MCP appears in the same Space canvas and generation tracker as Web work. The durable Asset, Variant status, and Recipe are the source of truth; the browser that started a run does not need to remain open. ## Inspect history Open **Variant details → History** to see exact input Variants and the Regenerate, Vary, Fork, and Copy origin and descendant groups. **View full history** loads the bounded ancestor and descendant graph. Relationships are read-only facts derived from Recipes, not editable canvas connectors. ## Organize the Space Type and Recent are automatic views: they always reflect the Space and are not editable containers. Collections are saved, user-curated sets. An Asset stays in its automatic view and may belong to more than one Collection. Use the folder action on an Asset to add or remove it from a Collection without leaving the canvas. For many Assets, enter selection mode, narrow the Space with search, choose **Select all matching**, then apply one Collection action. Drag an Asset onto a visible Collection for the direct-manipulation shortcut. Open **Collections** to create, find, rename, show, hide, or delete Collections. This compact panel manages Collections themselves rather than loading every Asset into a separate organizer. Collection changes do not alter media, Recipes, or References. ## Copy, update, and delete Use **Copy to new Asset** from Variant details to create a new Asset from the selected media without generation. Renaming an Asset changes its mutable metadata without creating a Variant. Asset and Variant actions can also copy their stable public references for use in the CLI, MCP, or another collaborator's message. Asset and Variant actions expose permanent deletion for eligible objects. There is no trash: - activate another completed Variant before deleting the current main Variant; - delete the Asset to remove its only Variant; - deleting a Collection keeps the Assets it organized; - deleting a Space removes the complete Space and its stored media. Destructive actions require confirmation and current permission. ## Choose another interface Use the [CLI](/docs/cli) for terminal automation and local file transfer. Use [MCP](/docs/mcp) for structured agent operations. See [Core Concepts](/docs/concepts) for the shared product model. --- Source: https://makefx.app/docs/cli.md # CLI Reference The CLI operates on the same Spaces, Assets, Variants, Recipes, References, Collections, Drafts, Bindings, canvas organization, and permissions as the web app. Use it for terminal automation and caller-local file upload or download. Commands follow `noun verb`. Assets and Variants use compact references: ```text asset:name~prefix asset:name~prefix@variant ``` Run `makefx --help` or `makefx --help` for the authoritative commands, flags, model choices, and output options. ## Start Install the canonical [makefx package on npm](https://www.npmjs.com/package/makefx): ```bash npm install -g makefx makefx login makefx spaces create "My Game" --init makefx spaces current --json makefx models list --available ``` ## Generate Generate creates a new Asset: ```bash makefx image generate "A painted market" \ --name "Market" --type scene -o market.png makefx video generate "A slow push through the market" \ --name "Market Push" --type animation -o market.mp4 makefx audio music generate "Warm acoustic theme" \ --model eleven-music --name "Theme" -o theme.mp3 ``` ## History and continuation Inspect typed parents and descendants, or continue one exact Variant: ```bash makefx variants history makefx image derive "Same character, winter clothes" \ --refs --name "Winter hero" --type character -o winter.png makefx variants fork --name "Hero branch" \ --changes "Keep everything; make the expression slightly happier" --wait makefx variants copy --name "Hero copy" --type character ``` Derive creates a Recipe from exact inputs. Fork edits a restored Recipe and runs it into a new Asset. Copy duplicates exact media without a provider. Generate accepts no inputs. Upload local files before deriving. ## Regenerate, Vary, Retry, and Activate Regenerate a completed Variant to replay its Recipe unchanged: ```bash makefx image regenerate --wait ``` Vary when the sibling should be subtly different: ```bash makefx image vary "Warmer light" --wait ``` Both add a sibling Variant to the same Asset. Vary patches the restored Recipe; Regenerate does not. The result becomes main by default; use `--no-activate` to keep the current one. Retry only a failed Variant whose Recipe must stay unchanged: ```bash makefx variants retry makefx variants show --wait ``` Choose a completed result explicitly: ```bash makefx variants activate ``` ## Files and organization ```bash makefx assets upload hero.png --name "Hero" --type character makefx assets download -o hero.png makefx collections add ``` ## Plan a Draft chain Drafts plan generation without running it. Create Drafts, then bind one output to another Draft's input: ```bash makefx drafts create "Character" --media image \ --generator image/pro \ --recipe '{"operation":"generate","assetType":"character","prompt":"Paint the character"}' \ --destination new_asset makefx drafts create "Character Motion" --media video \ --generator video/seedance-2-frame \ --recipe '{"operation":"generate","assetType":"animation","prompt":"Animate the character walking into frame"}' \ --destination new_asset makefx bindings set start_frame_variant_ref \ --source draft-output --ref makefx collections pin --x 240 --y 120 makefx spaces lens type ``` Reuse a completed Variant's Recipe and exact-Variant references: ```bash makefx drafts create --from --name "Next hero pass" ``` It creates a new Asset by default; `--destination sibling` targets the source. ## Run an approved workflow An agent can plan a speech Draft, bind its output into an alignment Draft, and bind the aligned result into a video Draft. It then requests one human checkpoint through MCP: ```text graph_run({ space_id: "", draft_refs: ["", "", ""], request_id: "dialogue-scene-07", include_upstream: true, require_approval: true }) ``` The canvas shows the pending graph-run summary. Approving it runs the exact request in dependency order; rejecting it starts no generation. The agent polls `graph_run_status` with the compact run reference after approval. Each completed Draft produces an ordinary Variant with its resolved References, Recipe and ordered Reference receipt. The equivalent CLI workflow is: ```bash makefx drafts run makefx graph run --upstream --wait makefx graph status --json ``` ## Permanent deletion ```bash makefx variants delete --yes makefx assets delete --yes makefx spaces delete --yes ``` There is no trash. Activate another Variant before deleting the current one; delete the Asset to remove its only Variant. ## Automation Prefer `--json` where help advertises it. Persist returned compact references, read accepted Variants until terminal, and do not repeat media creation merely because a local wait ended. --- Source: https://makefx.app/docs/mcp.md # 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 ```bash 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 . 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: ```text 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: ```text list_models({media_kind: "image", operation: "generate", available_only: true}) get_model({model: "pro"}) generate_image({ space_id: "", name: "Market", asset_type: "scene", prompt: "A painted market at dusk", model: "pro" }) get_variant({space_id: "", variant_ref: ""}) activate_variant({space_id: "", 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](https://makefx.app/docs/ai-media-variants.md) and [reproducible media records](https://makefx.app/docs/reproducible-ai-media.md) 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. ## Models --- Source: https://makefx.app/docs/model-and-parameter-selection.md # Model & Parameter Selection Discover models from the live account-aware catalog: ```text list_models({media_kind: "video", operation: "generate", available_only: true}) → get_model({model: "seedance-2"}) ``` In the CLI: ```bash makefx models list --media video --available makefx models show seedance-2.5 makefx models configure seedance-2.5 --provider elevenlabs ``` `get_model` and `models show` describe typed generate and regenerate inputs, defaults, reference limits, current availability, and provider choices when a model has equivalent routes. Use the public model slug exactly as returned. Provider choice is normally an account setting. Configure it once with `models configure` or MCP `set_model_default_provider`; omit the provider while generating. A generation request may still supply the model's advertised `provider` input as a one-run override. Resolution is explicit override, then account default, then catalog default. Make Effects does not silently switch to another provider when the selected route is unavailable, because the selected provider determines credentials and billing. Choose the media family first, then the model, then only parameters advertised for that operation. Regeneration has its own typed schema because it inherits a source recipe and accepts only meaningful overrides. Availability means the account can currently select the model; it is not a price, quota, or success guarantee. ## Workflows --- Source: https://makefx.app/docs/image-playbook.md # How do you keep an AI-generated character consistent across images? Choose one completed character result as the reference, then reuse that exact Variant instead of describing the character again from memory. Keep each derived scene's Recipe and exact References beside its media; compare sibling Variants for drift; and explicitly select the Variant that represents the Asset. This gives every attempt a stable visual input and a traceable decision, although reference-conditioned generation can reduce drift rather than eliminate it. ## What should become the character reference? Start with a clean result whose identity, clothing, proportions, and props are suitable for reuse. Compare sibling Variants and select the one that represents the character Asset. The public [Night Market recorded session](/#showcase) shows **Mara the Lantern-Keeper** as one Asset with three completed Variants; `4904331f` is main. ![Selected Mara Variant from the recorded session](/showcase/4904331f-1c34-416f-b7db-7f242412fe17-inspect.webp) ## How do you reuse that exact Variant in a scene? The session passed Mara's exact selected Variant, a lantern Variant, and the selected market-square Variant into **Lantern Lighting — vignette**: ```sh makefx image derive --refs asset:mara-the-lantern-keeper~0f4af497@4904331f,asset:the-brass-lantern~de879414@f677a830,asset:night-market-square~ef239e5a@58d45f21 --name "Lantern Lighting — vignette" --type composite "Mara reaches up to hang her glowing brass lantern on a stall post, warm light spilling over wet cobblestones and nearby faces" ``` ```text ✓ asset:lantern-lighting-vignette~a36ccfb1@8de24c27 · 3 references ``` ![Derived vignette from three exact recorded References](/showcase/8de24c27-38eb-4ab3-a59a-266751215cda-inspect.webp) The result's Recipe retains the prompt and ordered References, which compute the input graph from all three source Variants. The compact loop is: generate character → compare siblings → Activate the main result → reference that exact Variant in a new Asset → inspect and select the result. ## What should you do when the character drifts? A Reference is evidence for the model, not a pixel lock. Faces, hands, clothing, pose, lighting, and composition can still move. Compare every result with the selected character; Vary one deliberate change at a time and state what must stay fixed. Read [Core Concepts](/docs/concepts) for the record, [Model & Parameter Selection](/docs/model-and-parameter-selection) for current reference inputs, or the [video consistency workflow](/docs/video-playbook) for motion. [Start the MakeFX quickstart](/docs/quickstart) to use this loop with your own media. --- Source: https://makefx.app/docs/video-playbook.md # How do you keep characters and scenes consistent across AI video shots? Select an image Variant that already has the right character, scene, and composition; use that exact Variant as the video keyframe Reference; then compare completed video Variants and select the main clip. Preserve the image and video Recipes and exact References so the shot remains connected to its source. Reference-conditioned generation reduces identity and scene drift, but it cannot guarantee identical pixels, timing, or motion between shots. ## Why should the image keyframe come first? A cold video prompt asks the model to invent identity, composition, and motion together. A selected image settles the visible starting point first. The public [Night Market recorded session](/#showcase) uses Mara image Variant `4904331f` as the exact Reference for **Mara — idle loop**. ![Selected Mara image keyframe](/showcase/4904331f-1c34-416f-b7db-7f242412fe17-inspect.webp) ## What does the image-to-video handoff look like? ```sh makefx video derive --refs asset:mara-the-lantern-keeper~0f4af497@4904331f --name "Mara — idle loop" --type animation "Subtle idle animation: steady rain, warm lantern flicker, gentle breathing and blinking; camera locked, motion returns to the starting pose" --model veo-3.1 --tier fast --duration 8 --resolution 1080p --aspect 16:9 ``` ```text ✓ asset:mara-idle-loop~7d22189e@3828d140 · 8s video · $0.96 ``` ![Poster from the derived Mara idle-loop video](/showcase/3828d140-b39e-4177-a825-0f6447d25abb-poster.webp) The completed video keeps its motion Recipe and exact image Reference back to Mara. The compact workflow is: select image → generate video from its exact Variant reference → compare sibling clips → Activate the strongest completed clip. ## What can still drift between shots? An image Reference constrains the starting evidence, not every frame. Facial detail, props, motion, camera paths, lighting, timing, and audio can vary. Even “return to the starting pose” does not guarantee a perfect loop. Inspect the full clip, not only its poster. Vary deliberate changes as siblings; the current main stays selected while work runs, and failure does not replace it. Build the keyframe with the [image consistency workflow](/docs/image-playbook), inspect current inputs in [Model & Parameter Selection](/docs/model-and-parameter-selection), and review the record in [Core Concepts](/docs/concepts). [Start the MakeFX quickstart](/docs/quickstart) to run the human selection loop. --- Source: https://makefx.app/docs/reproducible-ai-media.md # How do you track prompts, references and versions for AI-generated media? Track each durable creative object as an Asset with sibling Variants, not as a folder of loosely named files. For every generated Variant, retain its typed Recipe, prompt, settings, and exact ordered input References; then explicitly select the main Variant that currently represents the Asset. This record works across images, video, and audio, and it preserves both unsuccessful directions and the chosen handoff without pretending that the same inputs guarantee identical media. ## Why is saving the prompt alone insufficient? A prompt omits the exact inputs, typed settings, operation, output, and selection. A complete record answers: what Asset was made; which Variant resulted; what its Recipe requested; which exact Variants were References; and which Variant is main. [Core Concepts](/docs/concepts) defines each term. ## What does a complete creative record look like? The public [Night Market recorded session](/#showcase) is backed by shipped replay data. Its ten Assets include images, audio, and a derived video: | Record | Visible evidence | |---|---| | Variants and selection | Mara has three completed Variants; `4904331f` is main. | | Recipe and References | The vignette stores its prompt and three ordered exact References. | | Computed Reference graph | Three Recipe Reference edges lead to the vignette; Mara also leads to the video. | | Cross-media work | The rain effect and theme retain audio Recipes; the idle loop retains a video Recipe. | ![Composite with three exact References in its stored Recipe](/showcase/8de24c27-38eb-4ab3-a59a-266751215cda-inspect.webp) ## How do you capture the record during production? Generate an Asset; inspect the completed Variant's Recipe and References; Regenerate unchanged replays or Vary deliberate changes as siblings; Retry only an unchanged failed Variant; compare the media and Activate the selected result; then use exact Variant references for dependent Assets. The Recipe is the immutable receipt, and its ordered References compute the input graph. The recorded video used `asset:mara-the-lantern-keeper~0f4af497@4904331f` and returned `asset:mara-idle-loop~7d22189e@3828d140`. Those compact references connect two distinct Recipes and results. ## Does this make generation deterministic? No. The record makes work inspectable and reusable; it does not guarantee identical pixels, frames, motion, or audio. Keep the exact completed media as evidence and compare new siblings against it. Use the [CLI guide](/docs/cli) or [MCP guide](/docs/mcp) to inspect the shared record, and the [audio playbook](https://makefx.app/docs/audio-playbook.md) for medium-specific work. Then read [how Variant selection works](/docs/ai-media-variants), or [follow the quickstart](/docs/quickstart) to create the first tracked Asset in a Space.