> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motion.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#interactive-widgets-mcp-apps)).

For the ChatGPT-specific app setup flow, see [ChatGPT App](https://docs.motion.so/guides/chatgpt-app.md).

For Claude, see [Motion for Claude](https://docs.motion.so/guides/claude.md). 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:

```json theme={null}
{"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](https://docs.motion.so/guides/engines.md).

## 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](https://docs.motion.so/guides/engines.md#discover-available-engines).

## 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.

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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:

```text theme={null}
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](https://docs.motion.so/guides/automations.md#mcp-tools-and-claude): 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](https://docs.motion.so/guides/automations.md) 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](https://docs.motion.so/guides/attachments.md)).

## Interactive widgets (MCP Apps)

In hosts that support [MCP Apps](https://modelcontextprotocol.io), 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](https://motion.so/agent?settings=plans_billing). The OpenAI profile exposes no billing tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.