GuidesBuild with VideoGenLibraries & SDKs

MCP server

Run the full VideoGen API from any MCP client.

The VideoGen MCP server is a Model Context Protocol server that exposes the full VideoGen API to any MCP client. Point your agent at it and it can generate videos from scripts, produce images, voiceovers, music, and avatars, upload files, export and remix projects, and manage runs, all authenticated with your own API key. It comes in two transports that expose the same tools: a hosted remote server (recommended) and a local server.

This is the API MCP server, which executes real API calls. It is distinct from the hosted documentation MCP at https://docs.videogen.io/_mcp/server, which is read-only and only answers questions about the docs. See Documentation MCP below.

Connect

Both transports wrap the official @videogen/sdk and expose the same tools. Get an API key from app.videogen.io/api first: every tool call runs as the team that owns the key.

The hosted server needs nothing to install or update. Point your MCP client at the endpoint and send your key as a bearer token:

1{
2  "mcpServers": {
3    "videogen": {
4      "url": "https://mcp.videogen.io/mcp",
5      "headers": {
6        "Authorization": "Bearer sk_videogen_live_..."
7      }
8    }
9  }
10}

The hosted server is stateless and multi-tenant. Your key is read from the request header, forwarded only to the VideoGen API, and never stored. Because it runs in the cloud and has no access to your machine’s filesystem, upload_file is not available on the remote server. Upload files directly through the VideoGen API (request a presigned upload URL and PUT the bytes yourself), then pass the returned vg_file_... id to other tools — or use the local server for files on your machine.

One-click install

Install the hosted server in one click, then authenticate with Sign in with VideoGen (or add your API key as an Authorization header afterward):

You can also install it from the command line:

$code --add-mcp '{"name":"videogen","type":"http","url":"https://mcp.videogen.io/mcp"}'

Local (stdio)

The local server runs as a subprocess that your MCP client launches with npx, so there is nothing to install ahead of time. It reads your key from the VIDEOGEN_API_KEY environment variable:

1{
2  "mcpServers": {
3    "videogen": {
4      "command": "npx",
5      "args": ["-y", "@videogen/mcp"],
6      "env": {
7        "VIDEOGEN_API_KEY": "sk_videogen_live_..."
8      }
9    }
10  }
11}

Your key stays on your machine. It is passed directly to the local server process and never sent anywhere except the VideoGen API.

VariableRequiredDefaultDescription
VIDEOGEN_API_KEYlocal only—Your VideoGen API key (local server). On the remote server the key travels in the Authorization: Bearer header instead.
VIDEOGEN_BASE_URLnohttps://api.videogen.ioOverride the upstream API base URL (e.g. for local development).

Other MCP clients

Windsurf, Cline, Goose, Claude Desktop, and most other MCP clients accept the same mcpServers JSON shown above (remote or local). Add the block to that client’s MCP config, then reload:

ClientWhere to add it
CursorSettings → MCP → Add, or the one-click link above
VS Code.vscode/mcp.json, or the one-click link above
Claude DesktopSettings → Developer → Edit Config (claude_desktop_config.json)
Claude (web/mobile)Settings → Connectors → Add custom connector — see Connect to Claude
Windsurf~/.codeium/windsurf/mcp_config.json
ClineMCP Servers panel → Configure MCP Servers
GooseSettings → Extensions → Add, or ~/.config/goose/config.yaml

Clients that support remote MCP over OAuth (Cursor, VS Code, Claude) can connect with just the server URL and authenticate via Sign in with VideoGen. Clients without remote/OAuth support use the local (stdio) block with a VIDEOGEN_API_KEY.

Sign in with VideoGen (OAuth)

MCP hosts that support OAuth — including Claude — can connect to the hosted server without an API key. Each user signs in through Sign in with VideoGen and the host calls the server on their behalf. The server advertises its authorization server via protected-resource metadata and supports Dynamic Client Registration (RFC 7591), so these hosts discover the auth server and register themselves automatically — there is nothing to paste but the server URL.

Use https://mcp.videogen.io/mcp for Cursor, Claude, VS Code, and other hosts that follow transport-level OAuth challenges.

Cursor: Prefer the remote config with an Authorization: Bearer API key above. Cursor’s OAuth client strips path components from authorization-server URLs (it does not follow RFC 8414 for path issuers), which breaks Sign in with VideoGen against Supabase Auth (…/auth/v1). The hosted /mcp endpoint works around this by advertising a pathless authorization server on mcp.videogen.io; if OAuth still fails after a Cursor update, use an API key.

Connect to Claude

  1. In Claude (claude.ai, Claude Desktop, or the mobile apps), open Settings → Connectors and click Add custom connector.
  2. Enter the MCP server URL https://mcp.videogen.io/mcp. Leave the OAuth Client ID / Secret fields in Advanced settings blank — VideoGen supports Dynamic Client Registration, so Claude registers itself automatically.
  3. Click Connect and approve the Sign in with VideoGen consent.

Each host uses its own OAuth redirect (callback) URL. VideoGen’s authorization server accepts these automatically through Dynamic Client Registration, so you don’t need to configure them — they’re listed here for reference:

HostOAuth callback (redirect) URL
Claude — web, Desktop, mobile, Coworkhttps://claude.ai/api/mcp/auth_callback
Claude Codehttp://localhost/callback and http://127.0.0.1/callback (loopback, port-agnostic)

Signed-in users can review and revoke connected apps at any time from the developer dashboard.

Long-running operations

Workflows, media tools, and project exports are asynchronous. The MCP server wraps each of these as a composite tool that starts the operation and, by default, polls until it reaches a terminal state (succeeded, failed, or cancelled) before returning the finished result. Every composite tool accepts these optional control fields:

FieldTypeDefaultDescription
waitbooleantrueBlock until the operation reaches a terminal state. Set false to return immediately with the run/execution id.
pollIntervalMsnumber—How often to poll while waiting, in milliseconds.
timeoutMsnumber—Maximum time to wait for a terminal state before giving up, in milliseconds.

When wait is false, use the matching get_* tool (e.g. get_workflow_run, get_tool_execution) to poll the returned id yourself.

Guidance resources

The API MCP also exposes operational guidance as static MCP resources (guidance://getting-started, guidance://async-tasks, guidance://workflows, guidance://tools-vs-workflows) plus matching no-arg tools (get_getting_started_guidance, get_async_tasks_guidance, get_workflows_guidance, get_tools_vs_workflows_guidance). Agents should call those tools when choosing workflows vs media tools, handling async polling on the hosted server, or following the run → remix → export flow. This is separate from the documentation MCP, which serves the full Fern docs site read-only.

Tool reference

The server registers 49 tools: 45 API tools plus four guidance tools. The remote transport also provides a hosted-only open_uploader widget. Ids are vg-prefixed opaque strings (vg_file_..., vg_enti_..., vg_work_..., vg_tool_..., vg_voic_...).

Workflows (end-to-end video)

ToolDescriptionKey parameters
script_to_videoTurn a script into a finished narrated video with visuals and captions. The script is narrated verbatim. Composite (waits by default).script, visualStyle, aspectRatio, visualPacing, quality, language, voiceId, voiceSpeed, actorEntityId, avatarQuality, featuredBRollFileIds, workflowAgentContext, scenes, remixActions, + poll controls
voiceover_to_videoBuild a narrated video from an already-uploaded voiceover audio file. Upload with upload_file first. Composite.fileId, visualStyle, aspectRatio, visualPacing, quality, language, captionStyle, logoFileId, workflowAgentContext, scenes, remixActions, + poll controls
slideshow_to_videoBuild a narrated video from an already-uploaded PDF or slideshow file. Upload with upload_file first. Composite.fileId, slideScripts, aspectRatio, language, voiceId, voiceSpeed, actorEntityId, avatarQuality, captionStyle, logoFileId, remixActions, + poll controls
storyboard_to_videoBuild a video from a structured storyboard of scenes. Composite.scenes, actorEntityIds, productEntityIds, defaultGeneration, defaultDurationSeconds, quality, aspectRatio, workflowAgentContext, remixActions, + poll controls
prompt_to_video_clipCreate a project and generate one short AI video clip from a text prompt (opening frame, then animate). Composite. Does not accept remixActions.prompt, imageFileIds, durationSeconds, aspectRatio, quality, + poll controls
list_workflow_runsList workflow runs, most recent first.cursor, limit, selfOnly
get_workflow_runFetch the current status and result of a single workflow run.workflowRunId
cancel_workflow_runRequest cancellation of an in-progress workflow run.workflowRunId

Provide at least two remixActions (e.g. ENABLE_CAPTIONS + SET_BACKGROUND_MUSIC) for a polished result. Available remix action types: SET_BACKGROUND_MUSIC, SET_LOGO, ENABLE_CAPTIONS, DISABLE_CAPTIONS, ADD_TRANSITIONS, RESIZE_PROJECT, CLEAN_UP_TRANSCRIPT, CONVERT_IMAGES_TO_VIDEOS.

Media tools

ToolDescriptionKey parameters
generate_imageGenerate an image from a text prompt, optionally conditioned on source images. Composite.prompt, quality, imageFileIds, aspectRatio, watermarkMode, numResults, isOutputTemporary, + poll controls
generate_video_clipGenerate a video clip from a text prompt, source images, or source videos. Composite.quality (STANDARD | HIGH), prompt, imageFileIds, videoFileIds, audioFileIds, generateAudio, durationSeconds, aspectRatio, watermarkMode, numResults, isOutputTemporary, + poll controls
text_to_speechConvert text into spoken audio using a selectable voice. Composite.ttsText, voiceId, speechLanguageCode, pronunciationReplacements, autoExpandPronunciationReplacements, voiceSpeed, numResults, isOutputTemporary, + poll controls
generate_sound_effectGenerate a sound effect from a text prompt. Composite.prompt, durationSeconds, promptInfluence, numResults, isOutputTemporary, + poll controls
generate_musicGenerate a music track from a text prompt. Composite.prompt, numResults, isOutputTemporary, + poll controls
generate_motion_graphicGenerate an animated motion graphic video from a text prompt (experimental, agentic). Outputs a transparent WebM overlay by default; set transparentBackground to false for an opaque MP4. Composite.prompt, fileIds, durationSeconds, aspectRatio, transparentBackground
generate_avatarGenerate a talking-head avatar video from an actor entity and an uploaded audio file. Composite.actorEntityId, audioFileId, avatarQuality, watermarkMode, numResults, isOutputTemporary, + poll controls
vectorize_imageConvert a raster image into a vector (SVG). Composite.imageFileId, watermarkMode, numResults, isOutputTemporary, + poll controls
remove_image_backgroundRemove the background from an image. Composite.imageFileId, watermarkMode, numResults, isOutputTemporary, + poll controls
remove_video_backgroundRemove the background from a video. Composite.videoFileId, watermarkMode, numResults, isOutputTemporary, + poll controls
upscale_imageIncrease the resolution of an image. Composite.imageFileId, watermarkMode, numResults, isOutputTemporary, + poll controls
upscale_videoIncrease the resolution of a video. Composite.videoFileId, watermarkMode, numResults, isOutputTemporary, + poll controls
image_3d_effectAdd 3D parallax motion to a still image, producing a video. Composite.imageFileId, watermarkMode, numResults, isOutputTemporary, + poll controls
list_tool_executionsList past tool executions, most recent first.cursor, limit, selfOnly
get_tool_executionFetch the current status and results of a single tool execution.toolExecutionId
cancel_tool_executionRequest cancellation of an in-progress tool execution.toolExecutionId

Projects

ToolDescriptionKey parameters
list_projectsList projects. API-created only by default; pass includeUiProjects for dashboard projects too.cursor, limit, selfOnly, includeUiProjects
get_projectFetch metadata and the shareable URL for a single project.projectId
export_projectExport a project to an MP4. Composite — waits until the download URL is ready by default.projectId, quality (STANDARD | HIGH | FULL_HIGH | ULTRA_HIGH), + poll controls
get_project_exportFetch the current status of a project export. Poll until status is succeeded, failed, or cancelled.projectId, exportId
remix_projectApply remix actions (music, logo, captions, transitions, natural-language edits) to an existing project.projectId, remixActions, saveAsNewProject
list_project_remix_actionsList the status of remix actions applied to a project.projectId

Files

ToolDescriptionKey parameters
upload_fileUpload a local file and wait until it is processed. Returns the file id (vg_file_...). Use it for voiceover_to_video, slideshow_to_video, logos, or B-roll. To upload a remote asset, download it first and pass its local path. Local (stdio) server only.filePath, displayName, type (IMAGE | VIDEO | AUDIO)
create_file_uploadCreate a pending file and return a presigned upload URL (same as POST /v1/files/upload). PUT the bytes yourself, then poll with get_file.displayName, type, isTemporary, transcript
get_fileFetch a file by id with freshly hydrated signed URLs for thumbnail, preview, and download renditions.fileId
list_filesList files visible to the current API key.cursor, limit

Hosted remote only:

ToolDescriptionKey parameters
open_uploaderOpen the hosted upload widget so a human can pick files in the browser (ChatGPT MCP Apps). Not counted in the 46 API tools above.—

Entities

ToolDescriptionKey parameters
list_entitiesList ACTOR, PRODUCT, and VISUAL_STYLE entities.entityType, cursor, limit
create_entityCreate an entity. Attach at least one image afterward with add_entity_reference.entityType (ACTOR | PRODUCT | VISUAL_STYLE), name, description
get_entityFetch one entity and its reference images.entityId
update_entityUpdate an entity’s display name and/or description.entityId, name, description
archive_entityArchive an entity so it no longer appears in lists or pickers.entityId
add_entity_referenceAttach an uploaded image (vg_file_...) as a reference. Use isDefault: true for the primary thumbnail.entityId, fileId, description, isDefault
remove_entity_referenceDetach a reference image from an entity.entityId, fileId

Guidance

ToolDescriptionKey parameters
get_getting_started_guidanceAuth, verify with get_me, id conventions, MCP vs SDK. Mirrors guidance://getting-started.—
get_async_tasks_guidancePolling, hosted wait caps, webhooks outside MCP. Mirrors guidance://async-tasks.—
get_workflows_guidanceRun → remix → export and each workflow tool. Mirrors guidance://workflows.—
get_tools_vs_workflows_guidanceSingle-asset tools (automatic model routing) vs full video workflows. Mirrors guidance://tools-vs-workflows.—

Resources & account

ToolDescriptionKey parameters
list_tts_voicesList available text-to-speech voices for narration, text_to_speech, and workflows.cursor, limit, includeDeprecatedVoices, query
list_languagesList supported languages for narration and captions.query
get_meFetch the account and team behind the API key (apiKeyId, apiKeyNickname, email, displayName, teamId). Use it as a connection test.—
get_app_deep_linkBuild a VideoGen app URL that opens a modal or navigates after sign-in (upgrade, buy credits, invite teammates, feedback, integrations, account settings, or a NAVIGATE destination). Prefer this when the user must complete something in the VideoGen UI that MCP tools cannot do inline. No API key required.action, plus action-specific fields (destination, articleSlug, provider)

MCP tool to REST endpoint

Each MCP tool maps to one or more VideoGen REST endpoints. Composite tools call the start endpoint and then poll the get endpoint until terminal.

MCP toolREST endpoint(s)
script_to_videoPOST /v1/workflows/script-to-video, then GET /v1/workflows/runs/{workflowRunId}
voiceover_to_videoPOST /v1/workflows/voiceover-to-video, then GET /v1/workflows/runs/{workflowRunId}
slideshow_to_videoPOST /v1/workflows/slideshow-to-video, then GET /v1/workflows/runs/{workflowRunId}
storyboard_to_videoPOST /v1/workflows/storyboard-to-video, then GET /v1/workflows/runs/{workflowRunId}
prompt_to_video_clipPOST /v1/workflows/prompt-to-video-clip, then GET /v1/workflows/runs/{workflowRunId}
list_workflow_runsGET /v1/workflows/runs
get_workflow_runGET /v1/workflows/runs/{workflowRunId}
cancel_workflow_runPOST /v1/workflows/runs/{workflowRunId}/cancel
generate_imagePOST /v1/tools/generate-image, then GET /v1/tools/executions/{toolExecutionId}
generate_video_clipPOST /v1/tools/generate-video-clip, then GET /v1/tools/executions/{toolExecutionId}
text_to_speechPOST /v1/tools/text-to-speech, then GET /v1/tools/executions/{toolExecutionId}
generate_sound_effectPOST /v1/tools/generate-sound-effect, then GET /v1/tools/executions/{toolExecutionId}
generate_musicPOST /v1/tools/generate-music, then GET /v1/tools/executions/{toolExecutionId}
generate_motion_graphicPOST /v1/tools/generate-motion-graphic, then GET /v1/tools/executions/{toolExecutionId}
generate_avatarPOST /v1/tools/generate-avatar, then GET /v1/tools/executions/{toolExecutionId}
vectorize_imagePOST /v1/tools/vectorize-image, then GET /v1/tools/executions/{toolExecutionId}
remove_image_backgroundPOST /v1/tools/remove-image-background, then GET /v1/tools/executions/{toolExecutionId}
remove_video_backgroundPOST /v1/tools/remove-video-background, then GET /v1/tools/executions/{toolExecutionId}
upscale_imagePOST /v1/tools/upscale-image, then GET /v1/tools/executions/{toolExecutionId}
upscale_videoPOST /v1/tools/upscale-video, then GET /v1/tools/executions/{toolExecutionId}
image_3d_effectPOST /v1/tools/image-3d-effect, then GET /v1/tools/executions/{toolExecutionId}
list_tool_executionsGET /v1/tools/executions
get_tool_executionGET /v1/tools/executions/{toolExecutionId}
cancel_tool_executionPOST /v1/tools/executions/{toolExecutionId}/cancel
list_projectsGET /v1/projects
get_projectGET /v1/projects/{projectId}
export_projectPOST /v1/projects/{projectId}/export, then GET /v1/projects/{projectId}/exports/{exportId}
get_project_exportGET /v1/projects/{projectId}/exports/{exportId}
remix_projectPOST /v1/projects/{projectId}/remix
list_project_remix_actionsGET /v1/projects/{projectId}/remix-actions
upload_filePOST /v1/files/upload, PUT bytes, then GET /v1/files/{fileId}
create_file_uploadPOST /v1/files/upload
get_filePOST /v1/files/{fileId}/hydrate
list_filesGET /v1/files
open_uploaderHosted upload widget (no direct REST equivalent)
list_entitiesGET /v1/entities
create_entityPOST /v1/entities
get_entityGET /v1/entities/{entityId}
update_entityPOST /v1/entities/{entityId}/update
archive_entityPOST /v1/entities/{entityId}/archive
add_entity_referencePOST /v1/entities/{entityId}/references
remove_entity_referencePOST /v1/entities/{entityId}/references/remove
list_tts_voicesGET /v1/resources/tts-voices
list_languagesGET /v1/resources/languages
get_meGET /v1/me
get_app_deep_linkApp deep link (no direct REST equivalent)

Example prompts

Once the server is connected, ask your agent in natural language. It selects the matching tool automatically:

  • “Generate a narrated video from this script with captions and background music” → script_to_video
  • “Upload this voiceover and turn it into a video” → upload_file then voiceover_to_video
  • “Make an image of a red sports car at sunset” → generate_image
  • “Create a product entity from this pack-shot image” → upload_file / open_uploader, then create_entity + add_entity_reference
  • “Read this text aloud in a calm voice” → list_tts_voices then text_to_speech
  • “Upscale this video to a higher resolution” → upload_file then upscale_video
  • “Export my project as an MP4” → export_project
  • “Add background music and a logo to my project” → remix_project
  • “Which account and team does this API key belong to?” → get_me

Documentation MCP

VideoGen also hosts a read-only documentation MCP server that lets AI clients query the API docs in real time. It answers questions about the API but does not call it. Connect it alongside (or instead of) the API server:

1{
2  "mcpServers": {
3    "videogen-docs": {
4      "url": "https://docs.videogen.io/_mcp/server"
5    }
6  }
7}