Add a Live AI Avatar with Cursor or Claude Code (MCP Server Setup)
Set up the Realtime Avatar MCP server in Cursor or Claude Code so your coding agent reads your real avatars and balance, then give it a prompt that adds a live AI avatar call with the API key kept on your server.
Cursor and Claude Code write code in your own project, so they need two things an app builder supplies for itself: the facts of your account, and the rules for where the key goes. The Realtime Avatar MCP server supplies the first, so the agent lists your avatars and reads your balance instead of guessing an id. The prompt on this page supplies the second.
The server is published on npm as realtime-avatar-mcp and runs on your machine over stdio, started by npx -y realtime-avatar-mcp. There is nothing to build and nothing to host.
1. Get an API key
Try it free. Create a free account, then create a key in Settings, API keys. The free Sandbox plan includes 8 realtime minutes, once per account, and the prompts here cap every call at 120 seconds.
2. Add the MCP server
Both tools run the same server entry: npx -y realtime-avatar-mcp, with your key in the REALTIME_AVATAR_API_KEY environment variable. Only the way each one is configured differs.
Claude Code
Run this in your project, with your key in place of YOUR_API_KEY:
claude mcp add realtime-avatar -e REALTIME_AVATAR_API_KEY=YOUR_API_KEY -- npx -y realtime-avatar-mcpWithout --scope, Claude Code adds the server for this project only and stores it in ~/.claude.json in your home folder, so the key stays out of your repo. Check it with claude mcp list, which shows each server's health, or with /mcp inside Claude Code.
To share the setup with your team, commit a .mcp.json at the project root that reads the key from each developer's environment instead. Claude Code expands ${REALTIME_AVATAR_API_KEY} in that file:
{
"mcpServers": {
"realtime-avatar": {
"command": "npx",
"args": [
"-y",
"realtime-avatar-mcp"
],
"env": {
"REALTIME_AVATAR_API_KEY": "${REALTIME_AVATAR_API_KEY}"
}
}
}
}Cursor
Add the server to ~/.cursor/mcp.json, Cursor's global config. It lives in your home folder rather than the repo, so the key is never committed:
{
"mcpServers": {
"realtime-avatar": {
"command": "npx",
"args": [
"-y",
"realtime-avatar-mcp"
],
"env": {
"REALTIME_AVATAR_API_KEY": "YOUR_API_KEY"
}
}
}
}Or add it to Cursor in one click. Cursor asks before it installs the server. The link carries no key: it sets the key to ${env:REALTIME_AVATAR_API_KEY}, which Cursor fills from its environment, so start Cursor from a shell where REALTIME_AVATAR_API_KEY is set. A project .cursor/mcp.json written the same way can be committed, because it holds the variable name rather than the key.
Turn the server on or off from Customize in Cursor's sidebar, and read its output in the Output panel under MCP Logs. If the log says REALTIME_AVATAR_API_KEY is not set, the server started without a key.
3. Give the agent the prompt
With the server connected, paste this into Cursor's agent or into Claude Code. It carries the same rules as the builder prompts, has the agent check the key through the MCP server first, and lets it pick the SDK adapter for your framework. Every call it sets up is capped at 120 seconds by the server.
Add a live AI avatar video call to this app with the Realtime Avatar SDK.
Packages: realtime-avatar (pin exactly 0.26.0), livekit-client, @livekit/components-react, zod.
Rules, do not break them:
1. The API key is a server secret named REALTIME_AVATAR_API_KEY. Never put it in browser code and never in a VITE_ or NEXT_PUBLIC_ variable. Ask me for it as a secret.
2. The browser never calls Realtime Avatar directly. It calls ONE server route of ours that holds the key. The SDK ships that route; it answers POST <base>/connect and POST <base>/end and relays the platform's answer unchanged. Do not wrap or reshape what it returns.
3. The server decides the call: instructions, maxSeconds and which avatar ids are allowed. Ignore anything the browser sends for those.
4. Use the public example avatar "seed-rin-ashfall" and allow only that id for now.
Reference: https://realtimeavatar.ai/llms.txt and https://realtimeavatar.ai/docs/quickstart.md
First, use the realtime-avatar MCP server to check the key: call credit_balance and list_avatars and tell me what they return. Use seed-rin-ashfall for this first call either way.
Server: ONE route that answers POST /api/realtime-avatar/connect and POST /api/realtime-avatar/end. Use the SDK adapter for this project's framework:
- Next.js App Router: app/api/realtime-avatar/[...path]/route.ts, with export const { GET, POST } = createRealtimeAvatarRoute(options). Guide: https://realtimeavatar.ai/docs/nextjs.md
import { createRealtimeAvatarRoute } from "realtime-avatar/nextjs";
- TanStack Start: src/routes/api/realtime-avatar/$.ts, with server handlers from realtimeAvatarServerRoute(options). Guide: https://realtimeavatar.ai/docs/tanstack-start.md
import { realtimeAvatarServerRoute } from "realtime-avatar/tanstack-start";
- Hono, Cloudflare Workers, Bun or Deno: app.all("/api/realtime-avatar/*", realtimeAvatarHono(options)). Guide: https://realtimeavatar.ai/docs/hono.md
import { realtimeAvatarHono } from "realtime-avatar/hono";
- Express: app.use("/api/realtime-avatar", express.json(), realtimeAvatarExpress(options)). Guide: https://realtimeavatar.ai/docs/express.md
import { realtimeAvatarExpress } from "realtime-avatar/express";
options: apiKey as a function that reads REALTIME_AVATAR_API_KEY from the server environment, plus this policy:
authorize: ({ operation }) =>
operation === "connect" || operation === "end" ? undefined : new Response("Not found", { status: 404 }),
session: ({ avatarId }) =>
avatarId === "seed-rin-ashfall"
? { instructions: "You are Rin, a warm, curious guide. Short spoken sentences, one question at a time.", maxSeconds: 120 }
: new Response("Avatar not allowed", { status: 403 }),
Client: a page with a "Call Rin" button. Clicking it mounts the call component below (render it only in the browser, after mount, never during server rendering). When the call ends, show the button again.
import { AvatarCall, createProxyClient } from "realtime-avatar/react";
const client = createProxyClient({ proxyUrl: "/api/realtime-avatar" });
<AvatarCall
client={client}
avatarId="seed-rin-ashfall"
poster="https://realtimeavatar.ai/api/assets/public/characters/rin-ashfall/portrait.png"
idleVideoUrl="https://realtimeavatar.ai/api/assets/public/characters/rin-ashfall/idle-10s.mp4"
style={{ width: "100%", maxWidth: 420, aspectRatio: "3 / 4" }}
onEnded={() => setInCall(false)}
>
{(call) => (
<div style={{ position: "absolute", bottom: 16, left: 0, right: 0, textAlign: "center" }}>
{call.status === "waiting" ? <p>In line: {call.queuePosition}</p> : null}
<button onClick={call.end}>End call</button>
</div>
)}
</AvatarCall>
The microphone only works on https or http://localhost.To start from a working app instead, clone the realtime-avatar-starter-vite repo (Vite, React and a Hono server on one port) or download the Next.js starter, and ask the agent to adapt it.
Where the API key goes
In two places, neither of them the browser:
- The MCP server's config, above. The MCP server is a build-time tool: it is how the agent reads your account while it writes the integration, not how your app talks to the platform.
- Your app's server environment, as
REALTIME_AVATAR_API_KEY, for example in a.envfile your.gitignoreexcludes. Your app's own route holds the key at runtime and hands the browser a session grant for one call.
What the agent can do with the server
By default the server is read-only, so an agent connected to it cannot spend credits:
list_avatars,get_avatarandlist_clips: your avatars, which of them are ready for a live call, and each one's clips.credit_balanceandlist_sessions: the balance, what calls in flight have reserved, and the itemised bill.
Set REALTIME_AVATAR_ALLOW_WRITES=1 in the server's env to add start_call, create_avatar_from_image, upload_asset, create_remote_asset, set_loop and set_clip_library. start_call starts a real call and bills it by the second. The MCP page has the details.
What works and what has not been tested
- Checked on 2026-11-15 by running the published
realtime-avatar-mcp0.40.0 over stdio: it lists exactly the five read tools above, adds the write tools whenREALTIME_AVATAR_ALLOW_WRITES=1is set, and exits withREALTIME_AVATAR_API_KEY is not setwhen it has no key. - Checked on 2026-11-15: the SDK version the prompt pins,
realtime-avatar0.26.0, exports every adapter and component the prompt names. The command and config formats follow Claude Code's and Cursor's own MCP documentation as of that date. - Not covered by those checks: the one-click Cursor link and the
claude mcp addcommand run end to end against this server, and the code an agent writes from the prompt, which can differ from run to run. Before your first call, check that the key is read only on the server and that the route returns the SDK's answer unchanged.
Before you share the link
As generated, anyone who can open the app can start a call, and every call spends your balance. Before going public, ask your agent to require a signed-in user in the route's authorize hook (return a 401 when there is none), and set maxSeconds to what you will pay for per call. See Authentication for what authorize gates, and pricing for what a minute costs.
Other builders
Compare and cost guides
- Realtime Avatar pricing
- Avatar API cost calculator
- Realtime Avatar vs Tavus, HeyGen LiveAvatar, Anam and Simli
- Realtime AI avatar APIs compared
- Realtime avatar API pricing, worked out
- HeyGen and LiveAvatar API pricing explained
- Choosing a HeyGen alternative for realtime avatars
- Tavus pricing per minute
- A Tavus alternative for live AI characters
- Meta Muse Realtime Avatar vs Realtime Avatar
- A realtime AI avatar in React Native or Expo
- Live avatars in 2026: a field guide to the research