Shotmatic video MCP server
Plan, price, render and clip videos from your agent.
The hosted server gives an agent 23 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
- 23
- 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 23 tools
Listed from the server's own registry. A star marks a required argument. Catalogs such as voices and styles are resources, not tools.
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. Computes only; nothing is charged.goal*, platform, duration_seconds, script, avatar_profile_id, voice_id, product, key_points, audience, cta | – | – |
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. 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://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 |
|---|---|
| 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; 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.