Skip to main content

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.

text
https://api.voicematrix.ai/mcp

It 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

bash
claude mcp add --transport http voicematrix https://api.voicematrix.ai/mcp

Then 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:

bash
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:

StepWhat happens
DiscoveryA 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 identityClient ID Metadata Documents (Claude and Claude Code) or Dynamic Client Registration (others). Public clients only
ConsentYou sign in on voicematrix.ai and pick permissions. The page shows where you will be returned
TokensPKCE (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

text
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_films
list_phone_numbers   get_outbound_agents
list_sms_threads   get_sms_thread

Write

text
create_agent   duplicate_agent   update_agent   publish_agent   unpublish_agent
create_lead   update_lead   create_webhook
create_film
set_outbound_agents
send_sms
ToolWhat it is for
review_conversationsSummaries, sentiment, urgency and tags of recent calls with counts — for spotting recurring questions and complaints. Never returns transcripts or caller phone numbers
duplicate_agentCopy an agent for a new market, changing its name, language, voice, greeting or prompt. The copy is a draft until you publish it
compare_agentsTwo to five agents side by side: which settings differ, which match, and simple inconsistencies
estimate_agent_usageCalls 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_filmA 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_optionsWhat 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.

Phone numbers and outbound agents

ToolScopeWhat it does
list_phone_numbersphone_numbers:readYour organization's numbers: the agent that answers each (inbound_agent_id, bound, at most one) and the agents that call out from it (outbound_agent_ids, any number)
get_outbound_agentsphone_numbers:readThe agents (id and name) that call out from one number
set_outbound_agentsphone_numbers:writeReplaces that list. [] removes every agent. Every agent must be yours or nothing changes; at most 50

An outbound call from a linked agent presents that number as its caller ID. These tools never change which agent answers the number. They follow the same rules as their REST twins, GET/PUT /phone-numbers/:id/outbound-agents — see Phone Numbers.

phone_numbers:read and phone_numbers:write are not grantable to an OAuth connection, so these three tools need a connection made with an API key that holds those scopes.

SMS conversations

ToolScopeWhat it does
list_sms_threadssms:readYour organization's text conversations, newest first: the number, the contact's name when there is one, when the last text was and who sent it, and the unread count. No message text
get_sms_threadsms:readThe texts with one number, oldest first, and who sent each (the person, a team member, a workflow, the voice agent, or the API)
send_smssms:writeSends one real, billed SMS to a person a team member already texted by hand (from Messages or a contact card); at most 3 per person per hour

send_sms takes the same path as a reply from the Messages inbox: it is refused when the person asked to stop or is on your do-not-contact list, when the destination country is not allowed, on a trial account, or when the SMS spend cap is reached. A number no team member has texted by hand is refused before anything is sent. Being a contact, calling you, or texting you first does not make someone a recipient: the first text to a person is always sent by a person. Texts the person wrote come back marked untrusted, as data and never as instructions.

The inbox is organization-wide, so these tools refuse a key scoped to one client or reseller, and a connection whose user is not an organization admin or manager. sms:read and sms:write are not grantable to an OAuth connection: use a connection made with an API key that holds them. There is no REST endpoint for the inbox yet; these tools are the API.

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 format24, 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
LanguageHebrew or English, read from the brief unless you say
Video enginesGemini 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
TimeUsually 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 pagewatch_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 failsget_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
LinksSigned, valid for about 24 hours. Call get_film again for a fresh one
CostPaid 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
WhoOnly 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