@talkwith/mcp

The setup MCP for TalkWith — 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

TALKWITH_API_URL=https://preprod-api.talkwith.online   # the control-plane management API (https://)
TALKWITH_ACCOUNT_TOKEN=vt_at_...                        # an org account token (mint at https://preprod-app.talkwith.online)
npx -y @talkwith/mcp                                    # speaks MCP over stdio

The legacy VISUALITY_API_URL / VISUALITY_ACCOUNT_TOKEN names are still read as fallbacks (with a one-line deprecation warning on stderr) so existing MCP configs keep working.

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 @talkwith/embed, and a token route importing createToken from @talkwith/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 TALKWITH_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 TALKWITH_SECRET_KEY (required) and optionally TALKWITH_TOKEN_ENDPOINT to point at a different control-plane stage; when the secret is unset it returns 503 video_unconfigured rather than erroring. (The legacy VISUALITY_* names are read as fallbacks.)

Versioning & compatibility

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

Upgrading from visuality-mcp

This package was previously published as visuality-mcp (≤ 0.2.1); that name is deprecated in favour of @talkwith/mcp. To upgrade, change your MCP config to run npx -y @talkwith/mcp and rename the env vars VISUALITY_API_URL / VISUALITY_ACCOUNT_TOKEN to TALKWITH_API_URL / TALKWITH_ACCOUNT_TOKEN (the old names still work for now, with a deprecation warning).