Kickstart

MCP home · General MCP · Video MCP · Raw Markdown

Video MCP

Create, edit, validate, preview, and export Kickstart video projects from AI agents.

What Agents Can Build

Video MCP tools operate on Kickstart .ksvideo packages using the same document model and shared renderer as the Kickstart app. Agents can create project bundles, add media and text clips, generate narration with subtitles, download stock footage, add App Store badges, render animated 3D device mockups with screen content, and export frames or final movies.

All Video MCP tools require an active Kickstart Pro subscription. When Pro is inactive, the video tools are hidden from tools/list and direct calls return a Pro subscription error.

Use tools/list for exact JSON schemas. This page is the workflow guide and complete video tool index.

Connect and Discover

Kickstart ships one MCP helper at /Applications/Kickstart.app/Contents/Helpers/KickstartMCP. Claude, Codex, Gemini integrations, Cursor, and custom clients should launch that helper over stdio and use normal JSON-RPC 2.0 MCP messages.

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Treat tools/list as authoritative. If no video_ tools appear, the installed build may be old or the user may not have active Kickstart Pro. Do not call video tools that are missing from the live tool list.

Core Rules

Agent Operating Loop

A good video agent should move through discovery, narrow edits, validation, visual checks, and export. This keeps documents openable in Kickstart and keeps MCP output aligned with the app preview.

  1. Call video_create_project for a new package, or video_get_project_summary for an existing package. Keep the returned revision.
  2. For each mutating call, pass projectPath and the latest expectedRevision. Replace your cached revision with the new value returned by the tool.
  3. Use video_find_available_track or explicit trackIndex values to avoid clip overlap. Timeline times are frames; Kickstart video projects use 30 frames per second, so 90 frames is 3 seconds.
  4. Keep returned assetID, clipID, and animationID values. Later tools need those IDs; agents should not infer them from filenames or display text.
  5. Use compact reads while planning: video_get_project_summary, video_list_tracks, video_list_clips, and video_get_clip. Use detailLevel: "full" only for debugging.
  6. Call video_validate_project before rendering. Fix validation errors first; warnings may be acceptable if the user asked for a fast draft.
  7. Call video_export_frame for at least one representative frame before a long movie export.
  8. Call video_export_video only after validation and frame preview succeed. The returned outputPath is the file to show the user.

Response Handling

Video tool responses are MCP text content containing JSON. Parse result.content[0].text as JSON and inspect the fields before deciding the next step.

Fields to preserve

Mutating video tools commonly return projectPath, revision, changed, summary, warnings, tracks, and clips. The clips array contains clips touched by that call, including IDs needed for transforms, subtitles, animations, duplication, splitting, and deletion.

Structured recovery hints

Some failures return a JSON object with isError true and fields such as error, message, and nextTool. Follow nextTool when it is present. For example, narration model failures point to video_download_narration_models, and missing device models point to video_download_device_model.

Revision conflicts

If a tool reports a revision mismatch, call video_get_project_summary, compare the current tracks and clips with your intended edit, then retry with the new revision. Never bypass this by editing project.json directly.

Core Field Reference

These values are useful when constructing calls by hand. The live JSON schemas returned by tools/list remain the source of truth.

Document sizes

Media and style values

Subtitles

Use video_generate_narration with showSubtitles: true to create subtitles automatically from generated word timestamps. Use video_update_clip_subtitles or video_update_narration_subtitles to tune display mode, karaoke highlighting, social safe area, colors, font, transitions, and placement.

App Store badges and exports

Common Workflows

Create a narrated stock video

  1. Create the package with video_create_project.
  2. Search or download background footage with video_search_stock_media and video_add_stock_media_clip, or build scenes with video_build_stock_sequence.
  3. Check voices with video_list_narration_voices, then call video_download_narration_models if needed.
  4. Call video_generate_narration with projectPath, text, voiceID, and showSubtitles to write WAV audio, waveform data, word timestamps, and a narration clip into the package.
  5. Add a CTA with video_add_text_clip and video_add_app_store_badge_clip.
  6. Validate and export with video_validate_project and video_export_video.

Create a 3D device mockup

  1. Call video_list_device_models to find the device ID, such as iphone-17-pro-max.
  2. Call video_download_device_model if the model is not installed.
  3. Import the screen image or screen recording with video_import_media.
  4. Add the device using video_add_device_mockup_clip or video_add_device_clip.
  5. Attach screen content with video_set_device_screen_content.
  6. Animate rotation, scale, or position with video_add_clip_animation, video_apply_animation_preset, or video_update_device_transform.
  7. Use video_preview_animation or video_export_frame before exporting the final movie.

Build from a storyboard

Use video_build_from_storyboard for structured scenes with text, stock queries, narration, and optional CTA data. The recipe tools video_create_marketing_video, video_create_app_mockup_video, video_create_social_ad, video_create_app_store_preview, and video_create_narrated_stock_video use the same storyboard engine with workflow-specific intent.

Raw Call Examples

MCP clients normally handle JSON-RPC framing. These examples show the shape of tool calls when debugging manually. Replace REVISION_FROM_LAST_CALL, CLIP_ID_FROM_RESPONSE, ASSET_ID_FROM_RESPONSE, and paths with values from earlier tool responses.

Create a portrait project

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"video_create_project","arguments":{"projectPath":"/path/to/codex.ksvideo","documentSize":"portrait1080","overwrite":true}}}

Generate narration with subtitles

Check model readiness first. If the status response says models are missing, call the download tool and wait for it to finish before generating narration.

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"video_get_narration_model_status","arguments":{}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"video_download_narration_models","arguments":{}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"video_generate_narration","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","text":"Show your app in motion with Kickstart. Generate launch videos, App Store previews, and narrated demos from one editable timeline.","voiceID":"amara","showSubtitles":true,"startFrame":0,"trackIndex":1,"volume":100}}}
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"video_update_clip_subtitles","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","clipID":"CLIP_ID_FROM_NARRATION_RESPONSE","subtitleDisplayMode":"Phrases","subtitleKaraoke":true,"subtitleVerticalPosition":"Bottom","subtitleHorizontalAlignment":"Center","subtitleSocialSafeArea":true,"subtitleTransition":"Fade","subtitleKaraokeAnimation":"Sliding Background"}}}

Search stock media and add one result

Pass one full object from the results array into stockMedia. The second call below shows the expected shape; real values should come directly from video_search_stock_media.

{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"video_search_stock_media","arguments":{"query":"developer typing app launch dashboard","orientation":"portrait","limit":3}}}
{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"video_add_stock_media_clip","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","stockMedia":{"id":123456,"width":1080,"height":1920,"duration":8,"url":"https://www.pexels.com/video/example/","image":"https://images.pexels.com/videos/example.jpg","user":{"id":42,"name":"Creator Name","url":"https://www.pexels.com/@creator"},"video_files":[{"id":98765,"quality":"hd","file_type":"video/mp4","width":1080,"height":1920,"link":"https://videos.pexels.com/video-files/example.mp4"}]},"startFrame":0,"durationFrames":180,"trackIndex":0,"scaleToFill":true}}}

Add a 3D iPhone with screen content

Use video_list_device_models to confirm the exact model ID in the installed app. If the model is not downloaded, download it before adding the device clip.

{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"video_list_device_models","arguments":{}}}
{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"video_download_device_model","arguments":{"deviceModelID":"iphone-17-pro-max"}}}
{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"video_import_media","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","mediaPath":"/path/to/screen.png"}}}
{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"video_add_device_mockup_clip","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","deviceModelID":"iphone-17-pro-max","startFrame":0,"durationFrames":210,"trackIndex":3,"scale":86,"rotationX":-8,"rotationY":24,"positionY":-30}}}
{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"video_set_device_screen_content","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","clipID":"CLIP_ID_FROM_DEVICE_RESPONSE","assetID":"ASSET_ID_FROM_IMPORT_RESPONSE"}}}
{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"video_apply_animation_preset","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","clipID":"CLIP_ID_FROM_DEVICE_RESPONSE","preset":"Rotate In","relativeStartFrame":0,"durationFrames":60}}}

Add a CTA with an App Store badge

{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"video_add_text_clip","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","content":"Download on the App Store","startFrame":210,"durationFrames":90,"trackIndex":2,"fontSize":72,"textAlignment":"center","textColorRGB":[1,1,1],"naturalWidth":900,"naturalHeight":140,"positionY":-180}}}
{"jsonrpc":"2.0","id":15,"method":"tools/call","params":{"name":"video_add_app_store_badge_clip","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","badgeStyle":"appStoreDownload","colorScheme":"black","startFrame":210,"durationFrames":90,"trackIndex":3,"scale":140,"positionY":120}}}

Build a complete storyboard

{"jsonrpc":"2.0","id":16,"method":"tools/call","params":{"name":"video_build_from_storyboard","arguments":{"projectPath":"/path/to/storyboard.ksvideo","documentSize":"portrait1080","overwrite":true,"voiceID":"amara","defaultSceneDurationSeconds":4,"scenes":[{"narration":"Launch with a polished app preview in minutes.","showSubtitles":true,"visual":{"stockQuery":"mobile app launch team","orientation":"portrait"},"text":{"content":"Launch-ready videos","fontSize":76},"animationPreset":"Fade In"},{"narration":"Show real screens inside animated Apple device models.","showSubtitles":true,"visual":{"deviceModelID":"iphone-17-pro-max"},"text":{"content":"Real device mockups","fontSize":76},"animationPreset":"Scale In"}],"callToAction":{"title":"Ready for the App Store","prompt":"Download today","durationFrames":120}}}}

Validate, preview, and export

{"jsonrpc":"2.0","id":17,"method":"tools/call","params":{"name":"video_validate_project","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL"}}}
{"jsonrpc":"2.0","id":18,"method":"tools/call","params":{"name":"video_export_frame","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","outputPath":"/path/to/codex-frame.png","frame":90,"resolutionPreset":"matchDocument","overwrite":true}}}
{"jsonrpc":"2.0","id":19,"method":"tools/call","params":{"name":"video_export_video","arguments":{"projectPath":"/path/to/codex.ksvideo","expectedRevision":"REVISION_FROM_LAST_CALL","outputPath":"/path/to/codex.mp4","includeAudio":true,"resolutionPreset":"matchDocument","videoBitratePreset":"high","audioBitratePreset":"kbps192","overwrite":true}}}

Failure Recovery

Complete Tool Reference

The Video MCP surface provides 81 video tools.

Project Packages (6)

Kickstart Project Links (4)

Tracks And Timeline (6)

Clips And Styling (17)

Animations (11)

Assets (6)

Narration And Subtitles (8)

Stock Media (4)

3D Device Models (9)

Export (4)

Storyboard Builders (6)