MCP tools

Stateless throughout: no session to establish, nothing to keep alive, nothing to reconnect. A caller that crashes mid-conversation has left nothing behind but a room, and end_call cleans that up.

Endpoint: $LIVEGRID_CONTROL_URL/mcp · Protocol 2026-07-28 · Implemented in src/mcp.ts.

Connecting#

claude mcp add --transport http livegrid "$LIVEGRID_CONTROL_URL/mcp"

Authorisation is Bearer $UDK_SECRET, the same credential as the rest of the control plane.

Why seven#

The count is deliberate. Models pick tools less accurately as the list grows, and the discipline that follows is to return catalogues as data rather than as more tools — the ten avatar vendors are something list_avatar_providers returns, not sixteen separate tools.

The tools#

start_call#

Create a room and put a voice agent into it. Returns a token the end user joins with. Does not dial a phone number.

room, user_identity, agent_name, ttl_seconds, mode (voice | avatar | phone), avatar_id, caller_country.

Full walkthrough on Starting a call.

create_call_token#

Mint a join token for an existing room without dispatching an agent. Use it to add a second human, or an observer who should hear but not speak.

room, identity, role (human | agent | observer), ttl_seconds.

end_call#

End a call and remove the room, disconnecting everyone. Irreversible and immediate — there is no drain. Use it when the conversation is genuinely over, not to reclaim an idle room.

room*.

get_call_status#

Who is currently in one named room, and whether the agent joined and the avatar worker published video.

room*.

{ "room": "support-8f3a21", "region": "sg", "live": true,
  "participants": [
    { "identity": "daniel", "kind": 0, "joined_at": 1789..., "publishing_on_behalf_of": null },
    { "identity": "agent-1", "kind": 4, "joined_at": 1789..., "publishing_on_behalf_of": "agent-1" }
  ] }

publishing_on_behalf_of is how a frontend tells an avatar worker from the agent it renders for — they are two participants and the tracks must be attached differently.

An empty participant list means the room does not exist. An unreachable switchboard raises. This used to swallow transport errors and report a dead switchboard as an empty room, which is the opposite answer.

list_avatar_providers#

The vendor catalogue with published per-minute prices and caveats.

available (boolean) — only vendors whose key is set. The full list will happily name one that 401s at call time. Providers and pricing

list_live_calls#

Every call in progress right now on one switchboard, with participant counts and start times. Use it to answer "what is happening" without knowing a room name.

caller_country — which regional switchboard to ask.

Knows nothing about finished calls. Raises rather than returning zero when the switchboard is unreachable.

describe_call_config#

The configuration surface: modes, pipeline options, avatar settings, roles, and the latency note. Reference material — it changes nothing.

Prefer asking this over trusting a table in a document, including the ones on this site.

Tools that are deliberately not advertised#

Four avatar tools — list_avatars, create_avatar_upload, get_avatar, revoke_avatar — exist in the source and are not in tools/list.

They were briefly advertised, which is the worse of the two failures: a missing tool makes a model look for another way, while an advertised one that throws Unknown tool makes it call confidently and fail. Use the Avatars API over HTTP until they are re-added alongside the storage they need.

Calling one#

curl -sX POST "$LIVEGRID_CONTROL_URL/mcp" \
  -H "Authorization: Bearer $UDK_SECRET" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"describe_call_config","arguments":{}}}'

Results carry structuredContent alongside the stringified content block that models read. Prefer the structured form and fall back to parsing the text — the two services can be deployed minutes apart, so a reader that depends on only one shape breaks during a rollout.

An MCP error result is a failure with a 200 status and isError: true. Treating it as data turns "the switchboard is down" into an empty list.