Metamorpha API

Metamorpha is an AI-driven video editor for short-form social video. You arrange layered elements — video clips, images, text, shapes — over a composition, animate them on a 30 fps keyframe timeline, and export an MP4. The editor runs in the browser; this site documents the programmatic API that drives the same projects from outside the editor.

What the API is for

Every project Metamorpha can edit in the browser, an external agent can edit over the network. The same tool catalog is exposed three ways:

• MCP — POST /mcp, a Model Context Protocol server. Point Claude Code, Claude Desktop, or any MCP client at it and the full tool catalog appears as callable tools.
• HTTP — GET /api/tools lists the catalog; POST /api/tool/<name> dispatches one tool. Plain JSON, good for curl, scripts, and CI.
• Editor LLM panel — the same catalog, wired to the in-browser prompt panel. Not a network surface; mentioned here only because it shares the catalog.

All three call the same pure dispatch layer, so behaviour is identical whichever you use. A tool call loads the project from storage, applies the change, validates it against the schema, and writes it back.

The API is built for the work a person would never click through by hand: "place 50 stars at random positions, each with a staggered fade-in", "duplicate this layer 30 times in a circle", "recolour every shape along a gradient". One described instruction, hundreds of mutations.

Connecting over MCP

Add Metamorpha to your MCP client config:

{
  "mcpServers": {
    "metamorpha": {
      "url": "https://metamorpha.app/mcp",
      "headers": {
        "Authorization": "Bearer mk_your_api_key_here"
      }
    }
  }
}

For local development against wrangler dev, point at http://localhost:8787/mcp — no auth header is needed in dev (ENVIRONMENT=development bypasses the auth gate).

Connecting over HTTP

The HTTP base URL is https://metamorpha.app.

• GET /api/tools — returns the full tool catalog as JSON (the same TOOL_DEFINITIONS the MCP server exposes).
• POST /api/tool/<name> — dispatch one tool. Body: { "projectId": "<id>", "args": { ... } }. The worker loads the project from storage, runs the tool, and writes the result back when the tool reports success.

curl -X POST https://metamorpha.app/api/tool/describe_video \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "your-project-id", "args": {} }'

Authentication

Both surfaces use the same credential: a bearer API key.

1. Sign in to the editor at metamorpha.app/app.
2. Open `/app/settings` and mint an API key. It looks like mk_… and is shown once — copy it immediately.
3. Pass it as Authorization: Bearer mk_… on every MCP or HTTP request.

Keys are revocable from the same settings page. Each key maps to your account, so a tool call sees exactly the projects you'd see in the editor. In local wrangler dev the auth gate is bypassed entirely — no key required.

Where to go next

• [Getting started](/docs/getting-started) — the describe-before-mutate workflow, element-id conventions, the coordinate system, frames vs seconds.
• [Tool reference](/docs/tools) — every tool, grouped, with signatures and worked examples.
• [Examples](/docs/examples) — end-to-end sessions you can adapt.
• [Common mistakes](/docs/common-mistakes) — the failure modes that trip up new agents.