How to generate videos in Claude Code with MCP

Claude Code can already read your repository, run your tests and open a pull request. With one MCP server connected it can also make a video: you describe what you want in the same terminal session you were already working in, approve a script, and a few minutes later there is an MP4 to download. This post covers exactly how that works — the install command, the single credential you need, which half of the work your assistant does versus which half runs on our servers, and where the honest limits are.

What MCP is, and why a video is a good fit for it

The Model Context Protocol is an open standard for connecting an AI assistant to an outside system. A server publishes a set of tools with typed inputs, and the assistant decides which to call and when — the same way it decides to read a file or run a command. Nothing about it is specific to Claude: Cursor, VS Code Copilot, Windsurf, Zed, Codex CLI and Gemini CLI all speak the same protocol, and the same server works from any of them. Claude Code is simply where most developers first used it, and it remains the client where a long multi-step workflow feels most natural.

That matters here because generating a video is not one call. It is a sequence: agree a plan with the user, write a creative direction for each scene, write the animation code for each scene, look at the result, fix what is wrong. A protocol that lets a model hold that sequence across dozens of tool calls, with each result shaping the next, fits the problem far better than a single text-to-video endpoint that swallows a prompt and hands back whatever it produced. It also means the model that writes your video is the one you already chose, running in the client you already trust.

Connecting the server to Claude Code

Idea to Motion is a remote MCP server speaking Streamable HTTP at https://api.ideatomotion.com/mcp. Claude Code can carry a static Authorization header, so connecting is one command rather than a local process to install and keep running. Mint a connection key on the connect page first, then substitute it for the placeholder below.

claude mcp add ideatomotion https://api.ideatomotion.com/mcp --transport http --header "Authorization: Bearer vai_YOUR_KEY"

{
  "mcpServers": {
    "ideatomotion": {
      "type": "http",
      "url": "https://api.ideatomotion.com/mcp",
      "headers": {
        "Authorization": "Bearer vai_YOUR_KEY"
      }
    }
  }
}

Reload Claude Code and the tools appear under the server's name. The quickest way to confirm the connection is live is to ask it to call get_creation_options with a topic — that tool opens a picker of looks and narrator voices, and in a text-only client it returns the same options as plain text, so a successful call proves both the transport and the authentication in one step.

Connect a voice key — and when you do not need one

Narration runs on your own provider key, not ours. Before your first narrated video, connect an ElevenLabs or Cartesia key with the set_voice_key tool. That key does two jobs: synthesizing the voiceover, and transcribing an uploaded recording back into words. Both are voice services and both bill to you, which is the point — the per-minute cost of speech never becomes a reason for us to cap how much you are allowed to make. The key is stored encrypted and is never returned by any tool; get_voice_status reports only which provider is connected and which narration engine it will use.

Silent motion graphics need no voice key at all. If what you want is on-screen text and animation with no narrator — a launch teaser, a changelog card, a feature announcement over music — you can create it, preview it and export it without connecting any provider. This is the cheapest way to see whether the whole loop works for you, and it is what I would try first. For narrated videos, calling get_voice_status before you approve a plan is worth the one tool call: discovering a missing key at approval means the script you just agreed is waiting on a credential, rather than being three steps into production.

What actually happens when you ask for a video

The division of labour is sharper than it first looks. Your assistant does all of the writing: the script, the creative direction for each scene, and the actual animation code — real TypeScript and React components, rendered with Remotion. For a video made this way, no model on our side makes a creative decision. The platform does the parts a language model cannot do: synthesizing the voiceover, transcribing it back to obtain a timestamp for every word, snapping the scene boundaries to those timestamps, validating and sandbox-executing the submitted code, compositing sound effects and music, and rendering the final frames in a headless browser.

In practice the sequence runs create_job, get_plan, submit_plan, approve, and then per scene get_direction_brief and submit_directions followed by get_code_brief and submit_scene_code. The briefs are the interesting half. Each one is the full engineering contract — the resolved theme colours and fonts, the layout rules, the animation kit that is in scope, the list of globals available — so the assistant never needs access to this codebase to write a scene that compiles. Submitted code is statically validated and then executed for three frames in a sandboxed worker before it is accepted, which means a runtime crash comes back as a tool error carrying the message, and the model corrects it in place instead of a broken scene reaching the finished video.

Approval is a real gate, not a formality. Nothing is voiced or rendered until you say yes to the plan — which for an explainer is the exact script you are about to hear read aloud. That is deliberately the cheapest moment to change your mind: rewriting a script costs one tool call, while rewriting it after the voiceover exists means new audio and a new timeline for every scene downstream of it. Progress is polled rather than pushed, so your assistant calls get_job_status every fifteen seconds or so while a stage runs, and each response names the tool to call next.

The three kinds of video

You choose a kind at create_job, and it decides the shape of the plan you approve. An explainer is narrated: your assistant writes a script, the platform reads it in the voice you picked, and the scenes are timed to the individual words. A motion graphic is silent: the assistant writes a shot list with a duration per shot, the on-screen text is the content, and there is no voice key and no social-metadata step. A recording is your own footage: you upload a video, it is transcribed on your key, silences are detected, your assistant proposes which segments to keep, and the animation is composited over or beside you.

Aspect ratio and length are independent axes. A fifteen-second widescreen clip and a three-minute vertical explainer are both reachable, and you state what you want in ordinary words — "a YouTube video, about ninety seconds" — which the assistant turns into an aspect and a runtime and then reports back so you can correct it. That readback matters more than it sounds: neither choice is recoverable once the voiceover has been recorded against it, and a decision you cannot see is one you cannot correct.

Previewing and iterating

Most of the quality arrives in the loop after the first build, not in the first build. list_scenes returns every scene with its id, its timings and whether it already has accepted code, which is how a sentence like "the third scene feels empty" becomes a scene id to act on. render_scene_preview then renders that scene on our servers and returns the images to the assistant, so it can look at what it built instead of asking you to take a screenshot. Captions, any hand edits you made on the platform, and — for a recording — the speaker's own frame are composited in, so what the model checks is what will ship.

Note the word images. A scene preview is stills, not moving video, so timing and easing are still judged by watching the real composition — in the browser, where the platform plays it with audio, or in the chat preview panel if your client supports the MCP Apps extension. For small changes, edit_scene_code applies exact substring replacements to the code already accepted rather than rewriting the scene from scratch, which is both cheaper in tokens and far less likely to undo something that was already right. Three more tools change a finished video without touching scene code at all: adjust_audio for the sound effects and music bed, adjust_captions for burned-in subtitles, and adjust_scene_framing for where the speaker sits in a recorded video.

Why there is no export tool

You will not find a tool that renders the final MP4, and its absence is deliberate. Exporting is the only step that spends money, and an agent cannot see your account balance before it calls — so an export tool would mean a charge at a moment you did not choose, at a resolution you did not pick, with no way to decline. Every workflow therefore ends by pointing you back at the platform, where you select the resolution and see the exact price for that video before clicking. Re-exporting a video you have already paid for is free, so being sent to a browser tab once costs you nothing on the second pull.

What this costs, and the limits worth knowing

Creating and previewing are free in the sense that matters: writing a script, directing scenes, submitting code, fixing a scene and watching the preview cost you nothing here, because the model doing that work is yours and the preview plays in your browser. Rendering is different. It is real server compute that scales with duration and pixels, and that is what the rate card prices. Exports at 720p and below are free but watermarked, with a small monthly allowance; 1080p is billed per second of finished video with no minimum, and higher resolutions are a multiple of that rate. The current figures are on the pricing page, and the download menu quotes the price for that specific video before you commit.

A few operational limits are better known up front than discovered mid-session. Scene previews are bounded per account per day, because each one launches a headless browser on our side — a normal session will not come close, but an agent left looping can. Submitting a scene takes seconds rather than milliseconds, since it bundles and renders, so a five-scene video is a few minutes of tool calls; the server sends progress notifications to keep your client's inactivity timer alive rather than returning early. Uploaded recordings are capped at 1.5 GB and go straight to object storage over a presigned link rather than through the API.

The larger limit is not ours. Because your assistant writes the animation code, the output tracks the model driving it and the specificity of what you asked for. "Make me a video about our launch" produces something generic in any system; naming the three things you want on screen, the tone, and who it is for produces something worth publishing. The platform enforces a floor — a layout audit rejects scenes that leave most of the canvas empty, and a render-cost check rejects effects that would make the export crawl or time out — but a floor is not taste, and you will get better results by treating the assistant as a collaborator you brief properly than as a button.

Try it with something small

Mint a key on the connect page, run the command above, and ask for something short first — a fifteen-second silent motion graphic needs no voice key and reaches a finished preview in a couple of minutes, which is enough to tell you whether the loop suits how you work. The complete tool reference is published on the docs site, and the full workflow, including how to recover from each kind of rejection, is served as an open Agent Skill at https://api.ideatomotion.com/mcp/skill that any skill-aware client can read.