MCP server

How authentication works

An unauthenticated request to /mcp gets a 401 whose WWW-Authenticate header points at the protected-resource metadata. From there a client finds the authorization server, registers, runs the authorization-code flow with PKCE and comes back with a bearer token bound to the https://api.voixcall.com/mcp resource. Clients that implement the MCP authorization specification do all of this without configuration.

curl -si https://api.voixcall.com/mcp
# HTTP/1.1 401 Unauthorized
# WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://api.voixcall.com/.well-known/oauth-protected-resource/mcp"
# Request-Id: req_…

curl -s https://api.voixcall.com/.well-known/oauth-protected-resource/mcp
{
  "resource": "https://api.voixcall.com/mcp",
  "authorization_servers": ["https://api.voixcall.com"],
  "scopes_supported": ["rates:read", "credits:read", "calls:read", "calls:place", "contacts:read",
                       "numbers:read", "messages:read", "messages:history", "transcripts:read", "webhooks:manage"],
  "bearer_methods_supported": ["header"],
  "resource_name": "VoixCall MCP",
  "resource_documentation": "https://voixcall.com/developers/mcp"
}

On the consent page at app.voixcall.com/oauth/consent the user sees the client's name, how it registered (“registered by URL”, “self-registered” or “verified partner”), the host it redirects to, and each requested scope as a sentence. Self-registered clients asking for calls:place, messages:read, messages:history or transcripts:read need a second confirmation checkbox. After Allow, the user gets an email “New app connected”.

Tools

Every tool is prefixed voixcall_, sets title, and returns structuredContent matching its outputSchema plus a one-line spoken summary an assistant can read aloud. Business failures are returned as isError: true results with actionable text; protocol errors are reserved for unknown tools and malformed arguments. The server's instructions tell the assistant: “Tools act only on the connected personal account. Say what a tool returned; do not invent numbers, prices or call details.”

Live production

Planned not live

These follow the read endpoints in phase 2 and later phases. Names, scopes and annotations are from the specification and may still change before they ship; the changelog announces each one. There will be no top-up tool, no number purchase and no message sending.

Placing a call will always be two steps: voixcall_quote_call shows the price and the number that will ring, and voixcall_place_call accepts only that single-use quote. Your own phone rings first and you press 1 to connect, so no assistant can spend your balance without you on the line.

Per-client setup

Claude Code

claude mcp add --transport http voixcall https://api.voixcall.com/mcp
claude mcp login voixcall
claude mcp list

claude mcp login voixcall opens the consent page in your browser. Claude Code registers with its own client metadata document, so the consent page shows it as “registered by URL: claude.ai”. It currently requests every advertised scope; you can only allow or deny the set as a whole. Verified against production.

claude.ai (custom connectors)

Settings → Connectors → Add custom connector. Name it VoixCall, set the URL to https://api.voixcall.com/mcp and leave the OAuth client id and secret empty. Click Connect, approve on app.voixcall.com, then enable the connector in a chat. claude.ai connectors use the same standard MCP discovery and OAuth 2.1 flow. Unlike Claude Code, they connect from Anthropic's servers with an https callback, which we have not yet exercised end to end.

ChatGPT

ChatGPT's connector settings take the same server URL and use the same standard MCP discovery and OAuth 2.1 flow. Unlike Claude Code, ChatGPT connects from OpenAI's servers with an https callback, which we have not yet exercised end to end; treat it as untested until the changelog says otherwise.

MCP Inspector (for testing)

npx @modelcontextprotocol/inspector
# In the UI: Transport Type "Streamable HTTP", URL https://api.voixcall.com/mcp,
# then Connect. The Inspector registers itself (Dynamic Client Registration),
# opens the consent page, and lists voixcall_whoami under Tools.

Verified with Inspector 2.8.0: registration by Dynamic Client Registration, the sensitive-scope checkbox on consent, and voixcall_whoami returning structured output.

Other clients and your own code

Any client that implements MCP over Streamable HTTP with the authorization specification works. If you write your own, use the quickstart's curl flow with resource=https://api.voixcall.com/mcp to get a token, then POST JSON-RPC to /mcp with Authorization: Bearer vcat_…, Content-Type: application/json and Accept: application/json.

What the user controls

• Settings → Connected apps in the web app lists every connected client with its name, registration kind, redirect host, scopes, when it was first authorized and when it was last used. Disconnect revokes all of that client's tokens immediately; the next call gets invalid_token with “Reconnect VoixCall in your assistant”.
• Two sharing switches coming: “Allow connected apps to read call summaries” and, per number, “Allow connected apps to read messages on this number”. Both are off by default and are shown but not yet active; they gate the transcript and message tools when those ship.
• A password reset revokes every connected app and every API key.
• Every new connection is emailed to the account owner, and connections, disconnections and token refreshes are written to an audit log kept up to 400 days (automatic deletion job in progress; a view of it on the Connected apps page is coming).

More on what each scope exposes, and for how long, in privacy for connected apps.