MCP overview

OpenPhonex speaks MCP (Model Context Protocol). Any MCP-capable client points at one endpoint, passes a scoped key, and the OpenPhonex tools appear in tools/list — ready to call. This is the universal path; the OpenClaw connector and the REST API are convenience wrappers around the same tools.

The endpoint

POST https://api.openphonex.com/mcp
Authorization: Bearer tai_your_scoped_key

Standard JSON-RPC: tools/list to discover, tools/call to invoke.

Connect from the workspace

You do not have to assemble the configuration by hand. The API keys page in the workspace carries a Connect an AI assistant card: create a key with only the scopes the assistant should have, then copy the ready-made server entry it shows and paste it into the assistant's MCP settings, replacing the placeholder with that key.

{
  "url": "https://openphonex.com/control-plane/mcp",
  "headers": {
    "Authorization": "Bearer tai_YOUR_KEY"
  }
}

That URL is the same hosted MCP server as https://api.openphonex.com/mcp, reached through the dashboard host; either address works and both are held to the same scopes. The assistant can do exactly what the key allows and nothing more, and revoking the key disconnects it.

tools/list carries scopes

Each tool in tools/list advertises its required_scopes. tools/list returns all tools regardless of your key, but a tools/call for a tool whose scopes are not on your key fails closed with missing MCP scopes: X. This lets an agent see the full surface while still being held to least privilege.

Prefix scopes

Some scopes are grouped by prefix — for example sms:* covers both sms:read and sms:send. Grant the specific leaf scope for least privilege, or the prefix when an agent legitimately needs the whole group.

Capabilities that a deployment can switch off

A few tools belong to capabilities an operator enables per deployment — the Simulations Lab is one. tools/list publishes them regardless, because it is a catalog of what OpenPhonex can do rather than an inventory of what your instance has switched on. Calling one where the capability is off returns the same not-found the equivalent REST route returns.

Configure an agent from MCP

An organization-scoped key with agents:read and agents:write can complete the normal customer configuration loop without switching to REST:

1. Call get_agent_catalog to discover selectable STT, LLM, and TTS options plus conversation engines. It accepts either agents:read or coverage:read; use metered_only: true when you need only component-metered choices. Pass voice_frontend: "gpt_live" on create_agent or set_agent_voice_stack to select GPT-Live 1; omit it to keep Standard.
2. Call create_agent, then use list_agents for a bounded newest-first page or get_agent for one current safe agent projection.
3. Use update_agent for the ordinary mutable fields and set_agent_voice_stack to publish a selected stack. Read the published configuration back with get_agent_voice_stack.
4. Use preview_voice only as an explicit Listen action. It can contact a provider or validate a BYOK credential, is rate-limited per workspace, and may write safe preview-rate or voice-availability state. It is not a read-only or free preview.

list_agents is deliberately a bounded MCP collection: it returns the same safe agent items as REST inside { agents, pagination }, with up to 50 agents per page (the default and maximum). Follow pagination.next_cursor only while pagination.has_more is true. The legacy REST collection remains a separate compatibility response.

list_audio_environments is the same catalogue as GET /v1/audio-environments, with the same account:read scope. It is a read-only, provider-independent discovery call: it returns Off plus the currently packaged versioned presets and never changes an agent or starts a preview. Use its exact preset ID and asset version when configuring output ambience or a Simulation Lab caller condition; do not maintain a client-side copy of the catalogue.

The key's organization is authoritative. You may omit the redundant organization_id input from create, list, and preview calls; if supplied, it must match the key's workspace. Agent IDs, optional project filters, saved voice pins, preview rate limits, credential ownership, and provider/BYOK validation stay in the same services as the REST workflow.

For local stdio MCP, set both OPENPHONEX_MCP_SCOPES and OPENPHONEX_MCP_ORGANIZATION_ID before calling any organization-bound agent configuration tool. An absent organization fails closed; tools/list remains schema discovery only.