MCP Server
Verified against backend/internal/mcpserver/ and backend/internal/oauth/ (2026-10-11): the OAuth flow is covered end to end by backend/internal/oauth/oauth_test.go, and every tool's annotations by backend/internal/mcpserver/annotations_test.go. The Studio tools (2026-10-22) by backend/internal/mcpserver/studio_tools_test.go and backend/internal/studio/api_films_test.go.
VoiceMatrix runs a live Model Context Protocol server so Claude, Claude Code, Cursor or any other MCP client can work with your account directly: review what your callers are saying, launch an agent in a new market, compare agents, plan usage, and make finished videos with VoiceMatrix Studio — without you writing REST calls by hand.
https://api.voicematrix.ai/mcpIt runs in-process in the Go API, not as a separate service, on the same tenancy path and the same scope checks as the REST surface.
Connect
Claude (claude.ai, Desktop, mobile)
Settings → Connectors → Add custom connector → paste https://api.voicematrix.ai/mcp → Connect. You sign in to VoiceMatrix, choose which permissions to grant, and you are done. No key to copy.
Claude Code
claude mcp add --transport http voicematrix https://api.voicematrix.ai/mcpThen run /mcp in a session and choose Authenticate. Claude Code opens the VoiceMatrix consent page in your browser and receives the connection on a local port.
Cursor, VS Code and other clients
Add the URL as a remote (HTTP) MCP server; clients that support MCP authorization discover the sign-in automatically.
With an API key instead
Every client that can send a header can still use a key minted in Settings → API keys:
claude mcp add voicematrix \
--transport http https://api.voicematrix.ai/mcp \
--header "X-API-Key: vm_live_your_key_here"How sign-in works
The server is an OAuth 2.1 authorization server, built to what Claude's connector client requires:
| Step | What happens |
|---|---|
| Discovery | A request with no credential gets 401 and WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"; that document names the authorization server https://voicematrix.ai |
| Client identity | Client ID Metadata Documents (Claude and Claude Code) or Dynamic Client Registration (others). Public clients only |
| Consent | You sign in on voicematrix.ai and pick permissions. The page shows where you will be returned |
| Tokens | PKCE (S256) is required. Access tokens last 1 hour; refresh tokens 30 days, single-use and rotated. Presenting a used refresh token revokes the whole connection |
Approving creates a connection that appears in Settings → API keys under the application's name. Revoking it there ends the connection immediately. Who may approve: account owners, admins and managers, on a plan that includes API access — the same rule as minting a key. On the trial plan, a connection (or a key) can hold the Studio permissions only, so you can make a free film before choosing a plan.
Permissions a connection can hold: agents:read, agents:write, calls:read, leads:read, leads:write, webhooks:manage, studio:read, studio:write. A connection can never place calls, bind phone numbers, delete agents, or run paid tests — those scopes are not grantable over OAuth at all. studio:write is grantable because a film is paid from your organization's Studio allowance, never your card (see Studio films).
The tools
Every tool declares a title and whether it is read-only or changes data, so Claude can run reads without asking and always confirms a write.
Read
whoami list_agents get_agent list_calls get_call list_leads get_lead
list_webhooks webhook_deliveries list_webhook_events
review_conversations compare_agents estimate_agent_usage
studio_options get_film list_filmsWrite
create_agent duplicate_agent update_agent publish_agent unpublish_agent
create_lead update_lead create_webhook
create_film| Tool | What it is for |
|---|---|
review_conversations | Summaries, sentiment, urgency and tags of recent calls with counts — for spotting recurring questions and complaints. Never returns transcripts or caller phone numbers |
duplicate_agent | Copy an agent for a new market, changing its name, language, voice, greeting or prompt. The copy is a draft until you publish it |
compare_agents | Two to five agents side by side: which settings differ, which match, and simple inconsistencies |
estimate_agent_usage | Calls and minutes per day, projected minutes for the next 30 days against your plan's included minutes, average model tokens per call, and the relative model-cost change if you switch models |
create_film | A finished short video (MP4) from a brief, end to end: Studio's orchestrator writes the script, casts the main character, shoots each scene, narrates in Hebrew or English, adds music and edits it |
studio_options | What Studio can make now: lengths, formats, narrators, video engines, what a film costs in tokens, and how much of your Studio allowance is left |
Each tool checks the same scope its REST equivalent requires; a connection or key missing it gets a clear tool error, not a silently smaller result. Creating or duplicating an agent runs the same account and plan checks as the dashboard. Results are minimized: transcripts are opt-in per call (get_call) and never part of a list.
Studio films
create_film runs the same orchestrator as Studio in the dashboard, so a film made from Claude is a film in your Studio library. Its REST twin is POST /api/v1/ext/studio/films.
| Length and format | 24, 36 or 48 seconds; 16:9 or 9:16 (vertical, for Reels, TikTok and Stories). studio_options prices only the lengths that fit what is left of your allowance |
| Language | Hebrew or English, read from the brief unless you say |
| Video engines | Gemini Omni (recommended) and Veo; open models such as MiniMax H3 where they are enabled for your organization. studio_options lists what is available to you |
| Time | Usually 5-10 minutes; a 48-second film sometimes much longer. create_film answers at once with an id and a watch_url; get_film reports progress and, when done, the video link |
| Watch page | watch_url is a page for the person who asked for the film, no login needed: it shows the script, the main character and each scene as they arrive, then plays the film with download and share. It works for 30 days; anyone holding the link can watch that one film |
| If it fails | get_film says why in plain words, with an error_code: content_refused, legal_blocked, engine_retired, cancelled or production_failed. What the film did not use goes back to the allowance |
| Links | Signed, valid for about 24 hours. Call get_film again for a fresh one |
| Cost | Paid from your organization's Studio allowance: a free monthly allowance (about two 24-second films) unless your organization has its own Studio budget. The whole film is reserved before any work starts, and you are not charged for it |
| Who | Only the account owner's key or connection can make films |
Asking for the film is the go-ahead — there is no separate confirmation step. The same brief on the same day returns the same film, so a retried call never makes (or uses the allowance for) a second one; send a new idempotency_key for another take of an identical brief.
What you can ask it
"Which topics come up most in my calls this week, and what are callers unhappy about?" "Duplicate my English receptionist for the Israeli market, in Hebrew with a female voice." "Compare my three agents and tell me what's inconsistent." "If I switch this agent to a cheaper model, how does its usage change next month?" "Make a 24-second vertical video in Hebrew for my cafe's morning special."
Next
- Authentication — the scopes each tool checks
- SDKs & OpenAPI