realtime-avatar-mcp: create and manage live talking AI avatars from your coding agent
The MCP server for Realtime Avatar
(realtimeavatar.ai), the real-time AI avatar API. From Claude Code, Cursor or any MCP host, your
agent can create an avatar from one image, declare its clip library and start a short test call
(write tools, opt-in), and read your avatars, credit balance and per-session bill.
AGENTS.md tells a coding agent what the API is; this lets it look
instead of guessing ids and inventing shapes.
Published on npm as realtime-avatar-mcp.
Run it with npx; it is never installed into an app.
{
"mcpServers": {
"realtime-avatar": {
"command": "npx",
"args": ["-y", "realtime-avatar-mcp"],
"env": { "REALTIME_AVATAR_API_KEY": "tic_test_…" }
}
}
}
The read tools are on by default. Add "REALTIME_AVATAR_ALLOW_WRITES": "1" to env to turn on
avatar creation, the clip library and test calls (how writes are gated).
Full page, including the write tools and what they cost:
realtimeavatar.ai/docs/mcp. You need an API
key first: a sandbox key is free and needs no card.
Working on it in this repo? npm run build, then point command at node with
args: ["/abs/path/to/realtime-avatar-sdk/libs/mcp/dist/bin.js"].
Tools
| Tool | |
|---|---|
list_avatars | Every avatar with the id you pass to startCall, and which are usable live |
get_avatar | Full detail for one |
credit_balance | Balance, and what in-flight calls have reserved |
list_sessions | The itemised bill — when each session ran, how long, what it cost |
list_clips | An avatar's clip library: every clip, its status, the revision and rest pose |
With REALTIME_AVATAR_ALLOW_WRITES=1:
| Tool | Bills? | |
|---|---|---|
set_loop | Re-direct her resting loop from a new description | no |
set_clip_library | Declare an avatar's full clip set as JSON — the platform renders it | no |
upload_asset | Upload a file from this machine's disk, get a public URL | no |
create_remote_asset | Register a file already on the internet — no local copy | no |
create_avatar_from_image | Build an avatar from ONE still — the loop is generated | no |
create_avatar_from_video | Deprecated. Closed to new callers (422). Use the image tool | no |
start_call | Mint a live session to verify an integration | yes, per second |
Spending money is opt-in, and twice gated
The five tools above are read-only, and each carries readOnlyHint so a host can gate on
the annotation rather than on a name it has to recognise. Pointed at a production key, this
server is no more dangerous than a dashboard you left open.
REALTIME_AVATAR_ALLOW_WRITES=1 enables the write tools. Only start_call costs credits,
and it refuses a tic_live_ key outright — an operator who armed writes against a test
key and later swapped in a production one should not discover it by being billed. Two
independent gates, because one is a single mistake away from being none.
Two things to understand before arming writes:
upload_assetreads local disk. It opens whatever absolute path the agent names, on the machine running the server. Relative paths are refused rather than resolved against whatever directory the host spawned it in.- The clip declaration retires by omission.
set_clip_librarytakes the COMPLETE set; anything missing from it stops being served. Its plan reports kept/queued/retired clips. Declaresource.motionPromptorsource.assetId; the platform hosts and prepares media. The avatar's stored source is the implicit rest state — never declared, so the idprimaryis reserved.
Why an MCP server at all
An agent that reads docs still guesses. ava_… ids cannot be inferred, and the failures that
cost the most time here are invisible in a type signature: a reshaped connection payload is
rejected by the browser client; a 429 on a call is the queue, not an error; the resting loop
is the avatar's source rather than a library clip, so no declaration changes it.
list_avatars marks which avatars are actually usable. The server's instructions carry the
relay rule and the per-second billing model. That is context an agent cannot derive, delivered
where it is about to act.