MCP Server & AI Agents

Connect AI agents to Mosaic Motion over the Model Context Protocol (MCP). The MCP server is guarded by an OAuth 2.1 authorization server, and agents can generate videos, manage credentials, and buy their own credits. In hosts that support MCP Apps (including ChatGPT Apps and Claude), 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.

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 — signing up for Motion 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. Autonomous service account (no human in the loop)

An agent can register itself — no human, no device code — when self-service registration is enabled. It posts to the public registration endpoint (discoverable as service_account_registration_endpoint in /.well-known/oauth-authorization-server):

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

{ "name": "my agent" }

This returns a client_id + one-time client_secret, the token_endpoint, and a payment_setup_url. The agent then authenticates with neither an API key nor a browser sign-in:

POST https://mcp.motion.so/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=…&client_secret=…

Returns a short-lived access token. A service account has its own Motion identity, credits, and billing — separate from any user account.

Funding (one-time card setup, then formless): the agent's wallet starts empty. Add a card to it once by opening the payment_setup_url from registration (or call the setup_payment_method tool any time for a fresh link). After a card is on file, purchase_credits charges it directly (status: "charged", no checkout form) and set_auto_topup keeps the agent funded automatically — so it pays entirely on its own from then on.

A human can also provision one from Settings → MCP → Let your agent sign itself up, or via the register_service_account tool.

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 a Motion 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. Autonomous agents self-register a service account at POST /oauth/service-accounts/register (when enabled — see §2). 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 · mcp. (Motion API keys have full access.)

Tools

Tool	Purpose
create_video	Generate a video from a prompt (async). Renders the live video widget that updates itself until the video is ready — no polling needed
create_followup	Refine a completed video (same live widget)
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	Start checkout to subscribe to / switch a plan (plan_id)
purchase_credits	Buy credits (charges a saved card on file, or returns a checkout URL)
setup_payment_method	Get a one-time link to add a card to your wallet (so later top-ups are formless)
set_auto_topup	Configure automatic top-ups
register_service_account	Create an autonomous agent identity (humans only)
list_api_keys / create_api_key / revoke_api_key	Manage Motion API keys
get_settings / whoami	Account info / connection introspection

create_video takes prompt (1–12000 chars) plus optional 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 10 attachments.

Interactive widgets (MCP Apps)

In hosts that support MCP Apps (including ChatGPT Apps and Claude), Motion tools render interactive UI inline in the conversation. Widgets are served as ui://motion/*.html resources (text/html;profile=mcp-app); a tool opts in via _meta.ui.resourceUri, and the host pushes the tool's structuredContent to the widget. ChatGPT also honors the compatibility alias _meta["openai/outputTemplate"].

• 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 agent fires one call and never has to poll.
• Plans widget (show_plans_and_credits): plan cards (monthly/annual), credit top-ups, and one-click checkout — buttons call subscribe_to_plan / purchase_credits / setup_payment_method and open the Stripe checkout.
• 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 retries.

Hosts without MCP Apps support get the same data as plain JSON — every tool works headlessly too.

Buying credits

purchase_credits tops up motion_credits via Stripe. If a payment method (a Stripe Link wallet) is on file, the charge completes immediately (status: "charged"); otherwise it returns a hosted Checkout URL (requires_checkout: true, checkout_url). Purchases are idempotent on idempotency_key.