Realtime Avatar

realtime-avatar-mcp

Published on npm as realtime-avatar-mcp — run it with npx, never installed into an app.

An MCP server for Realtime Avatar. AGENTS.md tells a coding agent what the API is; this lets it *look* — at your avatars, your balance, your bill — instead of guessing ids and inventing shapes.

{

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

Full page, including the write tools and what they cost: https://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

With REALTIME_AVATAR_ALLOW_WRITES=1:

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_asset` reads 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_library takes the COMPLETE set; anything missing from it stops being served. Its plan reports kept/queued/retired clips. Declare source.motionPrompt or source.assetId; the platform hosts and prepares media. The avatar's stored source is the implicit rest state — never declared, so the id primary is 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.