Connect HeyGen to ChatGPT: Generate AI Videos and Custom Avatars via MCP

If you want to automate digital content creation, you need to connect HeyGen to ChatGPT. By leveraging a Model Context Protocol (MCP) server, your AI agents can bypass manual dashboard operations to generate personalized videos, translate existing footage, orchestrate interactive video agents, and clone voices on demand. (If your team uses Claude, check out our guide on connecting HeyGen to Claude or explore our broader architectural overview on connecting HeyGen to AI Agents).

Giving a Large Language Model (LLM) read and write access to a sprawling generative video platform is a serious engineering challenge. You must map massive, nested JSON schemas into explicit tool definitions, handle multi-step asynchronous media workflows, and gracefully manage strict platform rate limits. Every time HeyGen updates a model parameter or deprecates an endpoint, your custom integration breaks.

This guide breaks down exactly how to use Truto to dynamically generate a secure, authenticated MCP server for HeyGen, connect it natively to ChatGPT, and execute complex video automation workflows using natural language.

The Engineering Reality of the HeyGen API

A custom MCP server acts as a self-hosted integration layer that translates an LLM's natural language tool calls into structured REST API requests. While the open MCP standard dictates how models discover and execute tools, the reality of implementing it against a vendor API like HeyGen is painful.

If you decide to build and host a custom MCP server for HeyGen, you assume ownership of the entire API lifecycle. You are no longer just writing prompts - you are managing distributed systems edge cases. Here are the specific integration challenges that break standard CRUD assumptions when working with HeyGen.

Asynchronous Generation and Polling Logic

HeyGen does not generate high-fidelity avatars or lip-sync videos in real time over a single HTTP request. Video generation is fundamentally asynchronous. When you submit a request to create a video, HeyGen returns a video_id in a pending state.

LLMs are notoriously bad at handling asynchronous state machines without explicit guidance. If your custom server does not provide both the initiation tool and a tightly scoped polling tool, the LLM will assume the video generation failed when the initial request doesn't return an MP4 link. You have to explicitly instruct the model via prompt injection or schema descriptions to enter a loop, sleep between calls, and query the get_single_hey_gen_video_by_id endpoint until the status changes from processing to completed.

Two-Step Direct-to-S3 Asset Uploads

Uploading custom background images, audio files, or PDF assets to HeyGen is not a standard multipart form data POST request. HeyGen uses a direct-to-S3 upload architecture.

To give ChatGPT the ability to upload files, your custom MCP server must coordinate a three-step dance:

1. Call the HeyGen API to initialize an upload, which returns a pre-signed AWS S3 URL and an asset_id.
2. Execute a raw HTTP PUT of the binary file data directly to the AWS URL.
3. Call the HeyGen API again to complete and finalize the asset upload.

If your custom MCP server tries to pass this complexity directly to the LLM, the model will hallucinate the S3 PUT request and the upload will fail. Your server layer must abstract this stateful upload flow into a single, cohesive MCP tool.

Rate Limits and 429 Enforcement

HeyGen enforces strict rate limits based on your account tier, capping concurrent video generations and API requests per minute. When these limits are breached, HeyGen returns an HTTP 429 status code.

Factual note on how Truto handles this: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream HeyGen API returns an HTTP 429, Truto passes that exact error back to the caller. However, Truto normalizes the upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) conforming to the IETF specification. The caller - in this case, your multi-agent framework or ChatGPT client - is strictly responsible for interpreting these headers and executing its own exponential backoff.

The Managed MCP Approach

Instead of forcing your engineering team to build, host, and maintain a custom MCP server, you can use Truto. Truto derives tool definitions dynamically from two existing data sources: the integration's internal resource routing and curated documentation records.

A tool only appears in the generated MCP server if it has a corresponding documentation entry. This ensures only well-documented, highly functional endpoints are exposed to the LLM. Truto automatically injects pagination logic, schema requirements, and authentication headers on the fly. You connect the account once, generate a cryptographic token URL, and pass it to your AI framework.

Creating the HeyGen MCP Server

Truto scopes every MCP server to a single integrated account. This means the resulting server URL contains a secure token encoding the specific tenant, the allowed tool filters, and the expiration time. You can generate this server via the user interface or programmatically via the API.

Method 1: Via the Truto UI

For ad-hoc agent testing or internal IT operations, the UI is the fastest path.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected HeyGen account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your parameters. You can filter by methods (e.g., read, write) or apply tool tags to restrict access.
5. Click Save and immediately copy the generated MCP server URL. (Store this securely; it functions as your authentication token).

Method 2: Via the API

If you are building a platform that programmatically deploys ChatGPT instances for your own customers, you should automate server creation.

Make a POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HeyGen Content Automator",
    "config": {
      "methods": ["read", "write", "custom"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API provisions the underlying KV infrastructure, applies your method configurations, and returns a ready-to-use URL:

{
  "id": "mcp_abc123",
  "name": "HeyGen Content Automator",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67g8h9i0j..."
}

Connecting the MCP Server to ChatGPT

With the secure URL generated, the next step is binding it to your ChatGPT instance. You can do this through the native UI or via a local proxy if you are running a custom agent architecture.

Method A: Via the ChatGPT UI

If you are using ChatGPT Pro, Team, or Enterprise, you can add the server directly as a custom connector.

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Toggle Developer mode on (MCP support requires this flag).
3. Under MCP servers / Custom connectors, click add a new server.
4. Enter a descriptive name (e.g., "HeyGen (Truto)").
5. Paste the Truto MCP URL into the Server URL field and click Save.

ChatGPT will immediately ping the endpoint, execute a JSON-RPC handshake, and cache the available HeyGen tools.

Method B: Via Manual Config File (Server-Sent Events)

If you are running ChatGPT Desktop or orchestrating agents locally via the open-source MCP specification, you can define the server in your local JSON configuration file. Truto's MCP servers support the SSE (Server-Sent Events) transport layer via a lightweight proxy command.

Add the following block to your configuration file (e.g., chatgpt_mcp.json or claude_desktop_config.json):

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

Hero Tools for HeyGen

Truto automatically maps dozens of HeyGen endpoints into normalized LLM tools. Do not try to overwhelm the context window with generic CRUD operations. Instead, focus your prompts on the high-leverage operations that actually drive video automation.

Here are 6 hero tools derived from the HeyGen API that unlock the most powerful workflows.

create_a_hey_gen_video

This is the core execution tool. It allows the LLM to submit a complex payload specifying the avatar, voice, background, and script to generate a synthetic video. Because the endpoint accepts a deeply nested JSON schema for video_inputs, Truto parses the documentation to ensure ChatGPT knows exactly how to structure the character and voice parameters.

"Generate a welcome video using the create_a_hey_gen_video tool. Use avatar ID 'joshua_formal_suit' and voice ID 'en-us-male-professional'. The script should be: 'Welcome to the Q3 kickoff. We have incredible metrics to review today.' Set the background to a solid hex color #1A1A1A."

get_single_hey_gen_video_by_id

Because video generation is asynchronous, ChatGPT needs a way to check status. This tool allows the model to query a specific video ID to retrieve its current processing state, duration, and ultimately, the final MP4 download URL and thumbnail URL.

"Take the video ID from the previous step and check its status using get_single_hey_gen_video_by_id. If the status is still 'processing', wait 10 seconds and try again. Once it returns 'completed', output the video_url to me."

create_a_hey_gen_video_translation

HeyGen excels at localizing existing content. This tool accepts a source video_url and an output_language. The LLM can orchestrate a workflow where it pulls a video link from your cloud storage, passes it to HeyGen, and requests a lip-synced translation.

"I have a product demo video at this URL: https://example.com/demo.mp4. Use the create_a_hey_gen_video_translation tool to translate it into Spanish (es-ES). Give me the translation job ID so we can track its progress."

create_a_hey_gen_video_agent

Interactive video agents allow you to spin up a live, WebRTC-enabled avatar session. This tool initializes that session, returning a session_id, an access token, and a WebSocket URL. It is the mandatory first step for building real-time conversational avatars.

"We need to start a live interactive session. Use the create_a_hey_gen_video_agent tool to instantiate a new agent. Return the session_id and the access_token so I can bind them to my frontend WebRTC client."

hey_gen_video_agents_send_message

Once a video agent session is active, you use this tool to feed it text dynamically. The agent will speak the text in real-time. ChatGPT can act as the brain of the agent, taking user input, generating a response, and pushing that response directly to the avatar via this tool.

"The user just asked about our pricing plans. Formulate a polite two-sentence answer, then push it to the active HeyGen avatar using the hey_gen_video_agents_send_message tool with the session ID we generated earlier."

create_a_hey_gen_audio_text_to_speech

Sometimes you only need a voiceover, not a full avatar render. This tool accepts raw text and a voice_id to rapidly generate an audio file. It is incredibly useful for podcast generation, dynamic IVR voice prompts, or accessibility narrations.

"Use the create_a_hey_gen_audio_text_to_speech tool. Take this 300-word blog post summary and generate a voiceover using a friendly, upbeat female British voice. Provide the final audio_url when complete."

For the complete inventory of available proxy tools, authentication schemas, and supported operations, check the HeyGen integration page.

Workflows in Action

Connecting an LLM to HeyGen via MCP fundamentally shifts how you build generative media pipelines. You stop writing rigid orchestration scripts and start defining outcome-oriented workflows. Here are two concrete examples.

Scenario 1: Automated Video Marketing Localization

Your marketing team uploads a new product feature video to an internal Slack channel. You want an AI agent to automatically detect the video, generate translated versions for EMEA markets, and post the links back to Slack.

"You are a localization agent. Read the latest message from the marketing Slack channel to find the source video URL. Send that URL to HeyGen to translate it into French, German, and Italian. Monitor the job statuses. When all three are complete, format a message with the final video links and post it back to the channel."

Agent Execution Path:

1. The agent parses the Slack message and extracts the MP4 URL.
2. It calls create_a_hey_gen_video_translation three times in parallel, passing the URL and specifying fr-FR, de-DE, and it-IT as the target languages.
3. The agent receives three distinct translation IDs. It enters a loop, calling get_single_hey_gen_video_translation_by_id every 30 seconds for each ID.
4. As the jobs complete, it collects the final url values from the JSON responses.
5. It formulates a final text summary and posts the payload to the external system.

Scenario 2: Dynamic Personalized Sales Outreach

A sales development representative (SDR) wants to generate 50 highly personalized introductory videos based on a list of prospects in a CRM. The agent needs to pull the prospect data, inject it into a script, and render the avatars.

"Look up the 5 newest inbound leads in Salesforce. For each lead, read their company name and job title. Write a custom 1-paragraph video script tailored to their role. Then, use HeyGen to generate an avatar video for each script using the 'joshua_formal_suit' avatar. Give me a table mapping the prospect's name to the final HeyGen video URL."

Agent Execution Path:

1. The agent queries the CRM tools (e.g., Salesforce via a separate Truto MCP server) to retrieve the 5 latest lead objects.
2. The LLM natively formulates 5 unique text scripts based on the company data (e.g., "Hi Sarah, I see you lead marketing at Acme Corp...").
3. The agent calls create_a_hey_gen_video 5 times, structuring the video_inputs payload with the custom scripts and the required avatar ID.
4. The agent polls get_single_hey_gen_video_by_id for the 5 generated task IDs until they return a completed status.
5. The agent outputs the final markdown table with the generated video_url for the SDR to use in their email cadence.

Security and Access Control

When you give an autonomous agent the ability to spend API credits and generate media, security must be explicit. Truto MCP servers implement architectural safeguards at the edge.

• Method Filtering: By configuring methods: ["read", "create"] during server creation, you strictly block the LLM from executing destructive operations like delete_a_hey_gen_video_by_id. The tools simply will not load in the ChatGPT interface.
• Tag Grouping: You can scope the MCP server to specific functional domains. If you only want the agent to handle audio, apply a tag filter so it only sees tools like create_a_hey_gen_audio_text_to_speech and list_all_hey_gen_audio_voices.
• Ephemeral Tokens: Use the expires_at property to grant ChatGPT temporary access. Truto enforces this via edge KV expiration and Durable Object cleanup alarms. Once the timestamp passes, the server ceases to exist, preventing persistent backdoor access to your HeyGen account.
• Double Authentication: For critical environments, enable require_api_token_auth. This forces the ChatGPT client to pass a valid Truto API bearer token in addition to the server URL, preventing unauthorized access if the token URL is accidentally logged or exposed in an open repository.

Moving Past Manual Dashboards

Requiring human operators to click through a web interface to generate synthetic video does not scale. By exposing HeyGen via a managed MCP server, you transform a web application into a deterministic, agent-callable utility.

Building this layer from scratch requires abstracting asynchronous polling loops, wrestling with nested direct-to-S3 asset uploads, and managing strict rate-limit propagation. Truto abstracts these infrastructure hurdles away entirely, letting your engineers focus on prompt logic rather than payload parsing.

Your AI models are ready to generate content at scale. You just need to give them the keys to the studio.