Docs

MCP server

Give your coding agent the account itself: which avatars exist, what a call costs, and — behind a flag — the ability to create a character and start a call. One npx line, no build step.

An agent cannot guess an avatar id. That is the whole reason this exists. Hand a coding agent the docs and it will write plausible code against a character that does not exist, a plan you are not on, and a balance it cannot see — and you will find out at the first 404. The MCP server closes that gap by letting the agent read your actual account before it writes a line.

Install

Published on npm as realtime-avatar-mcp. There is nothing to build and nothing to host: it runs over stdio, straight from npx. Add this to your agent's MCP config — .mcp.json for Claude Code, .cursor/mcp.json for Cursor, claude_desktop_config.json for Claude Desktop.

{
  "mcpServers": {
    "realtime-avatar": {
      "command": "npx",
      "args": ["-y", "realtime-avatar-mcp"],
      "env": { "REALTIME_AVATAR_API_KEY": "tic_test_..." }
    }
  }
}
{
  "mcpServers": {
    "realtime-avatar": {
      "command": "npx",
      "args": ["-y", "realtime-avatar-mcp"],
      "env": {
        "REALTIME_AVATAR_API_KEY": "tic_test_...",
        "REALTIME_AVATAR_ALLOW_WRITES": "1"
      }
    }
  }
}

Use a sandbox key (tic_test_) while you are building. Mint one at Settings → API keys; it is free, needs no card, and it is a real key against the real platform.

What the agent gets

Read tools are on by default. Write tools are not. An agent that can read your account cannot cost you anything; an agent that can start a call and create a character can, so that half is behind REALTIME_AVATAR_ALLOW_WRITES=1 and you opt in deliberately.

Always available

  • list_avatars — every avatar on the account, with the id you pass to a session mint. This is the one an agent should call before writing any code.
  • get_avatar — full detail for one avatar, including its clip set and voice.
  • credit_balance — the balance, and how much is reserved by calls in flight.
  • list_sessions — the itemised bill: when each session ran, how long it was billable for, and what it cost.
  • list_clips — the declared clip library with each clip's render status.

Behind REALTIME_AVATAR_ALLOW_WRITES=1

  • create_avatar_from_image and create_avatar_from_video — a character from one photo, or from footage.
  • upload_asset and create_remote_asset — get the source material in.
  • start_call — mint a live session and return the grant.
  • set_loop, set_clip_library, sync_clips — redirect the resting loop and re-declare the clip set.

Creating a character spends credits and takes minutes. Both create tools are asynchronous: the avatar comes back preprocessing and is not callable until it reaches ready. An agent that mints a session against a preprocessing avatar gets a 409 with code: "avatar_not_ready" — poll get_avatar instead of retrying the call.

What it is not

The MCP server is a build-time tool. It is how your agent learns the account while it writes your integration; it is not how your application talks to the platform at runtime. Your app should keep minting sessions from your own server, because that endpoint is where you decide who may call and what the character knows — see Authentication. Never ship a tic_live_ key inside an agent config you also commit.

Try it in one line

With the server configured, this prompt is enough to get a working page, because the agent can now look up a real avatar instead of inventing one:

Use the realtime-avatar MCP server. List my avatars, pick the first ready one,
then build a one-button page that opens a live video call with her: she speaks
first, two-way voice, her portrait while she connects, and a hang-up button.
Mint the session from a server route, never from the browser.
Follow https://realtimeavatar.ai/llms.txt for the SDK shapes.