# Build avatar apps with the Realtime Avatar MCP server

> Connect a coding agent to Realtime Avatar: configure the MCP server, inspect available avatars, and build a working app with the TypeScript SDK.

- Canonical: https://realtimeavatar.ai/docs/mcp
- Updated: 2026-09-10

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

For a concrete first task, ask your coding agent to inspect available avatars and credits, then adapt the [Next.js starter](https://realtimeavatar.ai/downloads/nextjs-avatar-starter.zip) using a returned avatar ID. Keep the key on the server and start a paid call only after a user action. The [integration guide](https://realtimeavatar.ai/docs/nextjs) covers the complete browser-to-server path.

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.

**Read-only (default)**

```json
{
  "mcpServers": {
    "realtime-avatar": {
      "command": "npx",
      "args": ["-y", "realtime-avatar-mcp"],
      "env": { "REALTIME_AVATAR_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

**With writes**

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

Create a key in [workspace Settings → API keys](https://realtimeavatar.ai/platform/settings#api-keys) and replace `YOUR_API_KEY` with the full key. The list stays masked; workspace owners and admins can use **Copy** to copy newly created keys again while they are active and unexpired. Lost legacy keys stored as hashes only need a replacement, and revoked or expired keys cannot be copied. See [Authentication](https://realtimeavatar.ai/docs/authentication) for details. Creating a key is free; calls use workspace credits. There is no separate free sandbox mode.

## 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. Video-source creation is restricted; a tool being listed does not grant access to that lane.
- `upload_asset` and `create_remote_asset` — get the source material in.
- `start_call` — mint a live session and return the grant.
- `set_loop` and `set_clip_library` — 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](https://realtimeavatar.ai/docs/authentication). Never commit any API key in an agent config, regardless of its prefix.

## 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:

```text
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.
```

---

Realtime Avatar — realtime AI avatar API & SDK. Docs: https://realtimeavatar.ai/docs · Agent guide: https://realtimeavatar.ai/llms.txt