Overview

Connect any MCP-compatible AI agent to HeyGen video generation in a few clicks. No API key, no local server — add the connector, authenticate with OAuth, and start creating.

Add HeyGen as a connector in your AI agent and start generating videos in a few clicks — no API key and nothing to install. Usage draws on your existing HeyGen plan’s credits.

Add HeyGen to Your Agent

1. Open your agent's connector settings

   In your MCP-compatible agent (Claude, Cursor, Gemini CLI, Manus, and others), open the Connectors or MCP servers settings and choose Add custom connector.

2. Paste the HeyGen MCP endpoint

   Name the connector HeyGen and enter the remote MCP server URL:

   https://mcp.heygen.com/mcp/v1/
   
3. Authenticate with OAuth

   Click Connect and sign in to HeyGen to approve access. This one-time OAuth flow links the connector to your account — no API key required.

4. Start creating

   Ask your agent to generate a video — for example, “Make a 30-second product explainer with HeyGen.” It calls HeyGen’s tools directly and bills against your existing plan.

Menu names vary slightly by agent. For click-by-click instructions, see the per-product setup guides below.

What You Can Do

Once connected, your AI agent has access to the following tools:

Video Agent

Tool Name	Description
list_video_agent_sessions	Returns a paginated list of video agent sessions for the authenticated user, sorted newest-first.
create_video_agent	One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes.
list_video_agent_styles	Returns curated visual style templates available for Video Agent sessions. Each style controls scene composition, pacing, and aesthetics. Supports tag filtering (e.g. ‘cinematic’, ‘retro-tech’).
get_video_agent_session	Returns the current status, progress, video_id, and recent chat messages for a session.
send_video_agent_message	Sends a follow-up turn to a session created in either generate or chat mode; follow-up turns preserve the session mode. Send a message, a scene edit_plan built from GET /v3/videos/{video_id}/scenes, or both. Items may reference different scene snapshots from this session; none identifies the output draft. edit_version is not a document lock, so two edits from one version may both be accepted. Returns the current working draft in video_id. Poll GET /v3/videos/{video_id} for status. For a failed video, inspect failure_code and failure_message; the session endpoint also exposes known stop reasons in error.
get_video_agent_resource	Returns a single session resource (image, video, draft, avatar, voice, etc.) by its resource_id.
stop_video_agent_session	Halts an active agent run at its next checkpoint. Partial results are preserved.
list_video_agent_session_videos	Returns all videos produced within a Video Agent session, sorted newest-first.

Videos

Tool Name	Description
list_videos	Returns a paginated list of all videos in the account. Filterable by folder_id or title substring.
create_video	Creates an avatar video: a HeyGen avatar or an image speaks your script or audio with lip-sync. Choose Avatar III, IV or V with engine (Avatar IV by default). To generate a whole scene from a prompt instead, use POST /v3/models/videos.
get_video	Returns details for a video including status, video_url, thumbnail_url, duration, and failure info if applicable.
delete_video	Permanently deletes a video and its associated files. This action cannot be undone.
get_video_scenes	Returns a video’s scenes as it stands now, with the edit_version to send when editing. Each scene has a background, placed elements and a script. Skip element types you do not recognize. Geometry, text content, animations and background music are not described. A video whose editor document is still being prepared returns 409 resource_not_ready; retry after it advances.

Templates

Tool Name	Description
list_templates	Returns a paginated list of API-ready templates in the workspace. Templates are created and edited in the HeyGen web editor; only templates with variables defined are listed.
create_template	Creates a private template from one of your videos, copying its scenes, avatars, script and media. URL-to-Video and older editor videos return template_source_unsupported. The template starts with no variables; declare them with PUT /v3/templates/{template_id}/variables.
get_template	Returns template details including its variable schema (with current default values) and scenes. Variable defaults are returned in the same shape the generate request accepts, so a response can be edited and posted back. Only draft version 4 templates (the current editor format) are supported.
generate_from_template	Generates a video from a template by filling its variables. Use scene_ids to select, reorder or repeat the template’s existing scenes. Poll GET /v3/videos/{video_id} or use webhooks for completion. An idempotent replay returns the original response, not the video’s current state.
update_template	Renames a template. Other properties are edited in the HeyGen editor or through PUT /v3/templates/{template_id}/variables. Returns the template detail.
delete_template	Soft-deletes a template. It disappears from the list and can no longer be used to generate videos; videos already generated from it are unaffected. Templates managed by another HeyGen product cannot be deleted here.
set_template_variables	Replaces a template’s full set of variables: any variable you omit is removed. Media, character and voice variables bind to a node by element_id, listed under composition in GET /v3/templates/{template_id}. A text variable with match turns that text into a {{name}} placeholder.

Voices

Tool Name	Description
list_voices	Returns a paginated list of voices, filterable by type, engine, language, and gender. Speech generation supports Starfish, HeyGen Voice, and ElevenLabs. Each voice includes its speech default and available speech engines.
design_voice	Returns up to 3 voices matching a natural language description (e.g. ‘warm, confident female narrator’). Use the seed parameter to get different batches of results.
clone_voice	Creates a voice clone from an audio file. Returns a voice_clone_id that can be polled via GET /v3/voices/{voice_clone_id} until the status is ‘complete’. The resulting voice can be used with POST /v3/voices/speech and POST /v3/videos.
create_speech	Synthesizes speech from text with a catalog voice and returns an audio URL, its duration and optional word timestamps. Omit engine to use the voice’s saved default and settings, or set it per request; choose an ElevenLabs model with settings: {model_id: ‘eleven_v4’}. Requests that omit engine use HeyGen Voice for most public catalog voices. Set engine: ‘heygen_voice’ to explicitly request HeyGen Voice, or ‘starfish’ for Starfish. The legacy ‘orca’ input remains accepted; response engine values retain ‘orca’ for compatibility. A professional HeyGen Voice clone is synthesized by POST /v3/models/audio/tts instead. HTTP 400: the saved default or explicit engine is unsupported, not allowed on your plan, or incompatible with the requested locale or language. HTTP 403 (ai_vendor_access_restricted): workspace vendor policy blocks ElevenLabs and all of its model variants.
get_voice	Returns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is ‘complete’.
delete_voice	Deletes a voice clone you own and frees its place in your clone limit. A voice used by a template cannot be deleted. An unknown or already-deleted voice returns 404 voice_not_found; treat that as success in delete-then-list flows.

Audio

Tool Name	Description
search_audio_sounds	Searches the music or sound-effects catalog by natural-language description (type=music by default, or sound_effects). Returns tracks ranked by similarity, each with a download URL, paginated by cursor.

Video Translate

Tool Name	Description
list_video_translations	Returns a paginated list of all video translation jobs in the account.
create_video_translation	Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video_translation_id per language. Use mode: ‘speed’ (default) for fast turnaround or ‘precision’ for higher lip-sync quality.
list_video_translation_languages	Returns all supported target language names for video translation.
get_video_translation	Returns details for a translation job including status, output language, video_url, and failure info if applicable.
update_video_translation	Updates the display title of a video translation job.
delete_video_translation	Permanently deletes a video translation and its associated files. This action cannot be undone.

AI Clipping

Tool Name	Description
list_ai_clipping	Returns a cursor-paginated list of AI clip jobs in the authenticated user’s workspace, newest first.
create_ai_clipping	Submit a source video and return a job id immediately. The job runs asynchronously and produces one or more short clips per the requested output_settings. Poll GET /v3/ai-clipping/{id} or subscribe to ai_clipping.success / ai_clipping.fail webhooks.
get_ai_clipping	Returns the full job resource including produced clips, statuses, and presigned download URLs.
delete_ai_clipping	Soft-deletes an AI clip job and its clips.

Batches

Tool Name	Description
create_video_batch	Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll GET /v3/videos/batches/{batch_id} for per-item video ids and statuses.
get_video_batch	Returns batch aggregate status and one page of items with their video ids and statuses. Item statuses are one of queued, processing, completed, or failed.
bulk_video_statuses	Returns statuses for up to 100 videos in one request, addressed by comma-separated video_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids.

Video Translation Batches

Tool Name	Description
create_video_translation_batch	Submits up to 100 translation payloads, each shaped like POST /v3/video-translations, as one batch. A payload with several output_languages becomes one item per language, and items run independently. Returns 202 with a batch_id to poll. Send an Idempotency-Key to make retries safe.
get_video_translation_batch	Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API).
bulk_video_translation_statuses	Returns statuses for up to 100 video translations by video_translation_ids and/or batch_ids: queued, processing, completed, failed, or not_found. Each entry’s id is in video_id.

Lipsync Batches

Tool Name	Description
create_lipsync_batch	Submits up to 100 lipsync payloads as one batch, and items run independently. Returns 202 with a batch_id; poll GET /v3/lipsyncs/batches/{batch_id}. Send an Idempotency-Key to make retries safe.
get_lipsync_batch	Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API).
bulk_lipsync_statuses	Returns statuses for up to 100 lipsyncs by lipsync_ids and/or batch_ids: queued, processing, completed, failed, or not_found. Each entry’s id is in video_id.

Asset Batches

Tool Name	Description
get_asset_batch	Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API); for asset batches it holds the asset_id.
complete_asset_batch	Finalizes every uploaded file in a batch once all PUTs return 200. Files are ingested independently. Returns 202 with the batch_id; poll GET /v3/assets/batches/{batch_id} for progress. Safe to repeat.
create_asset_upload_batch	Returns up to 100 presigned upload URLs in one call. PUT each file to its upload_url with the returned headers, then call POST /v3/assets/complete/batches. Send an Idempotency-Key to make retries safe.
bulk_asset_statuses	Returns statuses for up to 100 assets by asset_ids and/or batch_ids: queued, processing, completed, failed, or not_found. Each entry’s id is in video_id.

User

Tool Name	Description
get_current_user	Returns the authenticated user’s profile, remaining credits or balance, and billing details.

Avatars

Tool Name	Description
list_avatar_groups	Returns a paginated list of avatar groups (characters). Each group contains one or more looks. Filterable by ownership.
create_avatar	Creates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous.
list_look_templates	Lists the look templates and Look Packs your workspace can apply with POST /v3/avatars/looks. Send an item’s id as template_id and its type as type. Filter by gender to match your avatar.
list_avatar_looks	Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group_id, avatar_type, and ownership. The look id is the avatar_id to pass when creating a video.
create_avatar_looks	Generates new looks for an existing avatar from reference_look_id. type: look_pack applies a Look Pack; type: template applies one look template and produces two looks. Billing happens when the request is accepted: an API key is charged 1 API credit per look, and a connected integration (OAuth, including MCP) the method’s standard price from workspace credits. Free-tier MCP access cannot use this endpoint. Poll GET /v3/avatars/looks/{id} until each look finishes.
get_avatar_look	Returns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status.
update_avatar_look	Updates the display name of an avatar look. Only supported for photo avatar and digital twin look types.
delete_avatar_look	Deletes an avatar look. Photo avatar, digital twin and kit-based looks can be deleted; studio avatars cannot. Deleting the last look in a group also deletes the group.
get_avatar_group	Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status.
update_avatar_group	Updates an avatar group you own. Currently sets default_voice_id, the voice this avatar uses by default; any voice in your workspace works, including clones. Public avatars cannot be updated.
delete_avatar_group	Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups.
create_avatar_consent	Starts the consent flow for an avatar group and returns a URL where the subject approves in their browser. Required before a private avatar can generate video. The link expires after 24 hours and accepts one submission.

Assets

Tool Name	Description
list_assets	Beta: may change with a few days’ notice. Lists a workspace member’s uploaded assets, newest first, with cursor pagination. username is required during the beta. Pass folder_id to narrow to one folder, or an empty value for the root.
create_asset_upload	Begin a direct-to-S3 upload. Returns an asset_id and a presigned upload_url; PUT the file bytes to upload_url, then call POST /v3/assets/{asset_id}/complete. Unlike POST /v3/assets (which proxies the bytes), this never sends the file through the API.
get_asset	Returns metadata for an asset in the caller’s workspace — including owner, upload timestamp, file type, and a publicly accessible URL.
delete_asset	Permanently deletes an asset. The asset must belong to the caller’s workspace and not already be deleted.
complete_asset_upload	Finalize a direct-to-S3 upload into a reusable asset. Call after the upload PUT returns 200. Idempotent: repeated calls return the same finalized asset.

Folders

Tool Name	Description
create_folder	Creates a folder at the root or inside parent_id. Pass its folder_id to POST /v3/videos or POST /v3/video-translations to file output there. Names need not be unique, so store the ids you receive. Send an Idempotency-Key to make retries safe.
get_folder	Returns one folder in your workspace, including one in the trash (is_trash). Use it to check that a stored folder_id still exists. Deleted folders and folders in other workspaces return 404.

Lipsync

Tool Name	Description
list_lipsyncs	Returns a paginated list of all lipsync jobs in the account.
create_lipsync	Replaces the audio on an existing video and re-animates the speaker’s lip movements to match the new audio. Use mode: ‘speed’ for fast output or ‘precision’ for high-quality lip-sync.
get_lipsync	Returns details for a lipsync job including status, video_url, caption_url, and failure info if applicable.
update_lipsync	Updates the display title of a lipsync job.
delete_lipsync	Permanently deletes a lipsync job and its associated files. This action cannot be undone.

Brand

Tool Name	Description
list_brand_glossaries	Lists the brand glossaries in your workspace. A glossary sets how terms are pronounced in generated speech and how they are handled in translation. Pass a brand_glossary_id when creating a video or translation to apply it.
create_brand_glossary	Creates a brand glossary. Pass the returned brand_glossary_id when creating a video or translation to apply it. name must be unique in the workspace, ignoring case; a duplicate returns 409. Term lists are optional and can be added later with PATCH.
get_brand_glossary	Returns one brand glossary with its full term list. Pronunciations affect generated audio only, not captions. Translation rules (do_not_translate_terms, forced_translations) apply only to translation features; a list is omitted from the response when it is empty. Tone settings are not returned here.
update_brand_glossary	Updates a brand glossary. A field you omit is left untouched, a list you send replaces the existing list in full, and an empty array removes every entry. A name already used in the workspace returns 409. Tone settings are never modified by this endpoint.
delete_brand_glossary	Deletes a brand glossary. This cannot be undone. Its pronunciation terms and translation rules stop applying to anything generated afterwards; videos already generated are unaffected, and requests that still reference it keep working.
list_brand_kits	Returns brand kits available in the authenticated user’s workspace. Each brand kit contains colors, fonts, and logos that can be applied to Video Agent sessions. Use the returned brand_kit_id with POST /v3/video-agents to generate on-brand videos.
create_brand_kit	Creates a brand kit by importing logos, colors and fonts from a public website; by calling it you confirm you have the rights to use those assets. The kit assembles in the background: poll GET /v3/brand-kits/{brand_kit_id} until status is completed. Send an Idempotency-Key to make retries safe.
get_brand_kit	Returns one brand kit with its colors, logos and fonts and the role each plays. While status is loading these are provisional; poll every 2 to 5 seconds until status is completed.
update_brand_kit	Updates a brand kit’s name or role assignments: color roles, main logo, heading and body fonts. Omitted fields are unchanged and null is rejected. Each role object you send replaces the existing one in full; {} clears a role and it stays cleared. Role edits return 409 until the kit is completed; shared kits return 403.
delete_brand_kit	Deletes a brand kit and its colors, logos and fonts. This cannot be undone. Videos already rendered with it are unaffected. A kit shared from another workspace cannot be deleted and returns 403.

Models

Tool Name	Description
generate_model_speech	Generate speech from the voice identified by voice_id. The request stays open until speech generation finishes. The response contains a URL to a 44.1 kHz mono WAV file. ### Voice and settings Use an ACTIVE HeyGen Voice clone in your workspace. heygen-voice-1-turbo speaks instant clones at lower latency and refuses professional clones. API-key billing accumulates fractional usage. OAuth requests, including MCP calls, are rounded up per request to whole billing units, so their effective cost can be higher. seed, speed, pitch_shift, and pitch_variance apply only to professional clones. Instant clones, including Turbo, accept and ignore these controls. ### Language Set language to the language of text. If you omit it, the language is detected from text. Successful responses include Content-Language, the language the speech was generated in. ### Limits and request ID The rate limit is 30 requests per minute per workspace member. Successful responses include X-Request-Id. Use this ID when you contact support about the request.
list_model_audio_voices	Returns model-backed audio voices, ordered newest first. With the default type=private, these are the voices in the caller’s workspace, professional and instant; mode tells them apart. With type=public, these are the voices HeyGen provides to every workspace. Use limit and token to retrieve additional pages.
create_model_audio_voice	Creates an instant voice with mode: instant from one recording, or a professional voice with mode: professional. Instant voices do not support retraining. Use POST /v3/models/audio/tts/stream for streaming speech; model defaults to heygen-voice-1. Instant voices ignore seed, speed and pitch controls. Mode is required for both creation and retraining. Retrains a professional voice when voice_id is set. The voice is PENDING while training; poll GET /v3/models/audio/voices/{voice_id} until it is ACTIVE or FAILED. A new voice in professional mode needs a free professional-voice slot; each purchased slot provides five pooled trainings per monthly billing period, including the first, and failed trainings do not count. Send an Idempotency-Key to make retries safe.
get_model_audio_voice	Returns one model-backed audio voice, owned by the caller’s workspace or public, and its current lifecycle state. PENDING covers queued and running work, ACTIVE is ready for inference, and FAILED is terminal. An instant voice is ACTIVE as soon as it can speak.
delete_model_audio_voice	Deletes the caller-owned model-backed audio voice. The voice is removed from subsequent reads. A professional voice cannot be deleted while its status is PENDING: wait for training to finish and retry. Deleting an instant voice that is still being created cancels it. Repeating a successful deletion returns the same successful response.
create_image_generation	Generate one to five portraits with identity_remix, the default and only supported mode. Provide one to five identity_images and exactly one item in reference_images. The output preserves the identity while following the reference image’s clothing, pose, composition, and background. Returns a generation_id to poll. The job completes when all requested images are available; partial results are not returned.
get_image_generation	Return the generation job status and ordered images with fresh download URLs once the entire job completes.
create_model_video	Generates a scene with its sound from a prompt using HeyGen Video (heygen-video-1). Set mode to text_to_video, image_to_video or reference_to_video; reference-to-video takes up to twelve references in total, and reference videos must be between 1:4 and 4:1. Returns 202 with a video_id; poll GET /v3/models/videos/{video_id}. Send an Idempotency-Key to retry safely; without one, each submission creates a new generation. To have an avatar speak a script, use POST /v3/videos.
get_model_video	Returns a HeyGen Video generation: pending, processing, completed, failed or cancelled. Completed results include a fresh video_url, duration and dimensions; failed results include failure_code and failure_message. Poll again to refresh an expired URL.

Filler Word Removal

Tool Name	Description
create_filler_word_removal	Submits a video for filler-word removal and returns a job id. The job cuts filler words and long silences and renders one cleaned video; if nothing changes, the charge is refunded. $0.30 per source minute, 1-minute minimum. Poll GET /v3/filler-word-removals/{id} or use webhooks.
get_filler_word_removal	Returns the job resource: lifecycle status, progress, and — once completed — the presigned download URL of the cleaned video plus removal statistics (num_cuts, reduction_pct, durations).

Supported Products

HeyGen Remote MCP works with any MCP-compatible agent, including:

• Claude (Web, Desktop, and Code)
• Codex CLI
• Cursor (available in the Cursor marketplace)
• Gemini CLI
• Lovable
• Manus
• Superhuman
• OpenAI
• and more

See the dedicated setup guide for each product for detailed instructions.

Connect Your Own Agent

You can integrate HeyGen Remote MCP into any custom agent or application that supports the Model Context Protocol. Just point it to the endpoint:

https://mcp.heygen.com/mcp/v1/

For security, HeyGen Remote MCP uses domain whitelisting. If your agent runs on a domain that isn’t already whitelisted, you’ll need to request access before it can connect.

Remote MCP

	Remote MCP
Setup	Add endpoint URL, authenticate via OAuth
Runs on	HeyGen’s hosted infrastructure
Authentication	OAuth (no API key needed)
Billing	Web plan + premium credits
Best for	Most users — quick setup, works everywhere

FAQ

Do I need an API key? No. Remote MCP uses OAuth authentication tied to your HeyGen account. No API key required.

Does this cost extra? No. Video generation uses the credits included in your existing HeyGen plan.

Which HeyGen plans support this? Remote MCP is available on all HeyGen plans.

Can I use my custom avatars and voices? Yes. Any avatars and voices available in your HeyGen account are accessible through Remote MCP.

What’s the difference between this and the HeyGen API? The HeyGen API gives you direct REST endpoints for programmatic control. Remote MCP wraps those capabilities so AI agents can use them conversationally — without you writing integration code.