Motion through MCP

Connect your AI agent to Motion through the Model Context Protocol (MCP). New video jobs use the default returned by engine discovery for your account. Existing chats keep their engine. The MCP server is guarded by an OAuth 2.1 authorization server, and agents can generate videos, manage automations and credentials, and open checkout links for credits. In hosts that support MCP Apps (including ChatGPT Apps), tools also render interactive widgets inline — a live video that updates itself and a plans/upgrade panel (see Interactive widgets). For the ChatGPT-specific app setup flow, see ChatGPT App. For Claude, see Motion for Claude. Its connector supports code-based motion graphics with Motion medium and OAuth sign-in. Generative-media features and billing tools are available in the Motion app.

Create and edit a video

Ask your connected agent to create a video. It can call create_video with only a prompt:

{"prompt":"Create a 20-second launch video for our calendar app"}

Ask for “Motion with high effort” to send engine: "motion", effort: "high". Your agent can call list_engines to see the choices available to your account. GVA availability follows your account’s engine access. New jobs use your account’s configured default. Ask for “GVA Standard” to use engine: "gva", effort: "standard", or “GVA Extended” to use engine: "gva", effort: "extended". Motion Legacy requires an eligible account; read engine discovery before choosing it. Use list_engines to discover account-accessible engines and efforts, and list_templates to discover templates for the selected engine. Follow-ups keep their project engine. Existing connections and tool names remain valid. Use engine: "motion" with effort for Motion; MCP schemas do not expose REST’s deprecated mode input. Full engine and compatibility guide.

Connector profiles

Each profile advertises its supported engines and effort levels. Authentication, templates, and optional tools depend on the connector and your account access.

Profile	How to connect	Available capabilities
Full or directory	`https://mcp.motion.so/mcp`	Video creation, revisions, discovery, uploads, automations, and account/billing tools according to the server profile and scopes
OpenAI	`https://mcp.motion.so/mcp/openai`	Video tools, automations, and sponsored generation; no billing tools on the OpenAI profile
Muse	`https://mcp.motion.so/mcp/muse`	Video tools and automations within the connected profile’s engine and scope limits
Claude	`https://mcp.motion.so/mcp/anthropic`	Code-based motion graphics with Motion medium, chat reads, saved exports, and code-based automations; OAuth required; no generative-media or billing tools

Read the connected server’s tool schema before sending optional inputs. A connector’s OAuth grant does not grant engine access. Account access rules.

Endpoints

What	URL
MCP server	`https://mcp.motion.so/mcp`
Protected resource metadata (RFC 9728)	`https://mcp.motion.so/.well-known/oauth-protected-resource`
Authorization server metadata (RFC 8414)	`https://mcp.motion.so/.well-known/oauth-authorization-server`
JWKS	`https://mcp.motion.so/oauth/jwks`
Device verification (for humans)	`https://motion.so/device`

Ways to connect

Adding https://mcp.motion.so/mcp with no credential returns 401 with an RFC 9728 WWW-Authenticate challenge, so a compliant MCP client runs the OAuth flow automatically. You don’t need an API key.

1. Authorize in the browser (default)

Add https://mcp.motion.so/mcp as a custom connector. The agent registers itself (Dynamic Client Registration) and starts the OAuth flow; you authorize in a browser window and create a Motion account if you’re new, and approve the requested scopes. The agent receives a token and acts as you, using your credits. No API key. Native clients such as Cursor can use their app callback for the redirect; Motion accepts Cursor’s cursor://anysphere.cursor-mcp/oauth/callback callback during Dynamic Client Registration. Agents that can’t open a browser use the device flow (below): you approve at https://motion.so/device.

2. Register with a user or agent email

An agent must supply an email address it can verify. If it does not have one, it should ask the user for an account email before registering. An existing email uses its existing Motion account, including its projects and credits. Discover account_registration_endpoint and account_verification_endpoint at /.well-known/oauth-authorization-server. If registration is unavailable, use browser authorization or the device flow below.

POST https://mcp.motion.so/oauth/accounts/register
Content-Type: application/json

{ "name": "my agent", "email": "agent@example.com" }

A 202 response means email verification is required; it contains no credentials. Read the verification email and copy its confirmation link without opening it. Opening the link consumes the proof. Submit that link to the returned verification endpoint:

POST https://mcp.motion.so/oauth/accounts/verify
Content-Type: application/json

{ "name": "my agent", "email": "agent@example.com", "confirmation_url": "<link from the email>" }

You can instead supply token for an email code or token_hash for a raw confirmation hash. Supply exactly one verification method. After successful verification, the response contains an api_key shown once. Store it securely and connect with Authorization: Bearer <api_key>. This key has full access to the account at the verified email. Sign in with that email to manage API keys, projects, credits, and billing. If the proof expires or key creation fails, request a new verification email. purchase_credits returns a checkout link that the user completes in their browser. Subscription and automatic top-up changes also require the user to review and save them in Motion billing. New service accounts are no longer created. Existing service-account credentials remain usable, including secret rotation and revocation. The old public /oauth/service-accounts/register URL now requires an email and follows the same verification flow; it no longer returns client credentials.

3. API key (fallback)

If browser authorization isn’t available, you prefer a key, or you’re wiring up runs directly against your account, create an API key (Settings → API) and set it as the connector’s API key / bearer token:

Authorization: Bearer motion_your_api_key

OAuth grants

The authorization server supports authorization_code + PKCE (S256), refresh_token, client_credentials, and the device authorization grant (urn:ietf:params:oauth:grant-type:device_code, RFC 8628). Clients register via Dynamic Client Registration (RFC 7591, POST /oauth/register) or CIMD. New agents register with email verification (see §2). The client_credentials grant remains available for existing service accounts. Access tokens are RS256 JWTs audience-bound to https://mcp.motion.so/mcp.

Device flow

For agents that can’t perform a browser redirect:

POST /oauth/register            → client_id  (public, token_endpoint_auth_method=none)
POST /oauth/device_authorization → { device_code, user_code, verification_uri_complete, interval }
# show the user verification_uri_complete; they approve at motion.so/device
POST /oauth/token  grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=…&client_id=…
  → authorization_pending → slow_down → { access_token, refresh_token }

Scopes

motion:sessions:read · motion:sessions:write · motion:account:read · motion:account:manage · motion:credits:read · motion:credits:purchase · motion:credits:manage · motion:automations:read · motion:automations:write · mcp. API keys do not require OAuth scopes; account permissions still control engine access.

Automations

All five profiles expose the 11 automation tools: capabilities, list, get, create, update, delete, run, run history, run detail, retry, and analytics. Reads require motion:automations:read; changes and invocations require motion:automations:write. Existing session scopes do not include these permissions. Reauthorize the connection to add automation scopes, and confirm the account has automation access. Automations execute only with GVA and default to standard effort. Use run_automation with automation_id and a new UUID request_id; reuse the UUID after a lost response to avoid duplicate runs. Channel automations need real source events. Each invocation opens a new Motion chat. Claude can read, pause, or delete existing automations. Creation, other edits, resuming, running, and retries require Motion or a GVA-capable connector. See Automations for REST equivalents, pagination, and errors.

Tools

Tool	Purpose
`list_chats` / `get_chat` / `list_chat_messages`	Browse your existing chats and messages
`list_engines`	List engines and effort levels
`list_templates`	List account-accessible templates for an engine
`create_video`	Generate a video from a prompt (async). Shows a live video widget in supported hosts; other hosts poll status
`create_followup`	Revise a completed job or reply when it is waiting on user input
`upload_asset`	Get a signed upload URL for a local file (video/audio/image), so it can be used as an attachment. The server cannot read `file://` paths — upload first, then pass the returned `attachment_url` in `attachments`
`get_session_status`	Re-show a job in the widget; read `output.download_url` when `completed`
`job_status`	App-only — the video widget calls this to refresh itself; hidden from the model
`show_plans_and_credits`	Show plans, balance, and top-ups in the plans widget
`get_credit_balance`	Read credit balance + plan
`list_plans`	List plans / top-ups
`subscribe_to_plan`	Return billing settings to review a plan (`plan_id`); the user completes changes in the browser
`purchase_credits`	Create hosted credit checkout; payment requires user action in the browser
`setup_payment_method`	Get a one-time link to add or update a payment method
`set_auto_topup`	Return billing settings; the user reviews and saves automatic top-ups in the browser
`list_api_keys` / `create_api_key` / `revoke_api_key`	Manage API keys
`get_settings` / `whoami`	Account info / connection introspection

create_video takes prompt (1–12000 chars) plus optional engine, effort, template, and aspect_ratio (16:9,9:16,1:1,4:5,21:9), duration (<10s,10-30s,30s-1min,1-5min), design_system_id, design_md, style_reference_url (YouTube), and up to 100 attachments. Attachment URLs must be publicly reachable http(s) links — for files that only exist on the user’s machine, call upload_asset first and use the returned attachment_url (see Attachments).

Interactive widgets (MCP Apps)

In hosts that support MCP Apps, Motion can show a video card and plans panel inside the conversation. Availability depends on the host and connected profile.

Video widget (create_video, create_followup, get_session_status): shows the job and updates itself live as the video renders, then plays the result inline with a Download button. The widget polls an app-only job_status tool on a server-driven cadence (poll_after_seconds), so the widget can refresh status without repeated agent calls. In hosts without a live widget, the agent polls get_session_status.
Plans widget (show_plans_and_credits): plan cards (monthly/annual), credit top-ups, and billing links. Credit purchases open hosted checkout; subscription and automatic top-up changes happen in Motion billing.
Out-of-credits recovery: if a generation can’t run for lack of credits, the tool returns structuredContent.recovery_tool: "show_plans_and_credits"; the agent opens the plans widget so you can top up, then continues after payment is confirmed.

Hosts without MCP Apps support receive JSON results. Video creation, revisions and status checks still work; billing tools return browser links for the user to complete.

Buying credits

purchase_credits creates a hosted Stripe Checkout URL (requires_checkout: true, checkout_url) for full and directory profiles. The user must complete checkout in their browser, including when a payment method is saved. Creating the link does not add credits. Purchases are idempotent on idempotency_key. subscribe_to_plan and set_auto_topup return billing links and do not change subscriptions or recurring charges. The user reviews and saves those changes in Motion billing. The OpenAI profile exposes no billing tools.

Getting Started

Working in Motion

Team administration

AI Agents

Guides

Create and edit a video

Connector profiles

Endpoints

Ways to connect

1. Authorize in the browser (default)

2. Register with a user or agent email

3. API key (fallback)

OAuth grants

Device flow

Scopes

Automations

Tools

Interactive widgets (MCP Apps)

Buying credits

​Create and edit a video

​Connector profiles

​Endpoints

​Ways to connect

​1. Authorize in the browser (default)

​2. Register with a user or agent email

​3. API key (fallback)

​OAuth grants

​Device flow

​Scopes

​Automations

​Tools

​Interactive widgets (MCP Apps)

​Buying credits

Create and edit a video

Connector profiles

Endpoints

Ways to connect

1. Authorize in the browser (default)

2. Register with a user or agent email

3. API key (fallback)

OAuth grants

Device flow

Scopes

Automations

Tools

Interactive widgets (MCP Apps)

Buying credits