> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Saperly MCP

> Manage Saperly phone numbers, connections, calls, SMS and usage through its official MCP server using your scoped workspace API key.

![Saperly MCP logo](https://mintcdn.com/composio-preview/YYC5iurbUCUzEs77/images/toolkits/saperly_mcp.svg?fit=max\&auto=format\&n=YYC5iurbUCUzEs77\&q=85\&s=275efda901c4080cd3a05f2b5ca1833e)

* **Category:** communication
* **Auth:** API\_KEY
* **Composio-managed OAuth available?** N/A
* **Tools:** 24
* **Triggers:** 0
* **Slug:** `SAPERLY_MCP`
* **Version:** 00000000\_00

## Tools

> [accordion] Assign number connection
>
> **Slug:** `SAPERLY_MCP_ASSIGN_NUMBER_CONNECTION`
>
> Attach a connection (the handler that answers calls) to a number — i.e. configure the line.
>
> #### Input Parameters
>
> **numberId** `string` *required*
>
> Saperly number id
>
> **connectionId** `string` *required*
>
> Saperly connection id
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).

> [accordion] Create connection
>
> **Slug:** `SAPERLY_MCP_CREATE_CONNECTION`
>
> Create a connection. hosted = an in-network AI assistant; manual = your own brain via BYO-LLM.
>
> #### Input Parameters
>
> **mode** `string ("hosted" | "manual")`
>
> hosted | manual
>
> **name** `string` *required*
>
> Human-friendly name
>
> **voiceId** `string`
>
> Voice ID from list\_voices, including a ready private cloned voice. Hosted agents only.
>
> **language** `string`
>
> Hosted lines: the agent’s spoken language as a BCP-47 tag (e.g. "en", "es", "en-US"). Sets the in-network transcription hint (which language the caller speaks). Omit to let the carrier auto-detect.
>
> **disclosure** `string`
>
> The TCPA disclosure spoken as the line’s first, uninterruptible utterance when compliance is on.
>
> **instructions** `string`
>
> System prompt / instructions for the assistant
>
> **smsAutoReply** `boolean`
>
> Hosted lines: auto-reply to inbound SMS with the line’s own LLM (off by default). Manual lines forward inbound to their webhook brain regardless of this flag.
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).
>
> **backgroundAudio** `string ("off" | "office")`
>
> Hosted background ambience. off clears it; office enables it.
>
> **backgroundVolume** `number`
>
> Office volume, 0.1–1.0 in steps of 0.1 (default 0.2). Supplying volume alone enables office ambience.
>
> **manualWebhookUrl** `string`
>
> Manual mode: the webhook-brain URL Saperly POSTs each turn to (signed with the connection’s manualSecret) when no live agent socket is connected. The serverless brain endpoint (e.g. a Base44 backend function).
>
> **complianceEnabled** `boolean`
>
> Compliance (TCPA): when on, the line speaks the disclosure as an uninterruptible opener + gets the caller opt-out tool. Defaults on; if no disclosure is set, a standard org-named default is used.

> [accordion] Delete connection
>
> **Slug:** `SAPERLY_MCP_DELETE_CONNECTION`
>
> Delete a connection.
>
> #### Input Parameters
>
> **id** `string` *required*
>
> Saperly connection id
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).

> [accordion] Get call
>
> **Slug:** `SAPERLY_MCP_GET_CALL`
>
> Fetch one call record by its Saperly id.
>
> #### Input Parameters
>
> **id** `string` *required*
>
> Saperly call id

> [accordion] Get connection
>
> **Slug:** `SAPERLY_MCP_GET_CONNECTION`
>
> Fetch one connection by its Saperly id.
>
> #### Input Parameters
>
> **id** `string` *required*
>
> Saperly connection id

> [accordion] Get number
>
> **Slug:** `SAPERLY_MCP_GET_NUMBER`
>
> Fetch one phone number by its Saperly id.
>
> #### Input Parameters
>
> **id** `string` *required*
>
> Saperly number id

> [accordion] Get usage
>
> **Slug:** `SAPERLY_MCP_GET_USAGE`
>
> Summarize calls, messages, and the current balance for this workspace.
>
> #### Input Parameters
>
> **since** `string`
>
> ISO timestamp lower bound (optional)

> [accordion] List calls
>
> **Slug:** `SAPERLY_MCP_LIST_CALLS`
>
> List the calls in this workspace.

> [accordion] List connections
>
> **Slug:** `SAPERLY_MCP_LIST_CONNECTIONS`
>
> List the connections (call/message handlers) configured in this workspace.

> [accordion] List custom voices
>
> **Slug:** `SAPERLY_MCP_LIST_CUSTOM_VOICES`
>
> List this workspace’s private voices and their processing status. Upload recordings through the dashboard or multipart POST /custom-voices. Only active voices can be selected.

> [accordion] List messages
>
> **Slug:** `SAPERLY_MCP_LIST_MESSAGES`
>
> List SMS messages in this workspace, optionally filtered to one number.
>
> #### Input Parameters
>
> **numberId** `string`
>
> Filter to one Saperly number id

> [accordion] List numbers
>
> **Slug:** `SAPERLY_MCP_LIST_NUMBERS`
>
> List the active phone numbers (lines) provisioned in this workspace.

> [accordion] List voices
>
> **Slug:** `SAPERLY_MCP_LIST_VOICES`
>
> List stock voices and ready private voices. Pass an id as voiceId to create\_connection or update\_connection. Upload recordings in the dashboard or POST /custom-voices (multipart); private voices are hosted-only.
>
> #### Input Parameters
>
> **language** `string`
>
> Optional language prefix such as en.

> [accordion] Place call
>
> **Slug:** `SAPERLY_MCP_PLACE_CALL`
>
> Dial an outbound call from one of your numbers. The connection answers it.
>
> #### Input Parameters
>
> **to** `string` *required*
>
> Destination phone number (E.164)
>
> **connectionId** `string`
>
> Connection to handle the call (optional)
>
> **fromNumberId** `string` *required*
>
> Saperly number id to call from
>
> **instructions** `string`
>
> Per-call system prompt — what the AI should say/do on this call, overriding the line saved instructions (optional)
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).

> [accordion] Provision number
>
> **Slug:** `SAPERLY_MCP_PROVISION_NUMBER`
>
> Order a new phone number and add it to this workspace. Charges the prepaid balance. The first number needs no card; provisioning a SECOND number requires a saved payment method on file (otherwise it fails with PaymentMethodRequired).
>
> #### Input Parameters
>
> **country** `string`
>
> ISO 3166-1 alpha-2 country (e.g. US)
>
> **areaCode** `string`
>
> Preferred area code
>
> **numberType** `string`
>
> Number type (e.g. local, toll-free)
>
> **phoneNumber** `string`
>
> A specific E.164 number to order, if known
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).
>
> **approveHigherPrice** `boolean`
>
> Proceed even if the live price exceeds the expected price.
>
> **expectedMonthlyPriceCents** `number`
>
> The monthly price (cents) you expect. If the live price is higher, the order is rejected with PriceChanged unless approveHigherPrice is set.
>
> **expectedUpfrontPriceCents** `number`
>
> The upfront price (cents) you expect (see expectedMonthlyPriceCents).

> [accordion] Release number
>
> **Slug:** `SAPERLY_MCP_RELEASE_NUMBER`
>
> Release a phone number and stop billing it.
>
> #### Input Parameters
>
> **id** `string` *required*
>
> Saperly number id
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).

> [accordion] Search available numbers
>
> **Slug:** `SAPERLY_MCP_SEARCH_AVAILABLE_NUMBERS`
>
> Search available inventory for numbers available to provision, priced for this workspace.
>
> #### Input Parameters
>
> **limit** `number`
>
> Max results to return
>
> **country** `string` *required*
>
> ISO 3166-1 alpha-2 country (e.g. US)
>
> **areaCode** `string`
>
> Preferred area code
>
> **numberType** `string`
>
> Number type (e.g. local, toll-free, mobile)

> [accordion] Send sms
>
> **Slug:** `SAPERLY_MCP_SEND_SMS`
>
> Send an SMS from one of your numbers.
>
> #### Input Parameters
>
> **to** `string` *required*
>
> Destination phone number (E.164)
>
> **body** `string` *required*
>
> Message text
>
> **fromNumberId** `string` *required*
>
> Saperly number id to send from
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).

> [accordion] Set caller id name
>
> **Slug:** `SAPERLY_MCP_SET_CALLER_ID_NAME`
>
> Set (or clear) a line’s outbound CALLER ID NAME — the 1–15 letter/number/space display name (CNAM) shown alongside the number on the called party’s phone. Unlike the SMS sender name this is NOT free per-call text: it’s a listing registered to the number, so display is best-effort (the recipient’s carrier decides via a CNAM dip; mainly US & Canada, and it takes time to propagate — many mobile carriers may not show it). Pass an empty string or null to clear it (show the bare number). A bad value returns InvalidCallerIdName. Line-reconfiguration, so a number-scoped key is bounded to its allow-list.
>
> #### Input Parameters
>
> **id** `string` *required*
>
> Saperly number id
>
> **callerIdName** `string`
>
> Caller ID name (1–15 letters/digits/spaces) registered as the line’s CNAM listing, or an empty string to clear it (show the bare number).
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).

> [accordion] Set sms sender
>
> **Slug:** `SAPERLY_MCP_SET_SMS_SENDER`
>
> Set (or clear) a line’s alphanumeric SMS sender name — the 1–11 letter/number label recipients see as the “from” on INTERNATIONAL SMS only. US & Canada carriers don’t allow alphanumeric senders, so US/Canada recipients always see the phone number. It is one-way (recipients can’t reply to a name). Pass an empty string or null to clear it (revert to sending from the phone number). A bad value returns InvalidSmsSenderId. Line-reconfiguration, so a number-scoped key is bounded to its allow-list.
>
> #### Input Parameters
>
> **id** `string` *required*
>
> Saperly number id
>
> **smsSenderId** `string`
>
> Alphanumeric sender name (1–11 letters/digits) for international SMS, or an empty string to clear it (send from the phone number).
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).

> [accordion] Speak into call
>
> **Slug:** `SAPERLY_MCP_SPEAK_INTO_CALL`
>
> Speak a line into a live call. NOTE: out-of-band speech injection is not available — the carrier owns the in-network audio loop and only pulls the brain on a caller turn. In manual mode the agent speaks by REPLYING on its turn (the BYO-LLM / agent-as-channel path); Saperly never holds the media path.
>
> #### Input Parameters
>
> **text** `string` *required*
>
> Text to speak
>
> **callId** `string` *required*
>
> Saperly call id

> [accordion] Sync connection
>
> **Slug:** `SAPERLY_MCP_SYNC_CONNECTION`
>
> Reconcile a connection — create/update its assistant and mint its manual-mode secret.
>
> #### Input Parameters
>
> **id** `string` *required*
>
> Saperly connection id
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).

> [accordion] Transfer call
>
> **Slug:** `SAPERLY_MCP_TRANSFER_CALL`
>
> Blind-transfer a live call to another destination — an E.164 phone number or a sip: URI. A Call Control action (signaling only): the carrier re-bridges the leg to the destination; Saperly never touches the audio (the no-media rule). Works across every backend — hosted, manual, and openai\_realtime — because it acts on the call’s bound carrier leg. Returns CallStartFailed if the call has no live leg or the carrier transfer fails.
>
> #### Input Parameters
>
> **to** `string` *required*
>
> Transfer destination — an E.164 phone number or a sip: URI
>
> **callId** `string` *required*
>
> Saperly call id of the live call to transfer
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).

> [accordion] Update connection
>
> **Slug:** `SAPERLY_MCP_UPDATE_CONNECTION`
>
> Update a connection’s name, instructions, compliance/disclosure — or switch its mode between hosted (an in-network AI assistant) and manual (your own brain via BYO-LLM). A mode switch reconciles automatically.
>
> #### Input Parameters
>
> **id** `string` *required*
>
> Saperly connection id
>
> **mode** `string ("hosted" | "manual")`
>
> hosted | manual
>
> **name** `string`
>
> New name
>
> **voiceId** `string`
>
> Voice ID from list\_voices, including a ready private cloned voice. Hosted agents only.
>
> **language** `string`
>
> Hosted lines: the agent’s spoken language as a BCP-47 tag (e.g. "en", "es", "en-US") — the in-network transcription hint. Omit to leave it unchanged; pass an empty string ("") to RESET it to auto-detect.
>
> **disclosure** `string`
>
> The TCPA disclosure spoken as the uninterruptible opener when compliance is on.
>
> **instructions** `string`
>
> New system prompt / instructions
>
> **smsAutoReply** `boolean`
>
> Hosted lines: auto-reply to inbound SMS with the line’s own LLM (off by default). Manual lines forward inbound to their webhook brain regardless of this flag.
>
> **idempotencyKey** `string`
>
> Optional client idempotency key — a retried tool call with the same key + arguments returns the original result instead of acting again (e.g. re-charging).
>
> **backgroundAudio** `string ("off" | "office")`
>
> Hosted background ambience. off clears it; office enables it.
>
> **backgroundVolume** `number`
>
> Office volume, 0.1–1.0 in steps of 0.1 (default 0.2). Supplying volume alone enables office ambience.
>
> **manualWebhookUrl** `string`
>
> Manual mode: the webhook-brain URL Saperly POSTs each turn to (signed with the connection’s manualSecret) when no live agent socket is connected. The serverless brain endpoint (e.g. a Base44 backend function).
>
> **complianceEnabled** `boolean`
>
> Compliance (TCPA): when on, the line speaks the disclosure as an uninterruptible opener + gets the caller opt-out tool.
