Framesail AI
About
Official remote MCP server for Framesail AI. Create long-form (faceless YouTube) videos end to end from any MCP client: script, locked character references, storyboard, voiceover, and final video editing — with characters and style held consistent across every shot.
Details
- Author
- framesail
- Downloads
- 341
- Categories
- AI
Jump to
- Full video production pipeline as MCP tools: script, references, storyboard, voiceover, render.
- Streamable HTTP transport with OAuth 2.1 or fsk_ API key authentication.
- Supports anonymous initialize and tools/list for health checks without an account.
- Character and style consistency maintained across every shot.
- Available on Pro and BYOK pricing plans.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Framesail AICommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Connect via OAuth or an fsk_ API key. For claude.ai / Claude Desktop, add a custom connector pointing to https://api.framesail.com/mcp and approve the browser login. For Claude Code, run claude mcp add --transport http framesail https://api.framesail.com/mcp --header "Authorization: Bearer fsk_...". Other MCP clients similarly set the URL and Authorization header. Create API keys on your Framesail account page.
list_channels
List your channels. Every project lives in a channel, which owns the reusable styles (art/narrative/director) that drive generation.
create_channel
Create a new channel — the container for projects and their reusable styles. Use when the user wants a fresh creative identity rather than adding to an existing channel.
list_projects
List projects in a channel.
create_project
Create a project. The description (the video concept/topic) seeds script generation, so write a meaningful one. The response's web_url is the project's page in the web app — share it so the user can follow along.
get_project
Fetch a project row — settings, voice config, default style, export URL.
update_project
Patch project fields. Updatable: title, description, asset_mix, sfx_level, video_concept, voice_mix, voice_tts_provider, script_target_minutes, narrator_speed. (The narrator's TTS voice is NOT here — use set_narrator_voice.)
delete_project
Permanently delete a project and everything in it (script versions, assets, voiceover, segments, renders). Irreversible — confirm with your user first.
set_project_style
Set the project's default style — the style whose art/narrative/director fields drive its generations. Use after create_style to put a new visual identity into effect, or to switch a project between channel styles.
update_caption_config
Merge a patch into the project's burned-in caption config (keys like enabled, plus styling). Read the current value from get_project (caption_config). Applies at the next export — no rebuild needed.
get_pipeline_progress
THE resume/orientation tool: one call returns every pipeline step's state (script -> scan -> reference_images -> voices -> voiceover -> style_templates -> storyboard -> segment_assets -> scenes -> export), any running jobs, and a next_action telling you exactly what to do next. Call this when picking up an existing project, after any await_jobs, or whenever you're unsure where a video stands — never guess pipeline position. Every step carries a web_url — the page in the Framesail web app where your user can see that step's output. Share it whenever you present a step's results ("review the storyboard here: ...") so they can inspect and edit in the browser; the app and this API act on the same live state.
get_workflow_status
Poll this between steps: returns active + recently-finished AI jobs (scope by project_id, or style_id for style analysis), plus per-segment- asset render statuses for projects. A step is done when its jobs reach status=complete (or error, with a user-readable message). NOTE: finished jobs drop out of `jobs` after ~30s — a short list does NOT mean work was lost; judge render batches by `segment_assets` statuses (or get_pipeline_progress), never by counting jobs. Prefer await_jobs over polling this in a tight loop.
await_jobs
Block (server-side) until the scope has no pending/running jobs, or the timeout passes — use this instead of polling get_workflow_status yourself. Returns {done, jobs}. If done=false the work is still running: just call await_jobs again (a 3-5 minute storyboard takes a few consecutive calls). Keep timeout_seconds <= 50 so the client doesn't time out the tool call.
get_section_template
Inspect the prompt sections a generation job exposes for per-call override via editable_sections (jobs: script, script_scan, storyboard, segment_image, segment_video, voice_block, ...). Sections marked locked cannot be overridden.
list_models
List the models allowed for a generation job, with display names, credit estimates, and each model's settings_schema — the valid keys for that tool's `settings` param (e.g. image quality/orientation, video duration). The first entry is the default every tool uses when model is omitted.
generate_script
Generate the project's script from its description/concept and the channel's narrative style. Async — returns {job_id}; poll get_workflow_status.
get_script
Read the active script's full text + the version list. Use this to show the script to your user for review/feedback before scan_script — the review-edit-resave loop (get_script -> discuss -> save_script) is the expected workflow when the user wants input.
save_script
Save script text (your own draft, or an edited version of the generated one — saving creates a new version, old versions are kept). Run scan_script afterwards so assets and voice blocks reflect the new text.
revise_script
AI-rewrite a passage of the active script in the project's narrative voice (the same in-editor revise the UI offers). selected_text must appear verbatim in the script; omit it to revise the whole script. Synchronous — returns {revised_text}, which is NOT saved: splice it over selected_text (or replace the full script) and call save_script to keep it.
activate_script_version
Switch the project's active script to another saved version (ids come from get_script's version list — every save_script creates one). Re-run scan_script / rescan_voice_blocks afterwards if the text differs, since downstream artifacts follow the active version.
scan_script
Analyze the active script: extracts character/environment/object assets and splits narration into voice blocks. DESTRUCTIVE on re-run (assets are recreated, not merged — curated descriptions, reference images, and voices are lost; prefer rescan_voice_blocks after script edits). Async — returns {job_id}.
list_assets
List the project's assets extracted by scan_script — characters, environments, objects. Each has a description (the spec every shot uses to render it — surfaced top-level here; the raw row nests it at ai_output.description), an optional reference image (file_path is a public URL — view_image it), and for characters a voice_id. Review these after scan_script: fix descriptions, then generate_asset_reference for each one (all of them need a reference image before voiceover). asset_type filter: "character" | "environment" | "object".
create_asset
Manually add a character/environment/object the scan missed. asset_type: "character" | "environment" | "object". The description is the generation-facing spec of its look — be specific.
update_asset
Rename an asset and/or rewrite its description. If the look changed, regenerate its reference image afterwards so renders match.
delete_asset
Delete a project asset (e.g. one the scan over-extracted).
generate_asset_reference
Render an asset's reference image in the channel's art style — the visual anchor that keeps a character/environment looking identical across every shot. EVERY character, environment, and object asset needs one before generate_voiceover (the server enforces this; fire the jobs for all assets, then one await_jobs). Async — the job writes the image onto the asset row: await_jobs(project_id), then list_assets and view_image the file_path to check likeness.
set_character_voice
Bind a TTS voice to a character asset — required before generate_voiceover for every character with dialogue (the narrator's voice is separate: set_narrator_voice). Browse ids with list_voices.
list_voices
List available TTS voices (id, label, preview audio URL) for a provider: "minimax" (default engine) or "elevenlabs". Match the project's voice_tts_provider (see get_project) so picked ids work with its engine.
set_narrator_voice
Set the project's narrator TTS voice — required before generate_voiceover whenever the script has narration. Browse ids with list_voices. (Character dialogue voices are separate: set_character_voice.)
list_voice_blocks
List the project's voice blocks (per-speaker narration chunks) with their audio status and assigned voices.
update_voice_block
Override one voice block's voice or playback volume (block ids from list_voice_blocks). Re-run generate_voiceover for the block afterwards if you changed its voice — existing audio is not regenerated automatically.
rescan_voice_blocks
Re-extract voice blocks from the active script WITHOUT touching assets or their reference images — the non-destructive alternative to scan_script after a script edit. Existing audio is superseded by the new block split, so re-run generate_voiceover afterwards. Async — returns {job_id}.
generate_voiceover
Generate TTS audio for the project's voice blocks. Without voice_block_ids it fills gaps: only blocks with no audio yet run, so re-calling it is always safe (already-generated and currently-generating blocks are skipped, never re-billed). Pass voice_block_ids to explicitly REgenerate those blocks (e.g. after changing a block's voice). Speakers must have voices bound first — set_narrator_voice / set_character_voice. Optional editable_sections/settings apply to every selected block (see get_section_template("voice_block") and list_models("voice_block")). Async — returns one job per block.
generate_storyboard
Plan the full visual storyboard: segments, shot pacing, image/video prompts, overlays, continuation chains — driven by the channel's director and art styles. Requires voiceover to exist (timing comes from it). BEFORE calling: confirm the project's asset_mix with your user (image vs video vs generated_graphic percentages, update_project) — the storyboard plans against it and video-heavy mixes multiply the later render cost. Async — returns {job_id}; this is the longest LLM step.
get_segments
List the storyboard's segments (narration span, type, duration, creative direction). The 1-based segment_number is the handle every segment tool takes (update/split/combine/continuation/regenerate) — you never need a UUID. Each segment also reports `continues_from_segment`. When set, this shot is a CONTINUATION of that earlier segment: its rendered frame carries over (same composition, characters, and setting) and only the delta changes — an added overlay, a shifted expression, a closer angle, a slow reframe. Null means a fresh, independent shot. The storyboard plans these chains automatically; adjust them with set_segment_continuation.
get_segment_assets
List one segment's assets (images/video/overlays) including their status, config (prompts, model), and public URLs of rendered files — pass an image's public_url to view_image to actually look at it.
regenerate_segment_asset
Regenerate a segment's primary image or video with optional overrides — the API equivalent of the editor's expert drawer. asset_type: "image" | "video" (for a video segment, "image" targets its start frame). Use a different model, override prompt sections (see get_section_template("segment_image")), or tweak settings (e.g. image quality), then re-run just this asset. Async — returns {job_id}.
change_segment_type
Change a segment's visual type: "image" | "video" | "overlay_scene". carry_frame=true reuses the already-rendered image as the video start frame (or vice versa) instead of recreating it.
update_segment_content
Rewrite one segment's creative direction from feedback ("make this shot a close-up", "show the machine from above") — an LLM rewrites the shot's prompts; continuation links, SFX, and overlays are preserved. The visual assets reset to not_started: re-render them afterwards (generate_segments or regenerate_segment_asset). For a precise prompt tweak with no rewrite, use regenerate_segment_asset with editable_sections instead.
split_segment
Split a segment at the given time offsets (ms, 1-3 cuts → 2-4 parts). inherit_index picks which resulting part keeps the original creative data. Later segments renumber — re-check get_segments before further edits.
combine_segments
Merge a segment with an adjacent one (segment numbers must be neighbors). keep: "this" | "other" — whose creative data survives. Later segments renumber — re-check get_segments before further edits.
set_segment_continuation
Make a segment's image render as a continuation of an EARLIER segment's frame (same composition evolving — the storyboard's continues_from_segment, settable after the fact). continues_from is that earlier segment's number; pass 0 to clear the link. Regenerate the segment's image afterwards — the reference is applied at generation time.
add_segment_sfx
Attach a sound effect from the audio library to a segment (find track ids via browse_audio_library with category="sfx"). Re-run build_scenes to get it onto the timeline.
remove_segment_sfx
Remove a sound effect from a segment. With one SFX attached, no name needed; with several, pass sfx_name (the asset name shown by get_segment_assets).
generate_segments
Render every actionable segment asset (images, video clips, overlays) across the project, in dependency order. THE most expensive call in the pipeline: ALWAYS dry_run=true first, show your user the estimate next to get_credit_balance, and wait for a fresh yes before the real run — prior blanket permission ("do the whole thing") does not cover this spend. Pass segment_numbers to render only a subset — e.g. segments 1-18 for the opening minute before committing to the full video. Safe to re-run: completed and currently-generating assets are skipped, so a second call only picks up new/failed work. Async — one job per asset; await_jobs until all complete.
build_scenes
Compile segments + assets + voiceover into the editor/render timeline (scenes). Run after segment assets are complete, before export.
list_scenes
List the project's scenes (composition layers, durations, layout).
director_note
Edit ONE scene with a natural-language note (the same director chat the editor UI uses): move/restyle/add/remove layers and overlays, retime, etc. Synchronous — returns the applied mutations + updated scene. Use list_scenes to find scene ids; for notes spanning the whole video use project_director_note instead.
project_director_note
Apply a project-WIDE director note ("make the intro punchier", "all captions bigger", "tighten pacing in the back half"). A routing pass picks only the scenes the note applies to and edits each one. Synchronous — a few seconds per affected scene. Returns the per-scene results; re-run export_video afterwards to see changes in the final render.
export_video
Render the final MP4 (Remotion). Fetches the current timeline and queues the render. Async — poll get_workflow_status for the video_export job, then call get_video_url.
get_video_url
Download URL for the most recent completed export.
list_styles
List the channel's style rows (variable groups). Styles hold the art_style / narrative_style / director_style / script_prompt fields that drive every generation step, plus any custom @variables.
get_style
Fetch one style row — its inputs (reference material) and analyzed fields (art_style, narrative_style, director_style, script_prompt, ...). Show fields to the user for review; fine-tune with update_style_fields.
update_style_fields
Hand-edit a style's analyzed fields after reviewing them — e.g. tighten the art_style wording or adjust the director_style pacing rules. `fields` is the FULL flat dict to write: {key: {"value": str, "applies_to": [...]}} (fetch with get_style, modify, send back). Editing fields does NOT trigger re-analysis, so your edits stick.
list_style_presets
The curated preset catalog for the no-AI style creation path, grouped by axis (art_style / narrative_style / director_style). Show the user the labels + descriptions and let THEM pick one per axis — don't choose silently. Art presets include preview image URLs (view_image works on them). Create with create_style(presets={axis: id, ...}) — instant, no analysis job. Full field text lands on the style row (get_style shows it after creation).
create_style
Create a style. Two mutually exclusive paths: References (best): inputs=[{"input_type": "youtube" | "text", "value": "<url or description>"}] — YouTube videos are watched and text directions read; async analysis writes the style's art/narrative/director fields: await_jobs(style_id=...) before using the style. (Image/video FILE references require the multipart REST endpoint POST /styles.) Presets (instant, no analysis): presets={"art_style": id, "narrative_style": id, "director_style": id} — all three axes, ids from list_style_presets.
analyze_style
Re-run style analysis (after changing a style's inputs). Async — await_jobs(style_id=...) until the style_analysis job completes.
generate_style_template
Render one of a style's two template images — a REAL step of style setup, not an optional extra: a style isn't finished until both its character and environment templates are rendered (the app shows them on the style card). Asset reference images render against them (characters → character template; environments and objects → environment template), and segment renders fall back on them when a shot has no asset reference — so finish BOTH before generate_asset_reference. Run once per template_type ("character" | "environment") for every new style; skip only types the style already has (get_style shows them). Async — await_jobs(style_id=...), then get_style.
delete_style
Delete a style (e.g. a failed analysis experiment). Don't delete a style that projects still use as their default — rebind them first with set_project_style.
set_provider_key
Register a BYOK provider API key (encrypted at rest, BYOK plan only). Jobs whose model belongs to this provider then run on YOUR key and charge 0 credits. Providers: openai, gemini, anthropic, fal, elevenlabs, minimax.
list_provider_keys
List registered BYOK providers (masked — only the last 4 characters).
whoami
Verify the connection: the account email and plan behind the current credential. Call once after connecting — before creating anything — to confirm you're on the right account; costs nothing.
get_credit_balance
Current credit balance + plan info. Check before expensive steps (a full segment render can cost hundreds of credits — generate_segments dry_run gives the estimate). Jobs covered by a BYOK provider key bill 0.
browse_audio_library
Browse the audio library for background music and sound effects. category: "music" | "sfx". Returns track ids for add_music_track / add_segment_sfx.
list_music_tracks
List the project's background music tracks (volume, loop, timing).
add_music_track
Add background music to the project from the audio library (find track ids with browse_audio_library, category="music"). Defaults loop the track under the whole video at bed level (volume 0.2 ≈ -14 dB under narration — don't raise it without being asked); re-run export_video to hear it.
update_music_track
Tweak a music track. fields keys: name, volume (0-1), loop, start_frame, duration_frames, position, trim_start_frame, trim_end_frame.
remove_music_track
Remove a music track from the project.
view_image
Fetch a rendered Framesail image so you (and your user) can SEE it — pass a URL from get_segment_assets, get_style, or asset endpoints. Returns the image inline. Only Framesail media URLs are allowed.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"framesail ai": {
"framesail": {
"type": "streamable-http",
"url": "https://api.framesail.com/mcp",
"headers": {
"Authorization": "Bearer fsk_YOUR_API_KEY"
}
}
}
}
}McpServers
{
"framesail": {
"type": "streamable-http",
"url": "https://api.framesail.com/mcp",
"headers": {
"Authorization": "Bearer fsk_YOUR_API_KEY"
}
}
}Framesail is an AI video studio built for one job: long-form (faceless youtube) video. It locks character and environment references up front and renders every shot against them — the same characters, the same world, from the first shot to the last. The MCP server exposes the entire pipeline, connecting to 5+ ai providers, so Claude or any agent can take a brief to a finished video.
Connect
claude.ai / Claude Desktop (OAuth — no key handling): Settings → Connectors → Add custom connector →
https://api.framesail.com/mcp. A browser login opens; approve the consent screen.Claude Code / Cursor / other clients: use the server config with an
fsk_ API key from your account page. Every connection is revocable there.What the tools cover
Channels & projects · script generation and asset scanning · locked reference images and art styles · word-timed voiceover (ElevenLabs / MiniMax) · storyboard planning · segment rendering and final MP4 export · credit balance and job status. Every tool carries a title and safety annotations.
Access
API & MCP access is available on Framesail's Pro and BYOK plans — see pricing. With BYOK, jobs covered by your own provider keys bill zero platform credits.
Docs: framesail.com/developers · Registry:
com.framesail/framesail · Support: support@framesail.comSign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
