Shotmatic video MCP server
Plan, price, render and clip videos from your agent.
The hosted server gives an agent 28 tools and 21 workflow prompts. It works inside your Shotmatic account: the same credit balance, the same review step before anything renders, the same videos in your library.
- Endpoint
- https://shotmatic.com/mcp
- Transport
- Streamable HTTP
- Auth
- API key as Authorization: Bearer
- OAuth
- Not supported
- Tools
- 28
- Prompts
- 21
Add the server to your client
Each guide has the exact config, three prompts with the calls they lead to, and a real output.
The 28 tools
Listed from the server's own registry. A star marks a required argument. Catalogs such as voices and styles are resources, not tools.
Video DNA
Search what makes short videos break out (and what is rising now), read a format or opening in full, turn it into a structure to build on, storyboard it for your own image model, and check a draft against what held up.
| Tool | What it does | Scope | Limit per key |
|---|---|---|---|
dna_search | Search Video DNA, Shotmatic's measured knowledge of what makes short videos break out, for a goal and a niche. The query may be in English, Portuguese or Spanish. Results come in seven groups, each a role in the video: moves (measured choices, mostly in the first seconds; in a niche, ranked by what its own creators show, and that is where the edge is), findings (rules that held up for the niche), formats (containers from the Format Index, adoption only), hooks (hook lines and opening shots with templates to fill), xrays (breakouts to follow as a container), trends (what the niche's creators post more or less of now, adoption only; ask "what's trending" to list them) and asks (questions the niche's viewers keep asking that no video answers yet, demand rather than evidence; ask "what should I make next" to list them). Each item has a dna: ref, the evidence words to use, whether it matched the query (a group the query doesn't reach shows the niche's defaults, matched: false), and use_as: what dna_blueprint takes it as (ref, the container, or opening_ref, a move of the first seconds). next suggests a dna_fetch, a dna_blueprint call and the same as plan_video arguments (the short path); add the user's topic and length. Example: {"query":"first-time buyer mistakes","niche":"real_estate"}. No single format carries an edge on its own: it is the container. The edge is in the opening, the moves that held up. Never promise views. Read-only, on every plan.query, niche, kinds, evidence, limit | catalog:read | 120 per 10 min |
dna_fetch | Read up to five Video DNA objects in full by their dna: refs: a Format Index entry (recipe, line template and its slots, beats, how-to, what to watch out for, adoption and up to three credited example posts), a move (definition, what does not count, measured effect), a finding (effect, sample, comparison), an X-ray (the breakout's beats, shots, hook, pacing, sound and the moves it uses), a trend (what it is, why now, its velocity; adoption only) or a viewer question no video answers yet (dna:ask:<niche>:<n>: what viewers want and the video that would answer it; demand, not evidence). Every object carries its evidence level, the words to use for it and what they mean. Show a creator's cover only with its credit.text and link to their post; copy the structure, never their words, footage or likeness. Example: {"refs":["dna:move:c017","dna:format:fc2310e3ec9"]}; add "detail":"full" for an X-ray's every shot. Read-only, on every plan.refs, ref, detail | catalog:read | 240 per 10 min |
dna_blueprint | Turn a container ref (a format, opening, hook line, edit style, X-ray or move) and the user's topic into a blueprint: the source's beats retimed to the length, the hook, pacing, caption style, music policy and constraints with their evidence words, the script_structure Shotmatic's writer follows, and the plan_video call that makes it. Add opening_ref, a move that held up, to open the container that way: the edge is in the opening, not the format. opening.in_niche says how that move does in the niche. Without duration_seconds, the length is the source's, moved to follow the niche's length findings (length names them); a length asked for is kept within what the plan renders (longer, it runs at the plan's cap and length.asked_seconds says what was asked), and length says which finding it goes against or sits at the edge of. It is the object "Make one like this" opens Shotmatic's creator with. Write the script on its beats, or pass the same refs to plan_video or create_session as dna_ref and dna_opening_ref. Example: {"ref":"dna:xray:v515ea635e21e","opening_ref":"dna:move:c017","topic":"First-time buyer mistakes","duration_seconds":30}. Computes only; nothing is charged. Works on every plan, retimed within the length the plan renders.ref*, opening_ref, topic, duration_seconds, niche | catalog:read | 120 per 10 min |
dna_storyboard | Storyboard a video before it is made, for an agent with its own image model (GPT Image 2.5, Nano Banana 2.1 or another): from a Video DNA container ref (a format, X-ray or move from dna_search), an opening move (opening_ref) and the topic, and/or the user's script. Returns a look bible (production look, palette, light, lens, texture, the TikTok/Reels/Shorts safe zone and a negative list: no text in frames, unbranded props), cast and product sheets to generate first, and one panel per shot on the blueprint's beats at the measured pacing: time, shot size, cast, on-screen text to add in the edit, the voice-over line, transition, references, the panel's part of its image prompt (with one {picture} slot to fill) and of its motion prompt for image-to-video. Every prompt is a shared prefix plus its own part: send prompt_prefix + ' ' + panels[].image_prompt and motion_prefix + ' ' + panels[].motion_prompt (the prefix carries the look and the no-text rule, so always prepend it). detail: "full" also returns each panel's composed prompts, composition, angle, lens and camera, and the method; the default brief keeps the reply 35-45% smaller. Then the reference chain (sheets, then panel 1 as the look frame, then the rest), how to generate and approve, and next: dna_check, and the frames into Shotmatic (upload_media, then create_session with them as input_assets and asset_bindings). Panels apply Video DNA: the opening move on panel 1, the Tripod Rule (camera locked off) on every panel, the niche's findings, and an X-ray's shot sizes and cut rhythm; structure only, with the source's credit kept. Set model to the image model you have (prefer gpt-image-2.5 when your client has it; generic by default). The method is at shotmatic://playbook/storyboarding. Example: {"ref":"dna:xray:v689f6ee06428","niche":"stories","topic":"Four AI teammates run a coffee shop","visual_style":"animated_3d","cast":[{"name":"Nova","description":"a small round white robot with a teal visor"}],"model":"gpt-image-2.5"}. Composes prompts only: no image or language model runs and nothing is charged. Read-only, on every plan.ref, opening_ref, niche, topic, duration_seconds, script, look, visual_style, cast, setting, palette, model, aspect_ratio, max_panels, language, detail | catalog:read | 120 per 10 min |
dna_check | Check a draft before it's posted, or a video after, against what held up in Video DNA: the niche's findings and every creator's, the opening move the blueprint asked for, the narration pace and what the niche's research leaves out (health and finance claims). Pass what you have: the script, the planned length, what the first second shows (opening), the text on screen, the caption with its hashtags, the music, whether it's a library track, the camera and close-ups, the niche, and dna_ref / dna_opening_ref from dna_blueprint. Returns a short list of checks, each pass, flag or cant_tell, with what it saw, a concrete fix and the finding or move behind it in its evidence words; cant_tell says what to pass to check it. Findings no draft can show are in not_checked. The opening move is read in what is said in the first ~3 seconds (English, Portuguese or Spanish: a contrarian or superlative claim, two figures set against each other, a famous name for The Name Drop), and on-screen text must state the premise, not only a title. For a hook on its own, pass hook_only: true to check only the opening, with no length or word-count flags. No score and no prediction of views: a pass means nothing in the draft goes against that finding. For "why did this flop", it shows what went against what held up, never why one video got its views. Example: {"niche":"finance","script":"Most people lose to the market. Here is why...","duration_seconds":95,"caption":"3 index funds under $10 #investing #finance #stocks #money","library_track":false,"dna_opening_ref":"dna:move:c032"}. Deterministic and free: no model reads the draft. Read-only, on every plan.script, duration_seconds, opening, on_screen_text, caption, music, library_track, camera, close_ups, niche, dna_ref, dna_opening_ref, language, hook_only | catalog:read | 120 per 10 min |
Plan and price
Turn a goal into a starter payload and see credits before anything renders.
| Tool | What it does | Scope | Limit per key |
|---|---|---|---|
plan_video | Turn a natural-language goal into a recommended video type, archetype, starter session payload, credit estimate, warnings, and a creative_brief from the Shotmatic playbook: the format to make and why, three hook options on named formulas, a beat plan with target seconds and words, the length, frame, caption style, visual style and voice to choose, and pitfalls. Show the user the hook options and structure before drafting. Pass a draft script to get creative_brief.script_review, a lint of the hook, pace, one idea, ending and CTA with concrete fixes. Pass dna_ref (and dna_opening_ref, a move that held up) to build on a Video DNA structure: the type, captions and music follow it where the goal leaves them open, creative_brief.beats are its beats with the playbook's writing guidance, and dna_blueprint returns the beats the script follows. With a dna_ref or a niche, the length follows the blueprint and the niche's length findings; a length asked for is kept, and creative_brief.duration names the findings it follows or goes against. Images are planned and priced at the standard tier unless image_quality says ultra. Computes only; nothing is charged.goal*, platform, duration_seconds, script, avatar_profile_id, voice_id, product, key_points, audience, cta, image_quality, language, dna_ref, dna_opening_ref, niche | – | – |
get_creation_cost_estimate | Estimate credits for a creation or clip render using the same keyless calculation logic as POST /v1/calculate-credits. Slide videos are priced by the scenes they plan: pass video_type for article, ad and audio videos, which plan 6 scenes at any length.type, video_type, media_type, image_quality, duration_seconds, aspect_ratio, avatar_kind, voice, use_voice_over, clip | – | – |
quote_avatar_session | Prepare the required final Avatar quote after the session draft is ready. Does not reserve credits or render. Returns version-bound approval arguments for approve_and_render; review pricing and preview with the user first.session_id* | sessions:write | 30 per 10 min |
get_account | Return the caller credit balance and today’s net credit ledger spend. | videos:read | – |
Draft and revise
A session is an editable draft: preview it, change it, or branch a variant.
| Tool | What it does | Scope | Limit per key |
|---|---|---|---|
create_session | Create a draft-first interactive creation session. It uses the same payload shape as POST /v1/sessions. Headless workflow-profile runs are also supported via source.kind="workflow_profile" or source.kind="workflow_profile_binding" paired with creative_package. Add "dna_ref" (a Video DNA ref from dna_search; every plan), and "dna_opening_ref" for the move to open with, to write the draft on that structure; plan_video with dna_ref puts both in starter_session_payload. After creation, use get_session_preview to inspect the lightweight draft before update_session or approve_and_render.payload* | sessions:write | 10 per 5 min |
get_session_preview | Fetch the lightweight preview document for a creation session, including source, storyboard, voice, caption, asset, and next-action hints, plus quality_review: a check of the draft against the creative playbook (hook, one idea, words for the duration, shot length, words in images, characters, captions, ending and CTA) with a verdict and concrete fixes to apply with update_session. Read it before approve_and_render.session_id* | sessions:read | – |
update_session | Update a creation session using the same payload shape as PATCH /v1/sessions/{sessionId}.session_id*, payload* | sessions:write | 120 per 5 min |
branch_session | Create a new variant draft from an existing session while preserving project and brand context.session_id*, payload | sessions:write | – |
Render and deliver
Approve a draft into a render, follow it, and fetch the finished video.
| Tool | What it does | Scope | Limit per key |
|---|---|---|---|
approve_and_render | Approve a reviewed creation session into a queued render. For Avatar sessions, first call quote_avatar_session and use its approval_arguments payload. Return the current render status when available.session_id*, payload | sessions:write | 10 per 5 min |
get_render_status | Fetch render-run status and phase history by session id or render run id.session_id, run_id, include_events | sessions:read | – |
list_videos | List the caller’s public API videos.page, page_size, status | videos:read | – |
get_video | Fetch one video record by id.video_id* | videos:read | – |
publish_video | Record a publish draft (payload.mode "draft") for a completed video, or post it to connected social destinations (mode "live") where live distribution is enabled; otherwise live returns live_publish_disabled.video_id*, payload* | videos:write | – |
Clips from your footage
Analyze a library video, price the strongest sections, render them as clips.
| Tool | What it does | Scope | Limit per key |
|---|---|---|---|
create_clip_task | Create a clip extraction task from an existing media asset or uploaded bytes. Remote URL ingestion is advertised only when the shared capability gate is enabled.source_type*, creation_mode, url, media_id, file_url, file_base64, filename, mime_type, aspect_ratio, number_of_sections, min_section_duration, max_section_duration, generate_voiceover, include_background_music, language, focus_topic | clip_tasks:write | 6 per 10 min |
wait_for_clip_task | Wait up to 25 seconds for analysis or a partial shortlist. Returns terminal, timed_out and aborted flags and the current task. Cancellation stops polling; this does not generate or render anything.clip_task_id*, seconds | clip_tasks:read | – |
get_clip_task | Fetch one clip task by id.clip_task_id* | clip_tasks:read | – |
quote_clip_sections | Review the current credit cost and combined duration for selected clip sections before rendering. No credits are reserved. Analysis charges are separate; requote after changing the selection.clip_task_id*, section_index, section_indices, use_voice_over, aspect_ratio | clip_tasks:read | – |
render_clip_sections | Render one or more sections from a completed clip task. For one clip, send section_index. To combine several sections into one compilation video (one render, one charge), send section_indices. For commentary clips, set clip_mode to commentary and include commentary.style.clip_task_id*, section_index, section_indices, title, use_voice_over, aspect_ratio, clip_mode, voice, commentary | clip_tasks:write | 10 per 10 min |
Media library
Upload footage and images once, then reuse them by id.
| Tool | What it does | Scope | Limit per key |
|---|---|---|---|
upload_media | Upload media for later use. Accepts either a source_url or base64_data.filename, mime_type, source_url, base64_data, kind, title, metadata | media:write | 20 per 10 min |
list_media | List reusable media assets for the caller.page, page_size, type, sort | media:read | – |
Scheduled series
Set up a sequence that makes a new video on a schedule, and pause or resume it.
| Tool | What it does | Scope | Limit per key |
|---|---|---|---|
create_sequence | Create a scheduled creation sequence for repeated videos using the existing sequence automation tables. The sequence starts active and creates videos on its schedule until paused with pause_sequence. Scheduled videos are made on paid plans only: on the free plan the sequence is saved but makes no videos, and the response says so in warnings (runs_on_schedule false). Its videos are charged to the API key or connection that created it: they count toward that key’s daily credit cap (a video that would pass the cap waits for the next UTC day), and revoking the key or disconnecting the app pauses the sequence. Tell the user before relying on it.goal*, title, platform, duration_seconds, frequency, destination_ids, voice_id, language, media_type, image_quality, visual_style, aspect_ratio, sequence_instructions, metadata | sessions:write | 10 per 10 min |
pause_sequence | Pause a sequence so it creates no more scheduled videos until resume_sequence. A sequence is active or paused; pausing is how it stops. Videos already created are kept.sequence_id* | sessions:write | 30 per 10 min |
resume_sequence | Resume a paused sequence so it creates videos on its schedule again, starting with the next video that is due. From then on its videos are charged to the API key or connection that resumed it, within that key’s daily credit cap.sequence_id* | sessions:write | 30 per 10 min |
21 workflow prompts
A prompt hands the agent a ready-made plan for a common job. Clients that support MCP prompts list them by name.
viral-shortTurn a topic into a finished short video with the Shotmatic playbook: brief, hook options, a script to the beat plan, a quality review, and a render the user approves with the cost in view.
ad-from-productTurn a product into a short video ad with the Shotmatic playbook: problem-first hooks, claims only from the brief, an ending on brand plus one CTA, a quality review, and a render the user approves with the cost in view.
article-to-shortTurn an article into a short explainer with the Shotmatic playbook: the most surprising point as the hook, one question answered, facts only from the article, a quality review, and a render the user approves with the cost in view.
clip-a-podcastCut short clips from a podcast or long video with the Shotmatic playbook: sections that open on their strongest line and land on a declarative one, priced and confirmed before each charge.
create_video_from_briefGuide the model toward either a one-shot render or an interactive session from a short creative brief.
resume_project_campaignGuide the model through resuming a project, loading the best current draft, and deciding the next concrete creation step.
branch_and_compare_sessionGuide the model through forking a variant, applying a deliberate change, and comparing the result before approval.
create_listing_teaserGuide the model toward a short real-estate teaser workflow using either a draft-first plan or a direct render.
review_and_approve_sessionGuide the model through inspecting, editing, previewing, and optionally approving an interactive creation session.
publish_finished_cutGuide the model through approval, render-run inspection, and publishing: a publish draft, or a live post to connected social accounts where live distribution is enabled.
review_and_approve_video_planGuide the model through inspecting, editing, and optionally approving a draft video plan.
create_launch_filmGuide the model through a premium launch-film workflow with cinematic defaults and a review loop.
turn_walkthrough_into_clipsGuide the model through getting a walkthrough video into the media library, clip-task creation, polling, quoting, and clip rendering.
turn_article_into_videoGuide the model through turning an article URL into either a reviewable draft or a direct video render.
create_avatar_spokesperson_videoGuide the model through creating an avatar-style spokesperson video with a voice selection and optional review step.
create_asset_first_campaignGuide the model through a reusable-asset-first campaign workflow.
author_workflow_profileGuide the model through generating, previewing, refining, and publishing a reusable workflow profile from a long-form description.
configure_workflow_profile_bindingGuide the model through creating or updating a reusable workflow-profile binding for a team, brokerage, or individual creator.
create_shorts_batchGuide the model through producing a batch of related short videos using either repeated plan creation or direct renders.
upload_and_reuse_mediaGuide the model through uploading a reusable media asset, inspecting it, and referencing it in later work.
run_existing_workflowGuide the model through resolving a saved workflow and running it without inventing a new workflow definition.
Catalogs the agent reads
shotmatic://playbook | How to make a video that holds attention, with one page per format | no scope |
|---|---|---|
shotmatic://dna/method | Video DNA evidence levels, the words to use for each, and the credit rules | no scope |
skill://applying-video-dna/SKILL.md | A skill for planning and checking a video on Video DNA | no scope |
shotmatic://voices | Account voices; pass one as voice_id | voices:read |
shotmatic://avatar-profiles | Presenter profiles for Avatar videos | avatar_profiles:read |
shotmatic://capabilities | Formats, options and what is available now | no scope |
shotmatic://pricing/credit-price-sheet | Credit prices per operation | no scope |
shotmatic://caption-styles | Caption styles | catalog:read |
shotmatic://visual-styles | Visual styles | catalog:read |
shotmatic://archetypes | Starter recipes behind the workflow prompts | catalog:read |
shotmatic://media | Your uploaded media | media:read |
Authentication and scopes
Every request carries a Shotmatic API key as Authorization: Bearer <key>. Create keys on your account page, in the Developer section. A key is shown once, carries the scopes you choose, and can expire or be revoked.
The server does not offer OAuth sign-in, so connectors that only connect through OAuth cannot use it. Claude Code, Cursor and Codex send the header from their config.
A call without the scope it needs fails with insufficient_scope and names the scope in required_scope. plan_video and get_creation_cost_estimate need none.
| Scope | Tools |
|---|---|
| catalog:read | dna_search, dna_fetch, dna_blueprint, dna_check, dna_storyboard |
| clip_tasks:read | get_clip_task, quote_clip_sections, wait_for_clip_task |
| clip_tasks:write | create_clip_task, render_clip_sections |
| media:read | list_media |
| media:write | upload_media |
| sessions:read | get_render_status, get_session_preview |
| sessions:write | quote_avatar_session, approve_and_render, create_sequence, pause_sequence, resume_sequence, create_session, update_session, branch_session |
| videos:read | get_account, list_videos, get_video |
| videos:write | publish_video |
Limits and what is off today
- Rate limits. Tools that create or change work are limited per API key: quote_avatar_session 30 per 10 min; approve_and_render 10 per 5 min; create_sequence 10 per 10 min; pause_sequence 30 per 10 min; resume_sequence 30 per 10 min; dna_search 120 per 10 min; dna_fetch 240 per 10 min; dna_blueprint 120 per 10 min; dna_check 120 per 10 min; dna_storyboard 120 per 10 min; create_session 10 per 5 min; update_session 120 per 5 min; create_clip_task 6 per 10 min; render_clip_sections 10 per 10 min; upload_media 20 per 10 min.
- Long jobs. A request must finish within 60 seconds, so renders and clip analysis return an id to follow: get_render_status for renders, and wait_for_clip_task, which waits up to 25 seconds a call, for clip analysis.
- Credits. Renders and clip analysis spend credits from your balance. plan_video and get_creation_cost_estimate price a video before it exists; quote_avatar_session and quote_clip_sections price the exact draft or sections before you approve. See plans and the credit price sheet.
- Clip sources. create_clip_task takes an upload or a media library video. YouTube links and other remote URLs are refused while URL import is off: put the file in your media library first. Uploads go up to 500 MB.
- Posting. Live posting to social accounts is off, so publish_video records a draft and you download and post each video yourself.