Quickstart

Connect an MCP client, inspect your workspace, and test a configured agent in the browser.

Connect an MCP client and inspect your workspace without placing a paid phone call. The example uses the OpenClaw connector; other MCP clients use the same scoped tools. For the fastest audio test, configure an agent in the workspace and test it in the browser using welcome credit or purchased funds. PAYG has no monthly platform subscription; see Billing.

Prerequisites

An OpenPhonex organization and a credential that can mint keys — a dashboard session token (opsess_…) or a bootstrap key that holds api_keys:write.
Node 18+ (for the .mjs bridge) or Python 3.8+ (for the .py bridge).
An agent host that speaks MCP — an OpenClaw checkout with config/mcporter.json, or any other MCP client.

Install the connector

Copy the connector into your agent checkout and register the hosted MCP endpoint.

cp -R connectors/openclaw skills/openphonex
npx mcporter add openphonex --url https://api.openphonex.com/mcp

Full detail — the stdio bridge, the .mjs vs .py choice, and the remote-MCP shortcut — is in Install the connector.

Mint a scoped key

Mint one org key with the agent scope set. Control-plane scopes (api_keys:write, wallet:write, operator:*, provider_mutations:*) are intentionally omitted, and requested scopes are clamped server-side to what your admin credential already holds — the key cannot self-escalate.

curl -s -X POST "$OPENPHONEX_BASE_URL/v1/api-keys" \
  -H "Authorization: Bearer $OPENPHONEX_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organization_id":"org_...",
       "name":"OpenClaw agent",
       "scopes":["account:read","coverage:read","agents:write",
                 "numbers:read","numbers:write",
                 "calls:read","calls:write","recordings:read",
                 "sms:read","sms:send","policy:evaluate"]}'

The response returns token (a tai_… key) once — store it immediately, it is never retrievable again. For a cautious tier, drop sms:send, calls:write, and numbers:write to prevent those live actions. See Authentication & keys for the full scope model.

Wire the key into the MCP server

Set the three env vars on the openphonex MCP server and restart your agent so tools/list picks up the tools.

{
  "mcpServers": {
    "openphonex": {
      "command": "node",
      "args": ["skills/openphonex/bin/openphonex-mcp-bridge.mjs"],
      "env": {
        "OPENPHONEX_BASE_URL": "https://api.openphonex.com",
        "OPENPHONEX_API_KEY": "tai_your_scoped_key",
        "OPENPHONEX_ORGANIZATION_ID": "org_your_org"
      }
    }
  }
}

Your agent calls the tools

Ask the agent in plain language — it selects the right tool from tools/list.

you › show my account and search GB number coverage; do not place a call

→ account_overview(...)            # account:read
→ get_coverage(country="GB")       # coverage:read
✓ workspace balance and coverage summarized back to you

Then use the workspace's agent browser test to hear the configured voice. Shared-number live PIN trials are retired; create_trial_call is an offline synthetic-fixture tool, not a way to reach the agent by phone. A real outbound call requires purchased funds, a configured route, and policy authorization.

Safety by default

Live outbound calls and SMS are policy-gated. Evaluate evaluate_outbound_policy first, show the decision and cost, and wait for an explicit human yes. Scopes fail closed — a tools/call for a tool whose required_scopes are not on your key returns missing MCP scopes.

Prerequisites

Install the connector

Mint a scoped key

Wire the key into the MCP server

Your agent calls the tools

Next steps

Wire an agent to a number

Read call evidence

MCP tool reference

On this page