visuality-mcp

The setup MCP for Visuality — an MCP server a coding agent connects to in order to add EU-hosted video calling to the user's app. It provisions a project against the control plane and scaffolds a <VideoRoom> page + a server-only token route into the repo. It doubles as our QA tool (create_project → scaffold_embed → verify_project → delete_project).

Run

VISUALITY_API_URL=https://preprod-api.vt.rocklabs.co.uk   # the control-plane management API (https://)
VISUALITY_ACCOUNT_TOKEN=vt_at_...                        # an org account token (mint at https://preprod-app.vt.rocklabs.co.uk)
npx -y visuality-mcp                                     # speaks MCP over stdio

The agent learns the ordered setup sequence from the server's instructions; every tool call is guarded (auth + scope + spend cap + rate limit) before it runs.

Tools

• Provision: create_project, delete_project, rotate_secret, create_key, revoke_key, scaffold_embed.
• Read: get_api_keys, get_usage, get_plan, get_connection, list_projects, verify_project (exercises the token-mint path server-side, so a project that would 500 on mint reads not ready — it isn't just a key-presence check).

scaffold_embed returns the files for the agent to write (a <VideoRoom> page importing visuality-embed, and a token route importing createToken from visuality-embed/server). It takes an optional room template (one_to_one | group (default) | recording) that's baked into the token route. The scaffolded route is a starting point: it's unauthenticated and fails closed in production (403 unless VISUALITY_ALLOW_UNAUTH_TOKENS is set) — gate it behind your own auth before shipping.

Key rotation

rotate_secret swaps a project's keys atomically: it revokes every existing key the moment the new pair is issued, so a deployed app still using the old publishable key starts failing at once. For zero-downtime rotation, use the overlapping-key flow instead: create_key(projectId) issues an additional active pair alongside the current one (up to 2 active keys per project) → deploy the new publishableKey → revoke_key(projectId, publishableKey) the old one once traffic has moved over. revoke_key refuses to revoke a project's last active key.

The generated token route reads VISUALITY_SECRET_KEY (required) and optionally VISUALITY_TOKEN_ENDPOINT to point at a different control-plane stage; when the secret is unset it returns 503 video_unconfigured rather than erroring.

Versioning & compatibility

visuality-mcp and visuality-embed are versioned in lockstep for now: the scaffold emits imports (visuality-embed, visuality-embed/server) that must exist in the embed release the app installs. Install the same version of both (e.g. [email protected] with [email protected]); a mismatch may scaffold imports the embed package doesn't expose. See CHANGELOG.md for what changed.