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.
Prefer plain HTTP? The same functions are available as a REST API with the same keys — see the developer guide and /api/v1/openapi.json.
Quick start
- Subscribe — generation needs an active plan; tokens are the same as in the studio.
- 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 likeact_live_…, are shown once, and can be scoped (read,generate,upload) and revoked. - 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
get_accountPlan, token balance, limits (actors per frame, reference caps, parallel videos).list_modelsFrame and video models: enabled, default, durations, resolutions, cost, reference caps.estimate_costToken cost of a frame or a video before generating.list_actors / list_props / list_locations / search_referencesYour library: characters, objects, places — ids for references.list_projects / get_project / get_scene / list_frames / list_videosProjects, scenes, reusable frames and generated videos.upload_referenceStore an image (https URL or base64) as a frame / prop / location reference. Moderated like website uploads.create_actorSynthetic actor from a description (portrait generated), or a real person from a photo with consent + face check.verify_actorVerification status of a photo actor and a fresh face-check link (links expire within minutes).confirm_reference_peopleAfter people_found: turn the 1–2 people found in a direct image into photo actors (named, optional per person); the image attaches only when everyone is confirmed.invite_actorInvitation link bound to a photo actor for someone else to confirm consent and pass the camera check on their phone.generate_frameFirst frame of a scene from a prompt and references; waits and returns the image.generate_videoVideo from references (standalone — lands under Videos, poll get_video), from a scene or as a continuation of a finished scene inside a project (returns a job).get_job / wait_jobJob status and blocking wait with streamed progress; result links and previews.create_script_video / finish_project / stop_autorunScript → scenes → server pipeline → assembled film.generate_speech / generate_sound_effect / transcribe_audio / get_audio_asset / apply_audio_edit / list_audio_sourcesVoice lines, AI sound, captions and applying an audio edit to a video.list_recast_sources / upload_recast_video / recastRecast (video → video): motion, camera and timing from a source video, people replaced by your actors; sources are your videos or an upload by URL.generate_photo / get_photo / list_photosStandalone photos — a prompt plus references, no project needed; shown under Photos on the Videos tab.get_videoStatus of a standalone video: pipeline stage, ETA, and the final mp4 once assembled (wait: true blocks with streamed progress).generate_video_messageTalking video message (3–15 s): one actor looks into the camera and says your text verbatim; optional opening-frame prompt and voice sample. Returns videoId — poll get_video.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. A frame, prop or location image with one or two people returns error
people_foundwith apendingIdand the cut-out portraits: callconfirm_reference_peopleto create a photo actor per person, thenverify_actorfor yourself orinvite_actorfor someone else — the image becomes usable once everyone in it is verified (reference_people_unverifieduntil then). More than two people, a minor or explicit content are rejected (person_in_image/moderation_rejected). Exception:videoModelh3/h3_hq(MiniMax H3, our own GPU) takes photo actors and people in references without the face check, and its videos carry no Actoria provenance mark. - Real human faces are only allowed through verified photo actors:
create_actorwithsource: "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,wan3orwan22. - Unsaved direct assets expire in 7 days;
save_to_library: truekeeps 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). 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 — not needed with
videoModelh3/h3_hq(our own GPU). - 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