Connect HeyGen to Claude: Scale Video Agents and Voice Synthesis

If you need to connect HeyGen to Claude to automate personalized video campaigns, orchestrate interactive video agents, or scale multilingual video translation pipelines, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and HeyGen's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on connecting HeyGen to ChatGPT or explore our broader architectural overview on connecting HeyGen to AI Agents.

Giving a Large Language Model (LLM) read and write access to a computationally heavy platform like HeyGen is an engineering challenge. You are not just dealing with simple CRUD operations. You are managing asynchronous rendering pipelines, stateful video streaming sessions, and strict API quotas. Every time you want an AI agent to generate a video or translate a clip, you have to manage the polling logic, the webhook callbacks, and the complex nested JSON schemas required to render an avatar correctly.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for HeyGen, connect it natively to Claude Desktop or your custom agent framework, and execute complex video generation workflows using natural language.

The Engineering Reality of the HeyGen API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models like Claude to discover and execute tools, the reality of implementing it against HeyGen's specific API architecture is painful.

If you decide to build a custom MCP server for HeyGen, you own the entire API lifecycle. Here are the specific challenges you will face:

Asynchronous Rendering and Polling State HeyGen does not generate video synchronously. When you call the video generation endpoint, the API immediately returns a video_id while the actual rendering is queued on their GPU clusters. LLMs are stateless by nature and struggle with asynchronous polling. If you expose raw endpoints to Claude, the model might hallucinate the completion state or immediately try to access a video URL that does not exist yet. You have to build specific MCP tools that guide the model to check the status of a video_id explicitly until the state resolves to completed or failed.

Complex Nested Payload Schemas Creating a video in HeyGen requires highly specific, deeply nested JSON payloads. You must specify the avatar ID, the background asset, the voice ID, the input text, the aspect ratio, and the positioning coordinates. If the LLM gets the schema wrong, the API will reject the request. A managed MCP server translates these requirements into standard JSON Schema parameters, complete with required field validations, ensuring Claude perfectly structures its generation requests before they hit the HeyGen API.

Direct-to-S3 Asset Upload Handshakes Managing custom backgrounds or audio files in HeyGen requires a multi-step upload handshake. You cannot simply send a 32MB video file in a JSON payload. You must first call the direct upload endpoint to get an AWS S3 pre-signed URL, execute a raw PUT request to S3 with your binary data, and then call a final completion endpoint to register the asset in HeyGen. Building this multi-step state machine into an MCP server from scratch is tedious.

Strict Rate Limits and GPU Quotas HeyGen enforces strict rate limits to protect its rendering infrastructure. When building your integration, it is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. If your AI agent spams the translation endpoints and HeyGen returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). Your Claude agent or LangGraph application is fully responsible for reading these headers and implementing its own retry and exponential backoff logic.

Instead of building all of this boilerplate from scratch, you can use Truto. Truto normalizes the authentication and pagination schemas, exposing HeyGen's endpoints as ready-to-use, documentation-backed MCP tools.

How to Generate a HeyGen MCP Server with Truto

Truto dynamically generates MCP tools based on the actual resources and documentation available for an integration. No tool is exposed unless it has a corresponding documentation record, ensuring Claude only sees well-curated, functional endpoints.

There are two ways to generate a HeyGen MCP server in Truto: via the UI or programmatically via the API.

Method 1: Generating via the Truto UI

For internal automation or testing, generating the server URL via the dashboard is the fastest approach.

1. Log into your Truto account and navigate to the integrated account page for your HeyGen connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can optionally filter the server to only allow specific methods (like read or write) or specific tool tags.
5. Copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4....

Method 2: Generating via the Truto API

For customer-facing AI agents or dynamic provisioning, you can generate MCP servers programmatically. Make a POST request to the /mcp endpoint for your specific integrated account.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude HeyGen Production Server",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The Truto API will validate that the HeyGen integration is AI-ready, generate a secure token, and return a JSON payload containing the url required for Claude to connect.

Connecting the HeyGen MCP Server to Claude

Once you have your Truto MCP server URL, you must register it with Claude. The URL contains a cryptographic token that securely maps to the specific HeyGen tenant account. No additional headers or authentication are required by default.

Method A: Via the Claude UI

If you are using the Claude Desktop application or Claude for Enterprise:

1. Open Claude and navigate to Settings.
2. Select Integrations (or Connectors depending on your plan).
3. Click Add MCP Server or Add custom connector.
4. Paste the Truto MCP URL into the Server URL field.
5. Click Add. Claude will immediately perform an MCP handshake, discover the HeyGen tools, and make them available for your active chat sessions.

(Note: If your team uses ChatGPT instead, the process is similar: Settings -> Apps -> Advanced settings -> Enable Developer mode -> Add Custom Connector).

Method B: Via the Manual Configuration File

For advanced users, developers, or headless agent frameworks, you can configure Claude to connect to the remote Truto server using the official MCP Server SSE (Server-Sent Events) transport layer.

Modify your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "heygen_truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN_HERE"
      ]
    }
  }
}

Restart Claude Desktop. The application will use npx to establish an SSE connection to Truto, seamlessly exposing the HeyGen tools to the LLM.

HeyGen Hero Tools for Claude

Once connected, Claude has access to the full suite of HeyGen proxy APIs. Here are the highest-leverage operations your AI agents can perform.

create_a_hey_gen_video

This is the core engine of the HeyGen API. This tool allows Claude to submit a deeply nested video generation payload, specifying the avatar, background, voice, and script. Because video rendering takes time, this tool returns a video_id which must be checked later.

"Draft a personalized welcome video script for a new enterprise client named Acme Corp. Once drafted, use the HeyGen video creation tool to generate a video using avatar ID 'anna_pro' and voice ID 'en-US-female-1'. Set the background to a solid blue color. Give me the video ID when it successfully queues."

get_single_hey_gen_video_by_id

This tool is critical for managing the asynchronous video lifecycle. Claude uses this tool to poll the HeyGen API for a specific video_id to determine if the rendering is processing, completed, or failed. Once completed, this tool returns the final video_url and thumbnail_url.

"Check the status of HeyGen video ID 'vid_987654321'. If it is completed, give me the final MP4 download link and the thumbnail URL. If it is still processing, wait 30 seconds and check again."

create_a_hey_gen_video_translation

HeyGen offers powerful AI video translation that syncs lip movements to new languages. Claude can pass an existing source video URL and an output language code to queue a heavy translation job.

"Take this MP4 video URL (https://example.com/source.mp4) and use the HeyGen translation tool to translate it into Spanish ('es'). Queue the job and give me the translation ID so we can monitor its progress."

create_a_hey_gen_video_agent

HeyGen's video agents are interactive, real-time streaming avatars. This tool creates a new active session, returning a session_id, an access token, and an endpoint URL required to connect to the WebRTC or WebSocket stream.

"Initialize a new HeyGen video agent session using the 'sales_rep_v2' avatar model. Give me the session ID and the connection credentials so our frontend application can connect to the stream."

hey_gen_video_agents_send_message

Once a video agent session is active, Claude can push real-time dialogue directly to the avatar. The avatar will immediately speak the text and animate accordingly.

"Send the following message to the active HeyGen video agent session 'sess_abc123': 'Hello there! I see you are looking at our enterprise pricing page. Do you have any questions about our SLA guarantees?'"

create_a_hey_gen_audio_text_to_speech

For voiceovers or headless audio synthesis, this tool generates an audio file from text using a specific HeyGen voice clone. It returns a direct URL to the generated audio file.

"Using the HeyGen text-to-speech tool, synthesize the following paragraph using voice ID 'ceo_clone_1'. Give me the direct audio URL when it is ready."

For a comprehensive list of every available HeyGen endpoint, including asset management, lipsyncing, and hyperframe rendering, consult the Truto HeyGen integration page.

Workflows in Action

Connecting Claude to HeyGen unlocks fully autonomous video generation and localization pipelines. Here are two real-world workflows that leverage this integration.

Workflow 1: The Autonomous Video Translation Pipeline

Marketing teams often struggle to localize video content across multiple regions. By connecting Claude to HeyGen, you can build an agent that automatically detects new English marketing assets and localizes them.

Prompt: "We have a new product launch video at this URL: https://s3.aws.com/corp/launch_en.mp4. I need you to translate this video into German, Japanese, and Brazilian Portuguese using HeyGen. Queue all three jobs, monitor their status, and output a markdown table with the final URLs when they are completely finished."

Tool Execution Sequence:

1. Claude calls create_a_hey_gen_video_translation three separate times, passing the source URL and the language codes (de, ja, pt-BR), receiving three unique translation job IDs.
2. Claude enters a polling loop, calling get_single_hey_gen_video_translation_by_id for each ID.
3. Claude reads the status. If any return processing, it waits.
4. Once all jobs return status: completed, Claude extracts the new url for each language and formats them into a final markdown table for the user.

Result: The user receives three ready-to-publish, lip-synced localized marketing videos without ever opening the HeyGen dashboard.

Workflow 2: Dynamic Sales Agent Initialization

Sales development representatives (SDRs) can use Claude to dynamically configure interactive video agents right before a high-value prospect joins a landing page.

Prompt: "I have a prospect from Acme Corp visiting our custom landing page. Set up a HeyGen video agent session using our standard sales avatar. Once the session is created, push an initial welcome message greeting them by name, mentioning that we noticed they use Salesforce, and asking how we can help. Give me the session ID to pass to the frontend."

Tool Execution Sequence:

1. Claude calls create_a_hey_gen_video_agent to spin up the required cloud infrastructure, returning the session_id and WebRTC credentials.
2. Claude drafts a highly contextualized greeting based on the user's prompt.
3. Claude calls hey_gen_video_agents_send_message, passing the session_id and the drafted text, queuing the avatar to speak immediately upon connection.
4. Claude returns the session_id to the user to embed in their application.

Result: The AI agent provisions a heavy-compute, real-time video session and injects personalized data into the avatar's memory bank instantly.

Security and Access Control

Exposing an enterprise HeyGen account to an LLM requires strict governance. Truto's MCP servers provide granular access controls at the token level, ensuring your agents only have access to what they explicitly need.

• Method Filtering: Limit an MCP server to strictly read-only operations by passing methods: ["read"] during creation. This allows Claude to list avatars or check video statuses, but prevents it from executing expensive video generations.
• Tag Filtering: Group HeyGen tools by function. You can configure an MCP server to only expose tools tagged with translations, ensuring a localization agent cannot accidentally touch video agent sessions.
• API Token Authentication: By default, possession of the Truto MCP URL grants access to the tools. For zero-trust environments, enable require_api_token_auth: true. This forces the client framework to pass a valid Truto API token in the Authorization header alongside the MCP handshake.
• Ephemeral Servers: Set an expires_at timestamp when creating the server. Truto relies on scheduled alarms and durable storage to automatically destroy the MCP server credentials at the exact moment of expiration, leaving no stale access vectors.

Strategic Wrap-up

Connecting Claude to HeyGen transforms static text generation into scalable, interactive video production. But building the integration layer to handle HeyGen's asynchronous rendering, multipart S3 uploads, and strict rate limits is a massive drain on engineering resources.

Truto eliminates this boilerplate. By translating HeyGen's complex API behaviors into normalized, documented MCP tools, you can give Claude secure, perfectly structured access to your video infrastructure in minutes instead of months.

Stop writing custom polling loops and OAuth refresh handlers. Focus on prompting Claude to create incredible video experiences, and let Truto handle the integration architecture.