Varosity MCP Server

v4 Bible step — generates a creative bible for a run BEFORE storyboard planning. Calls Claude to produce a premise, visual philosophy, and cast of characters/locations with locked descriptions, then generates one Flux reference image per character and location. Writes the result to runs.bible and returns the BibleDocument. Open a bible-phase approval gate after calling this so the operator can review the character references before any storyboard is planned.

Generates a branded end-card PNG from brand identity (name, tagline, color palette, logo). Uploads the image to varosity-assets and attaches it to the brand as role='end_card'. The render bridge automatically picks up this asset for the next project stitch. Returns { asset_id, url }.

Generate or EDIT an image. This is the tool for ALL image models (kind=image — flux-1-schnell, recraft-v3, aurora, dall-e-3, gemini-3.1-flash-image, nano-banana, etc.). Synchronous (1–3 s): returns { imageUrl, modelId } DIRECTLY — there is no job to poll and no get_job step (that's video only). IMAGE-TO-IMAGE: pass referenceImageUrl (a public image URL) to edit/restyle a source image while preserving its subjects — use modelId "nano-banana" for best identity/element preservation (e.g. keep a logo or face, redesign around it). Do NOT pass image models to generate_video. For end-user choice among candidates, prefer pick_reference_images. Scope required: generate:image.

Generate a music track. Returns trackId + audioUrl when ready.

Generate voiceover + music for a storyboard from its plan.audio section (ElevenLabs BYOK). Writes voiceover_url and music_url to the storyboard row — render_storyboard then injects them into the project's audio tracks. Non-fatal when ElevenLabs is not configured; returns { ok: false, reason } instead of throwing.

Generate a single composite grid image covering all shots in a storyboard — best when shots share a consistent visual style or the operator wants one unified reference sheet. Binds the result to the storyboard and auto-attaches it to every shot at render time. Use generate_storyboard_keyframes instead when each shot has meaningfully distinct content. Call suggest_storyboard_mode first if unsure. Requires storyboards:write scope.

Generate one keyframe still per shot in parallel — best when shots have distinct content (different characters, locations, or visual moods). Returns ordered asset IDs bound to the storyboard. Use generate_storyboard_grid instead when shots share a unified visual style and a single reference sheet suffices. Call suggest_storyboard_mode first if unsure. Requires storyboards:write scope.

Submit a VIDEO render job — modelId must be a video model (kind=video; e.g. veo-3.1, kling-3.0, ws-pika-2.2). For images use generate_image (NOT this tool — image models like flux-1-schnell/recraft-v3 are not video). Returns { jobId, projectId }. jobId == shotId — poll status via get_job until status='succeeded', then retrieve outputUrl. Always call pick_reference_images first if the user has not supplied a reference image; pass the chosen URL as reference_image_url. For AVATAR / LIP-SYNC models (omnihuman, heygen-photo-avatar, muapi-latentsync): pass the source photo as reference_image_url AND the spoken audio track as audio_url (a public mp3/wav URL) — the avatar's lips track THAT audio instead of provider-generated TTS. For muapi-latentsync, reference_image_url is the source VIDEO url. Per-model knobs (e.g. HeyGen avatarId/voiceId/engine) ride on providerOptions. Pass project_id from create_project to group all shots from a run into one project. Scope required: generate:video.

Synthesize speech from text. Returns { audioUrl }. Pass voiceId for the provider's voice. Optionally set modelId to a Varosity voice model (elevenlabs-tts, openai-tts-1, deepgram-aura-2); defaults to ElevenLabs. Scope required: generate:voice.

Create a new empty project. Returns { projectId, slug }. Pass projectId to generate_video so all shots from a run land in one project. Create once per run, not once per shot.

Clone a template into a fresh project owned by the caller. Returns { projectId, shotCount }.

Permanently delete a project and all its shots. Cannot be undone.

Fetch a single project + its shot list.

Stitch every shot in a project into a single MP4. Returns the final URL.

Render video for an existing idle shot created by render_storyboard. Reads the shot's model, prompt, duration, and bound reference images from the DB, then submits to the provider. Returns { jobId, modelId, projectId }; poll via get_job.

v4 Director — materializes an approved storyboard into the existing Studio primitives: ensures a project, inserts one shot per plan.shots[] (storyboard_shot_index set), binds the grid asset to every shot (Mode A) or the per-shot keyframe (Mode B) via shot_assets. Idempotent on a single storyboard. Returns project_id + ordered shot_ids; callers kick off per-shot generate + stitch via existing endpoints.

List the caller's brand agents. Brand-scoped tokens see only their permitted brands.

Kick off a single run for a brand. Inserts a varosity.runs row with status='queued' and returns it. The agent loop walks the run forward via `generate_video`, the runs PATCH endpoint, and `gate_decide`.

Claude-powered brand run planner. Reads the brand's identity pack and recent memory (characters, locations, past performance, published assets) and returns a structured RunPlan with per-shot imagePromptHint, voiceover script, and platform routing. Call before generate_video when operating as a brand agent. Requires brand:read scope.

v4 Director — Claude-powered storyboard planner. Emits an 8-section plan (premise / visual_style / characters / locations / shots / audio / continuity / mode_recommendation) and persists it to varosity.storyboards. Brand context, project Style Bible, and typed Asset Library reuse all flow into the prompt. Caller can pass mode_hint to force grid vs keyframes; otherwise the Director picks.

Recommend the best models for a shot. Pass aspectRatio and budgetPriority for better results. Returns ranked list with reasoning.

v4 Director — heuristic-only routing between Mode A (grid) and Mode B (keyframes) for a brief. Cheap, no LLM call. Used by the canvas brief bar pre-plan; the Director's mode_recommendation is canonical once a plan exists.

Register a new webhook. Returns the signing secret ONCE — store it server-side.

Revoke a webhook by id. Irreversible.

Trim one source recording into one or more hosted mp3 clips. Provide segments as [{start,end}] in seconds; returns { clips: [{url,start,end,bytes}] }. The clip URLs feed straight into clone_voice as sampleUrls. Scope required: generate:voice.

Clone a voice from audio samples (Instant Voice Cloning). Pass name + sampleUrls (public audio URLs; 30s–2min of clean speech works best) and optionally provider (elevenlabs default, cartesia, fish-audio). Returns { voiceId } usable immediately in generate_voice (set voiceModel to the matching provider for cartesia/fish). The clone is private to you. Scope required: generate:voice.

Design a brand-new voice from a text description (ElevenLabs Voice Design). Returns audition previews [{ generatedVoiceId, audioUrl }]. Pass voiceName to also save the first preview as a reusable voice and get its { voiceId }. Scope required: generate:voice.

Apply an operator decision to a run's open gate. Decisions: approved | revised | rejected | auto_approved. Run status transitions: approved/auto_approved → 'approved', revised → 'briefing', rejected → 'rejected'.

Make any AI-generated asset compliance-grade: embeds a signed C2PA manifest, an invisible watermark + perceptual fingerprint (durable re-discovery), a visible per-jurisdiction disclosure label, a Claude claim-risk scan, and a tamper-evident audit-log entry. Works across any model.

Poll a video render job (jobId == shotId). Returns status + outputUrl when done. Video renders take time: fast models (LTX, ws-pika) ~30s; Kling 3.0 / Veo 3.1 / Seedance 60–120s; up to ~3min under load. `running` past 60s is NORMAL — keep polling every ~5–8s until status is `succeeded` or `failed`. Do not conclude a job is hung before ~3–4 minutes. `succeeded` always carries an outputUrl.

List available generation models with pricing and capabilities. Filter by kind (video, voice, music, image) to narrow results. byokPricePerSec = BYOK/agent rate (your own API key); creditsPricePerSec = platform credits rate (byokPricePerSec × 1.05). Check unavailable=true before submitting — unavailable models reject immediately. Use suggest_model for AI-assisted selection.

Generate N candidate reference images in parallel for the user to choose from BEFORE video generation. Call this when the user has not supplied their own reference image. Returns an array of {index, imageUrl} objects — show all of them to the user with their index numbers and ask which one they prefer. Pass the chosen imageUrl as reference_image_url in the subsequent generate_video call. Default count is 3. Uses the same image model as generate_image.

List the user's projects, most recently updated first (max 50). Returns id, name, slug, aspect_ratio. Use get_project to fetch shots for a specific project. For brand-agent runs, call create_project first and reuse its id across all generate_video calls — do not create a new project per shot.

Fetch the latest versions of all Varosity-managed skills from varosity.ai. Returns an array of {slug, version, content, suggested_paths} for each skill. suggested_paths lists install locations for common MCP runtimes (Hermes, Claude Code, Claude Desktop, generic). Write content to the path that matches your runtime. Call at the start of any video production session or when tool schemas feel stale.

v4 Director — re-rolls a single keyframe panel without disturbing the others. Replaces the asset_id at storyboards.keyframe_asset_ids[shot_index]. Optional prompt_override redirects that one panel.

Generate a sound effect from a text prompt (ElevenLabs sound generation). Returns { audioUrl }. Optionally set durationSeconds (0.5–30) and promptInfluence (0–1). Scope required: generate:voice.

Curated storyboard templates (Product demo, Testimonial, Social hook, Explainer). Clone with create_project_from_template.

Fire a dummy shot.generation.completed event at one of your webhooks (signature-verify smoke test).

Speech-to-text + optional speaker diarization (ElevenLabs Scribe). Returns { languageCode, durationSec, text, speakers, segments } where segments are contiguous same-speaker runs with start/end seconds — use them to pick clean windows (e.g. for clip_audio → clone_voice). Scope required: transcribe:audio.

Verify whether an asset is AI-generated and inspect its provenance: C2PA content credentials (present/valid/issuer), durable watermark + fingerprint match, and history. Public — no API key required. Satisfies the EU AI Act Article 50 detection obligation.

Speech-to-speech: convert a source recording (audioUrl) into a target voice (voiceId) while keeping the original delivery/performance. Returns { audioUrl }. Scope required: generate:voice.

List voices available to generate_voice. Returns the built-in provider voices (ElevenLabs / OpenAI TTS / Deepgram Aura 2) plus the user's saved library. Each entry has { voiceModel, voiceId, name, description } — pass voiceModel as modelId and voiceId as voiceId to generate_voice. Voice IDs are provider-specific (e.g. Deepgram wants 'aura-2-thalia-en', not 'aura'); use these exact ids.

List the caller's configured webhook endpoints (secrets are masked).