Codex video generation with the Shotmatic MCP server

Ask Codex for a video. Approve it before it renders.

Codex reads the key from an environment variable, which suits scripted work: a few shorts from a topic list, a weekly series, or download links for what you made this week.

Create an API keySee all 23 tools
Install

Connect Codex to Shotmatic

  1. 01

    Create an API key on your Shotmatic account page, in the Developer section, scoped to the prompts below.

  2. 02

    Add the entry below to ~/.codex/config.toml.

  3. 03

    Export SHOTMATIC_API_KEY in the shell that launches Codex, then start Codex.

  4. 04

    Run /mcp in Codex: shotmatic should be listed with its tools.

TOML configCodex Remote MCP
[mcp_servers.shotmatic]
url = "https://shotmatic.com/mcp"
bearer_token_env_var = "SHOTMATIC_API_KEY"

Add this entry to your Codex configuration and make SHOTMATIC_API_KEY available in the environment that launches Codex.

After connecting, call get_account and read shotmatic://capabilities. Use plan_video to choose a creation path. Add write scopes only for the actions you need.

Scopes the prompts below use: sessions:read, sessions:write, videos:read, voices:read.

Prompts

Three prompts and the calls they lead to

Shotmatic's server instructions steer the agent through these calls. It may add a read, such as the capabilities catalog, or check a status more than once.

01Three shorts from a topic list

Prompt

Make three 30-second faceless shorts for YouTube Shorts, one per topic: why the ocean is salty, how bees find flowers, why we have leap years. Use the same voice for all three and render them once I confirm the total.

Calls it leads to

  1. 1read shotmatic://voicesPick a ready account voice; its id becomes voice_id.
  2. 2plan_video(platform: "youtube_shorts", duration_seconds: 30)Called once per topic; each returns a starter payload and estimate.
  3. 3create_sessionOne draft per topic.
  4. 4approve_and_renderOne render per draft after you confirm.
  5. 5get_render_statusFollows each render.
You get
Three 9:16 shorts in your library.
API key scopes
sessions:read, sessions:write, voices:read

02A weekly series

Prompt

Set up a weekly series of 45-second faceless shorts about the history of everyday objects for YouTube Shorts, using my default narrator.

Calls it leads to

  1. 1read shotmatic://voicesPick a ready account voice; its id becomes voice_id.
  2. 2create_sequence(frequency: 1, duration_seconds: 45, platform: "youtube_shorts")Creates the series; Shotmatic makes each video on its schedule.
You get
An active sequence. On a paid plan with enough credits, Shotmatic makes each video when it is due and emails you; you download it and upload it yourself.
API key scopes
sessions:write, voices:read

03This week's download links

Prompt

List my five most recent Shotmatic videos with their status and give me the download link for each finished one.

Calls it leads to

  1. 1list_videos(page_size: 5)Lists recent videos with their status.
  2. 2get_videoFetches each finished video and its MP4 link.
You get
A list of recent videos with download links.
API key scopes
videos:read
Real output

A video made through these tools

Every client reaches the same server, so an output looks the same whichever agent asked for it.

Paper Moon Assembly

Made on April 3, 2026 with Shotmatic's MCP session tools, on a local copy of the hosted server using the production render pipeline and an internal test account.

Script

A city of paper astronomers gathers every night to assemble a moon from glowing fragments. Crane-sized kites lift silver crescents into place. Children in raincoats deliver the final shard. When the moon clicks together, the entire city glows as if it has remembered its own sky.

Calls the run made

  1. create_sessionCreated a draft from the script with a 9:16 render.
  2. get_session_previewWaited for the preview before changing anything.
  3. update_sessionCut the caption density, keeping the vertical framing.
  4. approve_session (today: approve_and_render)Approved the revised draft into the final render.
Format
Faceless short
Aspect ratio
9:16
Length
18 s
Visuals
AI Video
Image quality
Ultra
Visual style
Hand-painted Anime
Captions
Viral
Narration
AI voice
Soundtrack
Yes

At these settings a video like this is 301 credits today. This run predates the credit ledger, so its own charge is not on record.

Next
Claude Code guideCursor guideRecipes: step-by-step agent tasks