Skip to main content

MCP Server

Verified against backend/internal/mcpserver/tools.go, server.go, and PROJECT-DOCS/DEVELOPER_PLATFORM.md (production acceptance run, 2026-08-05). Re-verified by running the server on 2026-08-25: initialize answers, tools/list returns exactly the nine tools below, list_agents returns real rows, an unknown tool is refused, and a key missing a tool's scope gets a clean JSON-RPC error.

VoiceMatrix runs a live Model Context Protocol server so an AI coding agent (Claude Code, Cursor, Claude Desktop) can answer questions about your account directly, without you writing REST calls by hand.

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

This is in-process in the Go API, not a separate service — it reuses the exact same APIKeyAuth and RequireScope middleware as the REST surface, on the same tenancy path. (A second, standalone MCP container exists at mcp.voicematrix.ai on a different host; it has no DNS record pointing at it today and is not the one to use — see Changelog.)

Connect

Claude Code:

bash
claude mcp add voicematrix \
  --transport http https://api.voicematrix.ai/mcp \
  --header "X-API-Key: vm_live_your_key_here"

Cursor / Claude Desktop — add to your MCP config:

json
{
  "mcpServers": {
    "voicematrix": {
      "url": "https://api.voicematrix.ai/mcp",
      "headers": { "X-API-Key": "vm_live_your_key_here" }
    }
  }
}

Without a key, the server answers 401 MISSING_API_KEY (verified). With one, initialize returns the negotiated session. protocolVersion is negotiated, not fixed: the server echoes your version when it supports it (2025-03-26 and 2025-11-25 both echo back) and falls back to 2025-11-25 for anything it doesn't recognize — so the value you see here depends on what your client asked for:

json
{"jsonrpc":"2.0","result":{"capabilities":{"logging":{},"tools":{"listChanged":true}},"protocolVersion":"2025-11-25","serverInfo":{"name":"voicematrix","version":"0.1.0"}}}

The nine tools

All read-only, by design:

text
whoami   list_agents   get_agent   list_calls   get_call
list_leads   get_lead   list_webhooks   webhook_deliveries

Each tool declares the same scope its REST equivalent requires — a key missing that scope gets a clean JSON-RPC error from the tool, not a silently smaller result. Read tools also minimize what they return: call transcripts are opt-in per call and never included in a list result, because an MCP tool result is forwarded straight into your model provider's own context window, and transcripts are the same sensitive call data covered under Security & Data Residency.

What's deliberately not here yet: create_agent, create_call, bind_phone_number — anything that spends money or changes what a real phone line does. Making every REST route automatically LLM-callable would have forced that decision by accident; instead, write tools are planned as a separate, explicit per-key opt-in.

What you can ask it

"How many calls did my agent take this week?" "Show me yesterday's leads, and why the webhook for them failed." "Which of my webhooks are currently paused?"

Two current limits

  • No remote OAuth. Auth is a long-lived pasted key — correct for a locally-configured client like Claude Code or Cursor, not yet suitable for a hosted third-party connector. An OAuth 2.1/PKCE seam exists in the auth abstraction for when that's needed.
  • Read-only. See above.

Next

All pages