How to Use the HeyGen MCP in Mastra AI

Q: Can Mastra AI automatically retry HeyGen API calls?

Yes. If a generatevideo call times out, Mastra's built-in workflow engine applies exponential backoff. It tries again without you writing custom retry logic.

Q: Is my custom avatar data safe in this MCP Server?

The server processes avatarid values and configuration payloads in a zero-trust environment. Vinkius requires only one endpoint token, and the execution environment vanishes entirely after the workflow finishes.

Automate video production workflows with conditional routing using Mastra AI and the HeyGen MCP Server.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect HeyGen MCP to Mastra AI

Create your Vinkius account to connect HeyGen to Mastra AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup HeyGen with Mastra AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Handle generation failures with Mastra AI

The `get_video_status` tool fits perfectly into Mastra's exponential backoff engine. Video rendering takes time, and simple polling often hits rate limits. You configure a workflow that checks the status, waits, and retries automatically if the render is still processing. If the job fails entirely, conditional branching takes over. The workflow catches the error, checks `get_api_profile` to see if you ran out of credits, and either alerts an admin or retries with a cheaper `generate_from_template` fallback.

Chain complex video creation steps

Call `get_template_details` to extract the exact variable structure of a specific template before you try to render anything. Mastra takes those variables, formats the user data, and passes the clean `variables_json` into `generate_from_template`. This prevents malformed requests from ever reaching the API. You build a multi-step MCP pipeline where data validation happens first, generation happens second, and `list_videos` verifies the final output in your account.

Batch process video translations

Trigger `translate_video` across an entire folder of source material using a scheduled Mastra workflow. The agent constructs the `body_json` for each file, queueing them up sequentially. You skip the manual monitoring completely. Add a human-in-the-loop step before the translation starts. Mastra's requireToolApproval pauses the workflow, letting a manager review the target languages and costs. Once approved, the agent fires the API calls.

Setup guide

Set up HeyGen MCP in Mastra AI

Prerequisites

Node.js 18+ and a TypeScript project
@mastra/mcp + @mastra/core packages
Active Vinkius subscription with a valid endpoint token

1

Install dependencies
Run npm install @mastra/mcp @mastra/core plus your preferred model provider (e.g. @ai-sdk/openai).
2

Configure the MCPClient
Create an MCPClient with your Vinkius endpoint as a URL object. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com.
3

Discover and inject tools
Call mcpClient.listTools() and spread the result into your agent's tools object. All HeyGen tools become native Mastra tools.
4

Run with any model
Swap openai("gpt-4o") for any AI SDK-compatible provider. Call agent.generate() and the agent routes tool calls through MCP automatically.

agent.ts

import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const mcpClient = new MCPClient({
  id: "heygen-mcp-client",
  servers: {
    "heygen-mcp": {
      url: new URL(
        "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
      ),
    },
  },
});

const agent = new Agent({
  name: "HeyGen Agent",
  model: openai("gpt-4o"),
  instructions: "You have access to HeyGen tools.",
  tools: {
    ...(await mcpClient.listTools()),
  },
});

const result = await agent.generate(
  "List recent HeyGen transactions"
);
console.log(result.text);

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by HeyGen. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect HeyGen now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about HeyGen MCP in Mastra AI

Install @mastra/mcp and instantiate a new MCPClient. Pass your Vinkius server URL in the servers object. Mastra automatically detects if the transport is Streamable HTTP or SSE.

Yes. If a generate_video call times out, Mastra's built-in workflow engine applies exponential backoff. It tries again without you writing custom retry logic.

Use the workflow to pull data from your database, then format it as a JSON string. Pass that directly into the variables_json parameter of the generate_from_template tool.

You configure requireToolApproval on the tool within your Mastra setup. The workflow halts before executing generate_video, waiting for an administrator to click approve.

The server processes avatar_id values and configuration payloads in a zero-trust environment. Vinkius requires only one endpoint token, and the execution environment vanishes entirely after the workflow finishes.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript