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/developers 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, ChatGPT) 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 ChatGPT and 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.

Connect to ChatGPT

  1. In ChatGPT, turn on Settings → Security and login → Developer mode.
  2. Open Settings → Plugins (or chatgpt.com/plugins) and create a developer-mode app.
  3. Enter the MCP server URL https://mcp.videogen.io/mcp, add a name and description, and create it. ChatGPT runs the OAuth flow; approve the Sign in with VideoGen consent to finish.

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.

Tool reference

The server registers 34 tools. Ids are vg-prefixed opaque strings (vg_file_..., vg_work_..., vg_tool_..., vg_voic_..., vg_pres_...).

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, avatarPresenterId, featuredBRollFileIds, workflowAgentContext, 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, 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, avatarPresenterId, captionStyle, logoFileId, remixActions, + poll controls
storyboard_to_videoBuild a video from a structured storyboard of scenes. Composite. Does not accept remixActions.scenes, defaultGeneration, defaultDurationSeconds, quality, aspectRatio, workflowAgentContext, + 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). Composite.prompt, fileIds, durationSeconds, aspectRatio, numResults, isOutputTemporary, + poll controls
generate_avatarGenerate a talking-head avatar video from a presenter and an uploaded audio file. Composite.avatarPresenterId, audioFileId, 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
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)
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

Resources & account

ToolDescriptionKey parameters
list_avatar_presentersList available talking-head avatar presenters for generate_avatar and workflows.cursor, limit, voiceId
list_tts_voicesList available text-to-speech voices for narration, text_to_speech, and workflows.cursor, limit, includeDeprecatedVoices
list_languagesList supported languages for narration and captions.—
get_meFetch the authenticated team’s account details, including the current credit balance.—

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}
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}
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}
get_filePOST /v1/files/{fileId}/hydrate
list_filesGET /v1/files
list_avatar_presentersGET /v1/resources/avatar-presenters
list_tts_voicesGET /v1/resources/tts-voices
list_languagesGET /v1/resources/languages
get_meGET /v1/me

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
  • “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
  • “How many credits do I have left?” → 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}