Model Context Protocol

Actoria MCP server

Generate AI videos with your own consistent actors from Claude Code, Claude.ai, Cursor or the Claude API. The MCP server exposes the same generation pipeline as the Actoria studio: first frames, Seedance 2.5 / MiniMax H3 / Wan 3.0 videos, scripts, speech and sound — with your library of actors, props and locations, or with images you pass directly.

Quick start

1. Subscribe — generation needs an active plan; tokens are the same as in the studio.
2. Add the server by URL: https://actoria.ai/mcp. Claude.ai, Claude Code, ChatGPT and Cursor open the Actoria sign-in themselves (OAuth 2.1 with PKCE; clients register through Client ID Metadata Documents or Dynamic Client Registration) — no key to paste. For scripts and the Claude API, create an API key at Settings → API & MCP: keys look like act_live_…, are shown once, and can be scoped (read, generate, upload) and revoked.
3. Ask: “List my actors and make a 16:9 frame of Mia on a rainy street, then animate it for 5 seconds with Seedance.”

Claude.ai / Claude Desktop

Add to Claudeopens Claude with the connector pre-filled; press Add, then Connect and sign in to Actoria. Manually: Customize → Connectors → Add custom connector → URL https://actoria.ai/mcp. Manage or disconnect the app under Settings → Connected apps. Organizations with the request-headers beta can instead add the header Authorization: Bearer act_live_….

Claude Code

claude mcp add --transport http actoria https://actoria.ai/mcp
# then in Claude Code: /mcp → actoria → Authenticate (opens the Actoria sign-in)

With an API key instead of OAuth (CI, shared machines):

claude mcp add --transport http actoria https://actoria.ai/mcp \
  --header "Authorization: Bearer act_live_…"

.mcp.json (project scope)

{
  "mcpServers": {
    "actoria": {
      "type": "http",
      "url": "https://actoria.ai/mcp",
      "headers": { "Authorization": "Bearer ${ACTORIA_API_KEY}" }
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "actoria": { "url": "https://actoria.ai/mcp" }
  }
}
// Cursor opens the Actoria sign-in (OAuth). API key alternative:
// "actoria": { "url": "https://actoria.ai/mcp", "headers": { "Authorization": "Bearer act_live_…" } }

ChatGPT (Developer mode)

Settings → Apps & Connectors → Advanced settings → Developer mode → Create. MCP server URL https://actoria.ai/mcp, Authentication: OAuth(ChatGPT registers itself — dynamic client registration and client ID metadata documents are both supported; a pre-issued client ID and secret also work). Connect, sign in to Actoria and allow access. The app then appears in the composer under Developer mode.

Claude API (MCP connector)

{
  "betas": ["mcp-client-2025-11-20"],
  "mcp_servers": [{ "type": "url", "url": "https://actoria.ai/mcp", "name": "actoria", "authorization_token": "act_live_…" }],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "actoria" }]
}

Tools

References: saved or direct

Every generation tool takes the same references list. Use ids from your library, assets from upload_reference, your own frames, or pass an image directly by https URL or small base64:

references: [
  { "type": "actor", "id": "act_…" },                       // saved actor (list_actors)
  { "type": "prop", "id": "prp_…" },                        // saved prop
  { "type": "location", "id": "loc_…" },                    // saved location (one per scene)
  { "type": "asset", "id": "ast_…" },                       // from upload_reference
  { "type": "frame", "sceneId": "scn_…", "which": "last" }, // continue from your own frame
  { "type": "url", "url": "https://…/product.png", "kind": "prop", "name": "red sneaker" },
  { "type": "base64", "data": "…", "kind": "frame" }        // ≤ 3 MB, no people
]

• Direct images are moderated exactly like website uploads. Frames must contain no people; props and locations must contain no people either.
• Real human faces are only allowed through verified photo actors: create_actor with source: "photo" and consent — the person passes a camera check, then the actor becomes usable.
• Limits per model: up to 3 actors for 16:9 (2 otherwise); reference caps — frame 5, Seedance 8, H3 9, Wan 3 10.
• Seedance 2.5 / 2.0 / Lite animate only frames of their own origin; for uploaded frames use seedance_15, h3, wan3 or wan22.
• Unsaved direct assets expire in 7 days; save_to_library: true keeps a prop or location permanently.

Recast: video → video

recast takes the motion, camera and timing from a source video and replaces the people in it with your actors (up to 4, in order of first appearance), optionally featuring props and a location. Sources are your own finished videos (4–30 s) or a clip you upload by URL with upload_recast_video (you must hold the rights and the consent of the people in it; their faces are blurred before anything leaves Actoria). Seedance 2.5 handles up to 30 s, 2.0 and Lite up to 15 s; the price is per second of the source — check estimate_cost with kind: "recast". Recast jobs (v2v_…) are polled with the same get_job / wait_job.

Jobs and progress

Frames take 10–60 seconds (generate_frame waits by default and returns a preview). Videos take 1–15 minutes: generate_video returns a job — poll with wait_job, which streams progress and returns links to the mp4 and a poster preview. Failed jobs refund their tokens automatically.

Pricing and limits

Same tokens as the studio — see plans and per-second video prices; estimate_cost tells the exact cost before you spend. Rate limits: 60 requests per minute per key, 10 generations per minute per account; request bodies up to 8 MB.

Security

• Keys are hashed at rest and work only on the MCP endpoint; revoke them any time in Settings.
• Scopes limit what a key can do; a read-only key can never spend tokens.
• OAuth apps get short-lived access tokens with rotating refresh tokens and PKCE (S256). Self-registered clients are shown on the consent screen by their verifiable identity (the host of their client ID document) together with the address you will be sent back to; disconnect any app in Settings → Connected apps.
• Image URLs are fetched with SSRF protection (public https hosts only) and every image is moderated.
• Every call is logged (tool, outcome, job) for 30 days for support and abuse prevention.

FAQ

Do I need a subscription?

Reading your library works without one; any generation requires an active plan and tokens.

Can I use my own photos?

Yes for objects, places and first frames (without people). For a real person, create a photo actor and pass the face check.

Which models are available?

Call list_models: Seedance 2.5 / 2.0 / Lite / 1.5, MiniMax H3 (with DLSS HQ), Wan 3.0 and Wan 2.2 for video; Nano Banana, Seedream, Krea2, Qwen for frames. See Seedance and Wan 3.

Where do the files live?

In your Actoria account: projects, scenes and the Repository — everything made over MCP is visible in the studio and vice versa.

Endpoint: https://actoria.ai/mcp · Streamable HTTP, MCP 2026-07-28 (2025-era clients supported) · OAuth 2.1 metadata: /.well-known/oauth-authorization-server (PKCE S256, DCR at /api/oauth/register, CIMD) · Support