Use CallOnline through MCP

CallOnline exposes a stateless MCP endpoint at https://callonline.app/mcp. It supports MCP 2026-07-28 discovery and requests plus legacy 2025-11-25, 2025-06-18, and 2025-03-26 initialization. The tool catalog covers public documentation, calls, voices, billing readiness, and purchase-session workflows.

Discover the server

Modern clients should call server/discover first. Every modern POST includes matching MCP-Protocol-Version and Mcp-Method headers, plus protocol version and client capabilities in params._meta. A tools/call request also includes an Mcp-Name header matching params.name.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-client",
        "version": "1.0.0"
      }
    }
  }
}

Legacy clients initialize with a supported 2025 protocol version, capabilities, and client information, then send the id-less notifications/initialized notification. The endpoint returns 202 Accepted with an empty body for that legacy notification. In either era, call tools/list and use the returned schemas instead of relying on a hard-coded tool list.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "example-legacy-client",
      "version": "1.0.0"
    }
  }
}

Public documentation tools

These tools read the same published corpus as the website and require no API key:

• search_documentation(query, category?, limit?) searches seven public collections. Query length is 2–160 characters; limit defaults to 5 and cannot exceed 10.
• get_documentation(pathOrId) accepts a document ID, canonical resource path, or .md companion path and returns the complete Markdown with a canonical citation.
• get_api_operation(operationId) returns the exact method, path, summary, OpenAPI URL, and a related guide when one is mapped.

Example tool call:

{
  "jsonrpc": "2.0",
  "id": "docs-1",
  "method": "tools/call",
  "params": {
    "name": "search_documentation",
    "arguments": {
      "query": "verify webhook signature",
      "category": "webhooks",
      "limit": 3
    }
  }
}

An agent should follow search with get_documentation before giving detailed implementation advice. That second call supplies the complete current source rather than only a ranking snippet.

Protected action tools

Tools such as place_call, get_call_status, cancel_call, billing status, usage balance, and purchase-session creation call protected account APIs. Send an Authorization: Bearer ... header to the MCP request; CallOnline forwards it to the relevant handler.

Use callonline.calls for call actions, callonline.billing for billing and commerce actions, and the appropriate webhook scope for webhook REST operations. Keep the key in the MCP host’s secret store, not in a prompt.

Approve call placement and cancellation

place_call and cancel_call use a two-step server approval and durable idempotency flow. Supply an idempotencyKey containing 8–120 letters, numbers, periods, underscores, colons, or hyphens. The first call omits approvalToken and returns an MCP result whose status is 202, with approvalRequired, an opaque token, and its expiry. Show the exact action to the user, obtain approval, and repeat the same tool call with the returned token.

{
  "jsonrpc": "2.0",
  "id": "cancel-1",
  "method": "tools/call",
  "params": {
    "name": "cancel_call",
    "arguments": {
      "callId": "call_123",
      "idempotencyKey": "cancel-call_123-20260803"
    }
  }
}

The approval lasts five minutes, can be consumed once, and is bound to the authenticated account, API key, tool, idempotency key, and exact action arguments. Changing any bound value invalidates it. Cancellation also verifies that the call belongs to the authenticated account before issuing approval.

After execution, an exact retry with the same idempotency key and arguments replays the stored result without dialing or hanging up again. Reusing a key with different arguments returns a conflict. A pending or indeterminate provider outcome is locked and marked non-retryable; inspect get_call_status before deciding whether a genuinely new action is safe.

Agent safety policy

Tool availability is not permission to act. Configure the agent host to:

1. require human confirmation before a live call or purchase;
2. collect the exact compliance fields from an approved system of record;
3. never invent consent evidence, local-time context, or caller identity;
4. stop on a compliance block instead of editing fields to obtain approval;
5. reuse the original idempotency key for an exact retry and never switch to a new key after a pending or indeterminate outcome;
6. cite the canonical documentation URL returned by the tool.

Documentation retrieval can be autonomous because the corpus is public and read-only. Live calls and purchases should remain inside your explicit authorization boundary.