Docs

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-mcp

Without --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 .env file your .gitignore excludes. 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_avatar and list_clips: your avatars, which of them are ready for a live call, and each one's clips.
  • credit_balance and list_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-mcp 0.40.0 over stdio: it lists exactly the five read tools above, adds the write tools when REALTIME_AVATAR_ALLOW_WRITES=1 is set, and exits with REALTIME_AVATAR_API_KEY is not set when it has no key.
  • Checked on 2026-11-15: the SDK version the prompt pins, realtime-avatar 0.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 add command 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.

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