# 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 <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:

```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: "<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](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.