MCP · AI agents

Motiongist in your AI assistant

Ask Claude, ChatGPT or Cursor for a video: the assistant writes the script, shows you the price and starts the generation once you agree.

Connect an assistanthttps://motiongist.com/api/mcp

Introduction

What the MCP server does

The Motiongist MCP (Model Context Protocol) server lets an AI assistant — Claude, ChatGPT, Cursor, Claude Code or your own agent — create narrated motion design videos for you: it writes the script, lets you hear the voice, tells you the exact price, and only starts the generation once you agree. The videos also show up in your studio.

Videos are narrated in English by default, or in French: just ask the assistant, which sets the language parameter (en or fr) of the project. Tools and their descriptions are in English; the assistant answers in your language.


Endpoint	`https://motiongist.com/api/mcp`
Transport	Streamable HTTP, stateless (JSON responses, no SSE stream)
Authentication	OAuth (browser sign-in) or an MCP key in the x-api-key header
Plans	Studio, Team. On other plans, only motiongist_catalog answers.
Protocol versions	2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05

Access

Authentication

OAuth (recommended for Claude.ai and ChatGPT). Just add the server URL: the client discovers authorization through /.well-known/oauth-protected-resource, opens a Motiongist sign-in page, you pick the workspace and approve. No key to copy; you can disconnect the assistant at any time in API & AI agents.

MCP key (Claude Code, Cursor, custom agents). Create an MCP key (mg_mcp_…) in API & AI agents and send it in the x-api-key header (or Authorization: Bearer). A REST key (mg_live_…) also works. The key gives access to the workspace where it was created: keep it secret.

Clients

Install in your assistant

Claude (claude.ai, Claude Desktop)

Open Settings → Connectors → Add custom connector.
Name: Motiongist, URL: https://motiongist.com/api/mcp.
Click Connect, sign in to Motiongist and allow access. Enable the connector in the conversation.

ChatGPT

Turn on developer mode in Settings → Apps & Connectors → Advanced settings.
Create a connector with the URL https://motiongist.com/api/mcp and OAuth authentication, then sign in to Motiongist.

Claude Code

Terminal

claude mcp add --transport http motiongist https://motiongist.com/api/mcp \
  --header "x-api-key: mg_mcp_…"

Without --header, run /mcp in Claude Code to sign in with OAuth.

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "motiongist": {
      "url": "https://motiongist.com/api/mcp",
      "headers": {
        "x-api-key": "mg_mcp_…"
      }
    }
  }
}

Other clients (VS Code, Windsurf, custom agents)

Generic configuration

{
  "mcpServers": {
    "motiongist": {
      "type": "http",
      "url": "https://motiongist.com/api/mcp",
      "headers": {
        "x-api-key": "mg_mcp_…"
      }
    }
  }
}

To test by hand, the protocol is JSON-RPC 2.0 over a plain POST:

curl

curl -X POST https://motiongist.com/api/mcp \
  -H "x-api-key: $MOTIONGIST_MCP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"motiongist_catalog","arguments":{}}}'

Reference

Tools

The typical flow: motiongist_catalog → motiongist_project_create → motiongist_script_write (optional) → motiongist_narration_generate (optional) → motiongist_storyboard_write + motiongist_storyboard_get (optional, review the scenes) → motiongist_estimate → user approval → motiongist_generate → motiongist_job_get → motiongist_video_get.

motiongist_catalog· Catalogread-only

Voices, looks, lengths, languages, credit costs, plan and balance of the workspace. Call this first.

motiongist_project_create· Create a projectwrite

Creates a motion design video project (draft). Give at least the topic; set language to en (default) or fr. If you already have the text to narrate, pass it in script.

title?script?subject?inputKind?sourceText?audience?length?language?voice?look?brand?notes?mascot?tier?dimension?

motiongist_project_get· Get a projectread-only

Reads a project: settings, script, status, latest generation and latest video.

projectId

motiongist_project_list· List projectsread-only

Lists the projects of the workspace, newest first.

limit?cursor?status?

motiongist_project_update· Update a projectwrite

Updates the title, script or settings of a project. Any change invalidates the previous quote.

projectIdtitle?script?subject?inputKind?sourceText?audience?length?language?voice?look?brand?notes?mascot?tier?dimension?

motiongist_script_write· Write the scriptwrite

Writes a narrated script from a topic (hook, one idea per sentence, recap). With projectId, the script is saved to the project. Free.

topicprojectId?audience?length?language?tone?

motiongist_ideas· Video ideasread-only

Suggests video ideas (title + visual angle) for a niche.

nichelanguage?count?

motiongist_narration_generate· Preview the narrationwrite

Synthesizes the project script with the chosen voice so it can be heard before generating (free). Returns an audio URL valid for 15 minutes.

projectId

motiongist_storyboard_write· Write the storyboardwrite

Optional, free: the engine plans the video scene by scene (narration line + what is shown) in about a minute, so the user can review it before paying for a render. Poll motiongist_storyboard_get until status is "ready".

projectId

motiongist_storyboard_get· Read the storyboardread-only

Status (none, planning, ready, failed) and scenes of the project storyboard. After a render, it is the storyboard of the latest video; "dirty" lists the scenes the next render rebuilds.

projectId

motiongist_storyboard_update· Edit the storyboardwrite

Replaces the scene list (keep the ids of existing scenes). Edited scenes are rebuilt on the next render, untouched scenes keep their visuals. rebuild=[ids] rebuilds scenes without changing their text.

projectIdtitle?scenes?rebuild?

motiongist_estimate· Estimate the priceread-only

Computes the exact price in credits and the generation time. Returns a signed quote (valid 1 h) to pass unchanged to motiongist_generate once the user agrees.

projectIdvoiceMode?

motiongist_generate· Start the generationwritecharges credits

Starts generating the video. Requires approved=true (the user accepted the price) and the quote returned by motiongist_estimate, unchanged. A generation takes several minutes: poll motiongist_job_get sparingly.

projectIdquoteapproved

motiongist_job_get· Track a generationread-only

Status of a generation: queue, stage (script, voice, storyboard, review, render), progress, error, and videoId once finished.

jobId

motiongist_job_cancel· Cancel a generationwritedestructive

Cancels a generation as long as rendering has not started. Credits are refunded.

jobId

motiongist_video_list· List videosread-only

Lists the finished videos of the workspace.

limit?cursor?

motiongist_video_get· Get a videoread-only

Video metadata and signed links (15 min): MP4, SRT captions, contact sheet, storyboard.

videoId

motiongist_post_copy· Post copywrite

Title, description and hashtags of a video for YouTube, TikTok, Instagram and LinkedIn, in the video language, within each platform limit (generated on first call). regenerate=true rewrites it (optionally in another language); platforms={youtube:{title,description,hashtags}} saves edits. Free.

videoIdregenerate?language?platforms?

motiongist_share· Share pagewrite

Public share page of a video (unlisted link, 9:16 player, optional button, view count). Without enabled it returns the current settings. enabled=true creates the link, enabled=false revokes it for good. cta={label,url} adds a button (http/https), allowDownload lets viewers download the MP4. The free plan always shows "Made with Motiongist".

videoIdenabled?cta?allowDownload?

motiongist_publish· Publish to social mediawrite

Publishes a finished video to a connected YouTube, TikTok, Instagram or LinkedIn account, now or at scheduledAt (ISO 8601 with offset, up to 1 year ahead). Free (no credits). Without accountId or provider, it only lists the connected accounts and the posts of this video. The post uses the video post copy for the platform unless copy is given. Accounts are connected by a workspace member in the web app (/app/publishing). cancelPostId cancels a scheduled post instead. Poll again to see the status (scheduled, publishing, published with externalUrl, failed with error).

videoIdaccountId?provider?scheduledAt?copy?cancelPostId?

Parameters in black are required. The full schemas are returned by tools/list.

Resources: each video exposes its storyboard (motiongist://videos/{videoId}/storyboard) and its captions (motiongist://videos/{videoId}/captions) through resources/read.

Safety

Price approval

motiongist_estimate computes the exact price in credits and returns a signed quote (quote) valid for 1 hour. It charges nothing.
The assistant must show you this price. motiongist_generate requires approved: true and the unchanged quote; without both, nothing starts.
The generation never costs more than the quote. If the project changes after the estimate (script, voice, length…), the quote is refused and the assistant must estimate again.
Failures and cancellations (motiongist_job_cancel, possible until rendering starts) are refunded.

Help

Troubleshooting

Symptom	Cause and fix
401 with a WWW-Authenticate header	No token or key, or an expired token. Reconnect the connector (OAuth) or check the x-api-key header.
“MCP access is included from the Studio plan”	Your workspace is not on a Studio, Team plan. Change plans in Credits & plan.
“Missing scope: jobs:write”	The key or the OAuth authorization is read-only. Create a key with write scopes.
QUOTE_INVALID	The quote is more than an hour old or the project was modified since. Run motiongist_estimate again and approve the new price.
INSUFFICIENT_CREDITS	Balance too low: top up or upgrade your plan.
“Too many requests”	Limit of 60 tool calls per minute per key. Space out motiongist_job_get calls (every 10 to 20 s).
GET returns 405	Expected: the server is stateless and offers no SSE stream. Streamable HTTP clients use POST.
The assistant doesn’t see the tools	Check that the connector is enabled in the conversation, then ask it to list the Motiongist tools.

Prefer plain code? The same logic is available as a REST API.