MCP

Saperly exposes its tools over the Model Context Protocol so any agent framework can provision numbers, send SMS, and place calls as first-class tools — over Streamable HTTP with a bearer sk_ key.

Saperly ships a Model Context Protocol (MCP) server so agent frameworks can use Saperly as a set of tools — provision a number, send an SMS, place a call, check consent — without writing any HTTP glue. It speaks the Streamable HTTP transport (JSON-RPC 2.0) and authenticates with either a bearer sk_ key or an MCP OAuth access token. Any MCP-capable client (Claude, Cursor, or your own) can connect.

Endpoint


URL	`https://api.saperly.com/mcp`
Transport	Streamable HTTP (JSON-RPC 2.0)
Auth	`Authorization: Bearer <sk_key>` (or an MCP OAuth access token)

The key behaves exactly as it does for the REST API: scopes, the number allow-list, and spend caps are enforced server-side, and the workspace is read from the key. A read_only key can only call read tools; a call_only key cannot send SMS. See Authentication for the scope model.

Generic MCP client

Any client that supports the Streamable HTTP transport can connect by pointing at the endpoint and supplying the bearer header. A typical config block:

{
  "mcpServers": {
    "saperly": {
      "url": "https://api.saperly.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer sap_sk_live_..."
      }
    }
  }
}

Keep the sk_ key in an environment variable and inject it — don't commit it. Mint a narrowly-scoped child key (for example call_only, bound to one line, with a monthly_cap_cents ceiling) per agent so a runaway loop can't overspend.

Tool discovery

Tools are discovered at connect time — the client lists them via the standard MCP tools/list call and the server returns the schema for each (provision a line, send SMS, place a call, check consent, read usage, and more). You don't hardcode tool names; the framework reads them from the server. New Saperly capabilities appear as tools automatically as they ship.

Next steps

Node / TypeScript SDK — the typed v2 client (@trysaperly/sdk).
Python — call the v2 REST API directly with httpx.
Authentication — scopes, spend caps, and scoped sk_ keys.
API reference — every endpoint with a try-it playground.

Endpoint

Generic MCP client

Tool discovery

Next steps

On this page