# Saperly — how to use (mcp.ai)

Connect your Saperly account and use 30 tools for phone and SMS straight from your AI agent. Connect with your own API key. Saperly is the phone carrier for AI agents, phone numbers, voice, SMS, and compliance in one API.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_saperly?ms=1787293380000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `saperly_assign_number_connection`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/saperly`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/saperly/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/saperly/assign/number/connection` — Attach a connection (the AI persona / answering brain from SAPERLY_CREATE_CONNECTION) to a phone number, so inbound calls and SMS to that number — and outbound calls placed from it — are handled by th
  - body: { id: string, connectionId: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/check/consent` — Check whether a contact currently has active TCPA consent for one of your Saperly numbers, given numberId (your number) and peerNumber (the contact's E.164 number) as query params. Returns {hasConsent
  - body: { numberId: string, peerNumber: string }
- `POST https://api.mcp.ai/api/saperly/create/connection` — Create a connection: the AI 'brain' that answers calls and (optionally) SMS on a Saperly phone number. A phone number binds to a connection via SAPERLY_ASSIGN_NUMBER_CONNECTION in order to answer call
  - body: { llm?: object, tts?: object, mode?: string, name: string, language?: string, disclosure?: string, mcpServers?: object[], callControl?: object, instructions?: string, smsAutoReply?: boolean, idempotency_key?: string, manualWebhookUrl?: string, complianceEnabled?: boolean }
- `POST https://api.mcp.ai/api/saperly/delete/connection` — PERMANENTLY AND IRREVERSIBLY delete a connection (the AI answering brain / persona that handles calls and SMS) by its id. THIS CANNOT BE UNDONE — there is no restore. WARNING: any phone number current
  - body: { id: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/end/call` — End an in-progress call by its id, hanging up and settling the metered cost. This is the safe, cheap, RECOMMENDED companion to SAPERLY_PLACE_CALL: placing a call starts per-minute billing, and this to
  - body: { id: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/get/call` — Fetch a single call by its id, returning its status, per-minute rate, final duration (durationSec) and cost (costCents), and the hasRecording / hasTranscript flags. costCents and durationSec are NULL 
  - body: { id: string }
- `POST https://api.mcp.ai/api/saperly/get/call/recording` — Get the audio recording for a call and return it as a downloadable file. The API answers with a 302 redirect to a signed download URL when a recording exists; the recording is fetched and returned as 
  - body: { id: string }
- `POST https://api.mcp.ai/api/saperly/get/call/transcript` — Fetch the transcript (conversation turns/segments) of a completed call by its id. Transcripts only exist AFTER a call connects, ends, and is processed. The endpoint uses the same 404 for an unknown ca
  - body: { id: string }
- `POST https://api.mcp.ai/api/saperly/get/connection` — Fetch a single connection (the AI answering brain / persona that handles calls and SMS) by its id, returning its full config: name, mode, backend, instructions, tts voice, language, compliance/disclos
  - body: { id: string }
- `POST https://api.mcp.ai/api/saperly/get/number` — Fetch a single phone number by its id, returning its E.164 phoneNumber, bound connectionId, webhookUrl, country, numberType, pricing and lifecycle fields. Use after SAPERLY_LIST_NUMBERS to inspect one
  - body: { id: string }
- `POST https://api.mcp.ai/api/saperly/get/usage` — Return the workspace usage summary and prepaid balance: calls {count, totalCostCents, totalDurationSec}, messages {count}, and balanceCents (the prepaid balance, in cents). ALWAYS call this before any
  - body: { since?: string }
- `POST https://api.mcp.ai/api/saperly/list/calls` — Return the full voice-call history (inbound + outbound) for the connected Saperly workspace. Each call carries its id, numberId, direction, to and from_number (E.164), status, rateCentsPerMin, duratio
- `POST https://api.mcp.ai/api/saperly/list/connections` — Return every connection (the AI persona / answering 'brain' that handles calls and SMS) in the connected Saperly workspace. Each carries id, name, mode (hosted|manual), backend, instructions, llm, tts
- `POST https://api.mcp.ai/api/saperly/list/consent` — Return every TCPA consent record in the connected Saperly workspace, with each record's id, numberId (the Saperly number contact is authorized FROM), peerNumber (the contact's E.164 number), consentTy
- `POST https://api.mcp.ai/api/saperly/list/languages` — Return the spoken languages Saperly supports for voice connections, each as a {code, name} pair (about 42 entries, e.g. {'code':'en','name':'English'}). A language `code` is what you pass as a connect
- `POST https://api.mcp.ai/api/saperly/list/messages` — Return SMS messages in the connected Saperly workspace (both inbound and outbound). Each message has id, numberId, direction, to, from_number, body, segments, status and createdAt. Pass `numberId` to 
  - body: { numberId?: string }
- `POST https://api.mcp.ai/api/saperly/list/numbers` — Return every phone number provisioned in the connected Saperly workspace, with each number's id, phoneNumber (E.164), the connectionId (answering brain) bound to it, webhookUrl, country, numberType, m
- `POST https://api.mcp.ai/api/saperly/list/voices` — List the text-to-speech voices available for Saperly connections. Each voice has an id, name, gender and language; a voice id is what you pass as tts.voiceId when creating or updating a connection (SA
  - body: { language?: string }
- `POST https://api.mcp.ai/api/saperly/place/call` — PAID / METERED — places a REAL outbound voice call that RINGS A REAL PHONE and BILLS PER MINUTE (~26¢/min); it keeps billing until hung up — end it with SAPERLY_END_CALL to stop the meter. Calls FROM 
  - body: { to: string, connectionId?: string, fromNumberId: string, instructions?: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/provision/number` — PAID / METERED: provision (buy) a new phone number in a country. This SPENDS MONEY — it charges the workspace prepaid balance an upfront fee plus a RECURRING MONTHLY rent (US local ~ $1.79/mo, varies 
  - body: { country?: string, areaCode?: string, numberType?: string, idempotency_key?: string, approveHigherPrice?: boolean, expectedMonthlyPriceCents?: integer, expectedUpfrontPriceCents?: integer }
- `POST https://api.mcp.ai/api/saperly/quote/number/price` — READ-ONLY and FREE: quote the price to provision a phone number in a country/type, returning { customerMonthlyCents, customerUpfrontCents }. This DOES NOT provision, reserve, or charge anything — desp
  - body: { country: string, numberType: string }
- `POST https://api.mcp.ai/api/saperly/record/consent` — Record TCPA consent for a contact so outbound SMS (SAPERLY_SEND_SMS) and calls (SAPERLY_PLACE_CALL) from your number are permitted. Saperly's compliance gate: for a cold contact call this BEFORE sendi
  - body: { source: string, numberId: string, peerNumber: string, consentType: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/release/number` — PERMANENTLY AND IRREVERSIBLY release a phone number back to the carrier. THIS CANNOT BE UNDONE: the number leaves the workspace, is returned to the carrier pool, and CANNOT be recovered or reclaimed. 
  - body: { id: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/revoke/consent` — Revoke a contact's TCPA consent for a given Saperly number, blocking further outbound contact to them. CALL THIS WHEN A RECIPIENT SAYS 'STOP' / 'UNSUBSCRIBE' / 'do not contact me' — honoring an opt-ou
  - body: { numberId: string, peerNumber: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/send/sms` — PAID / METERED: send a single SMS from one of your Saperly numbers to an E.164 destination. This SPENDS REAL MONEY and sends a REAL text message to a REAL phone (~2 cents per 160-character segment; a 
  - body: { to: string, body: string, fromNumberId: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/set/number/caller/id` — Set the outbound caller ID name / CNAM (1-15 characters: letters, digits, spaces) presented to recipients on outbound calls from a Saperly phone number, or pass callerIdName=null to CLEAR it. callerId
  - body: { id: string, callerIdName: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/set/number/sms/sender` — Set the alphanumeric SMS sender id (1-11 alphanumeric chars, e.g. a brand name) shown as the 'from' on outbound SMS from this number, or pass smsSenderId=null to CLEAR it. Returns the updated number o
  - body: { id: string, smsSenderId: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/set/number/webhook` — Set the HTTPS webhook URL that Saperly POSTs this number's events (inbound SMS/calls, status) to. The url is required and must be https://. Returns the updated number object. NOTE: this endpoint has n
  - body: { id: string, url: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/transfer/call` — PAID / METERED — BLIND-transfers a LIVE, in-progress voice call to another destination `to` (an E.164 number like +15551230000, or a `sip:` URI). BLIND means the call is handed off UNCONDITIONALLY: th
  - body: { id: string, to: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/saperly/update/connection` — Partially update a connection (the AI answering brain bound to a number). Send only the fields you want to change (name, mode, instructions, llm, tts, language, mcpServers, callControl, complianceEnab
  - body: { id: string, llm?: object, tts?: object, mode?: string, name?: string, language?: string, disclosure?: string, mcpServers?: object[], callControl?: object, instructions?: string, smsAutoReply?: boolean, idempotency_key?: string, manualWebhookUrl?: string, complianceEnabled?: boolean }

## Example prompts
- "What can I do in Saperly?"
- "Show me a summary of my Saperly account"

## More
- Page: https://mcp.ai/saperly
- Agent spec (llms.txt): https://mcp.ai/saperly/llms.txt
- Postman collection: https://mcp.ai/saperly/postman.json