How to Use the Tavus Video Replicas MCP in Mastra AI

Q: How do I check video status with Tavus Video Replicas in mastra-ai?

You call generatereplicavideo first to get a job ID. Then, your agent uses getvideodetails(jobId) repeatedly until the returned generationstatus confirms completion. This is how you handle async video processing reliably.

Q: Can mastra-ai list all available replica voices?

Yes, simply use the listreplicas tool. It pulls a comprehensive list of every active profile attached to your MCP Server instance. This is your starting point for any new generation job.

Q: What data types does this MCP Server touch regarding Tavus Video Replicas and mastra-ai?

The server handles video job status, including the generationstatus field. This is critical because it dictates whether your agent can proceed with using a specific video asset in its workflow.

Q: What happens if I delete a replica using mastra-ai?

Calling deletereplica permanently removes that profile. You can't recover the voice model or any videos associated with it through this MCP Server, so double-check your assets first.

Build robust video pipelines using Tavus Video Replicas with your agent framework.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect Tavus Video Replicas MCP to Mastra AI

Create your Vinkius account to connect Tavus Video Replicas to Mastra AI — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup Tavus Video Replicas with Mastra AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity Vinkius runs on Gemini

Gemini

Grok

Track generation status via the MCP Server

When you call `generate_replica_video`, it kicks off a background job. You don't wait for it to finish; you track progress by checking the state using `get_video_details`. This mechanism lets your agent handle retries or timeouts gracefully, ensuring your production workflow never stalls. It's key to understand that calling this endpoint doesn't return the video file. Instead, it returns a job ID and a status code. You poll that ID until the `generation_status` is 'complete.' This state management capability keeps your complex workflows solid.

Manage all available replicas

Need to know what voices you've set up? Use `list_replicas` to get a quick roster of everything. For deep dives, call `get_replica_details`. This gives your agent the full metadata—like the source audio pitch and timbre data—it needs before attempting any generation. If a replica is obsolete or incorrect, you can wipe it clean immediately with `delete_replica`. It's a straight-up command that permanently removes the profile from the system.

Audit generated video assets

To give your agent visibility into past campaigns, start by listing everything with `list_generated_videos`. This gives you an index of all jobs. Then, if you find a specific video ID, use `get_video_details` to pull down the full data packet—who generated it and when. If you need to clean up old content or remove sensitive material, you can delete both the final asset using `delete_video` and the underlying replica profile. Both commands are irreversible.

Setup guide

Set up Tavus Video Replicas 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 Tavus Video Replicas 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: "tavus-video-replicas-mcp-client",
  servers: {
    "tavus-video-replicas-mcp": {
      url: new URL(
        "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
      ),
    },
  },
});

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

const result = await agent.generate(
  "List recent Tavus Video Replicas 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 Tavus. 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 Tavus Video Replicas 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 Tavus Video Replicas MCP in Mastra AI

You call `generate_replica_video` first to get a job ID. Then, your agent uses `get_video_details(jobId)` repeatedly until the returned `generation_status` confirms completion. This is how you handle async video processing reliably.

Yes, simply use the `list_replicas` tool. It pulls a comprehensive list of every active profile attached to your MCP Server instance. This is your starting point for any new generation job.

The server handles video job status, including the `generation_status` field. This is critical because it dictates whether your agent can proceed with using a specific video asset in its workflow.

The server manages the interaction with external APIs. While we don't control external API throughput, the `mastra-ai` framework allows you to build in exponential backoff logic when calling status endpoints.

Calling `delete_replica` permanently removes that profile. You can't recover the voice model or any videos associated with it through this MCP Server, so double-check your assets first.

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