---
canonical_url: "https://docs.composio.dev/toolkits/saperly_mcp"
markdown_url: "https://docs.composio.dev/toolkits/saperly_mcp.md"
product: "platform"
version: null
last_updated: null
---

# Saperly MCP

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

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

## Tools

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `numberId` | string | Yes | Saperly number id |
| `connectionId` | string | Yes | Saperly connection id |
| `idempotencyKey` | string | No | 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). |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string ("hosted" | "manual") | No | hosted | manual |
| `name` | string | Yes | Human-friendly name |
| `voiceId` | string | No | Voice ID from list_voices, including a ready private cloned voice. Hosted agents only. |
| `language` | string | No | 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 | No | The TCPA disclosure spoken as the line’s first, uninterruptible utterance when compliance is on. |
| `instructions` | string | No | System prompt / instructions for the assistant |
| `smsAutoReply` | boolean | No | 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 | No | 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") | No | Hosted background ambience. off clears it; office enables it. |
| `backgroundVolume` | number | No | Office volume, 0.1–1.0 in steps of 0.1 (default 0.2). Supplying volume alone enables office ambience. |
| `manualWebhookUrl` | string | No | 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 | No | 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. |

### Delete connection

**Slug:** `SAPERLY_MCP_DELETE_CONNECTION`

Delete a connection.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Saperly connection id |
| `idempotencyKey` | string | No | 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). |

### Get call

**Slug:** `SAPERLY_MCP_GET_CALL`

Fetch one call record by its Saperly id.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Saperly call id |

### Get connection

**Slug:** `SAPERLY_MCP_GET_CONNECTION`

Fetch one connection by its Saperly id.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Saperly connection id |

### Get number

**Slug:** `SAPERLY_MCP_GET_NUMBER`

Fetch one phone number by its Saperly id.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Saperly number id |

### Get usage

**Slug:** `SAPERLY_MCP_GET_USAGE`

Summarize calls, messages, and the current balance for this workspace.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `since` | string | No | ISO timestamp lower bound (optional) |

### List calls

**Slug:** `SAPERLY_MCP_LIST_CALLS`

List the calls in this workspace.

### List connections

**Slug:** `SAPERLY_MCP_LIST_CONNECTIONS`

List the connections (call/message handlers) configured in this workspace.

### 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.

### List messages

**Slug:** `SAPERLY_MCP_LIST_MESSAGES`

List SMS messages in this workspace, optionally filtered to one number.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `numberId` | string | No | Filter to one Saperly number id |

### List numbers

**Slug:** `SAPERLY_MCP_LIST_NUMBERS`

List the active phone numbers (lines) provisioned in this workspace.

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `language` | string | No | Optional language prefix such as en. |

### Place call

**Slug:** `SAPERLY_MCP_PLACE_CALL`

Dial an outbound call from one of your numbers. The connection answers it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | string | Yes | Destination phone number (E.164) |
| `connectionId` | string | No | Connection to handle the call (optional) |
| `fromNumberId` | string | Yes | Saperly number id to call from |
| `instructions` | string | No | Per-call system prompt — what the AI should say/do on this call, overriding the line saved instructions (optional) |
| `idempotencyKey` | string | No | 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). |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `country` | string | No | ISO 3166-1 alpha-2 country (e.g. US) |
| `areaCode` | string | No | Preferred area code |
| `numberType` | string | No | Number type (e.g. local, toll-free) |
| `phoneNumber` | string | No | A specific E.164 number to order, if known |
| `idempotencyKey` | string | No | 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 | No | Proceed even if the live price exceeds the expected price. |
| `expectedMonthlyPriceCents` | number | No | The monthly price (cents) you expect. If the live price is higher, the order is rejected with PriceChanged unless approveHigherPrice is set. |
| `expectedUpfrontPriceCents` | number | No | The upfront price (cents) you expect (see expectedMonthlyPriceCents). |

### Release number

**Slug:** `SAPERLY_MCP_RELEASE_NUMBER`

Release a phone number and stop billing it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Saperly number id |
| `idempotencyKey` | string | No | 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). |

### Search available numbers

**Slug:** `SAPERLY_MCP_SEARCH_AVAILABLE_NUMBERS`

Search available inventory for numbers available to provision, priced for this workspace.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Max results to return |
| `country` | string | Yes | ISO 3166-1 alpha-2 country (e.g. US) |
| `areaCode` | string | No | Preferred area code |
| `numberType` | string | No | Number type (e.g. local, toll-free, mobile) |

### Send sms

**Slug:** `SAPERLY_MCP_SEND_SMS`

Send an SMS from one of your numbers.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | string | Yes | Destination phone number (E.164) |
| `body` | string | Yes | Message text |
| `fromNumberId` | string | Yes | Saperly number id to send from |
| `idempotencyKey` | string | No | 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). |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Saperly number id |
| `callerIdName` | string | No | 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 | No | 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). |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Saperly number id |
| `smsSenderId` | string | No | Alphanumeric sender name (1–11 letters/digits) for international SMS, or an empty string to clear it (send from the phone number). |
| `idempotencyKey` | string | No | 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). |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text to speak |
| `callId` | string | Yes | Saperly call id |

### Sync connection

**Slug:** `SAPERLY_MCP_SYNC_CONNECTION`

Reconcile a connection — create/update its assistant and mint its manual-mode secret.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Saperly connection id |
| `idempotencyKey` | string | No | 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). |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | string | Yes | Transfer destination — an E.164 phone number or a sip: URI |
| `callId` | string | Yes | Saperly call id of the live call to transfer |
| `idempotencyKey` | string | No | 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). |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Saperly connection id |
| `mode` | string ("hosted" | "manual") | No | hosted | manual |
| `name` | string | No | New name |
| `voiceId` | string | No | Voice ID from list_voices, including a ready private cloned voice. Hosted agents only. |
| `language` | string | No | 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 | No | The TCPA disclosure spoken as the uninterruptible opener when compliance is on. |
| `instructions` | string | No | New system prompt / instructions |
| `smsAutoReply` | boolean | No | 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 | No | 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") | No | Hosted background ambience. off clears it; office enables it. |
| `backgroundVolume` | number | No | Office volume, 0.1–1.0 in steps of 0.1 (default 0.2). Supplying volume alone enables office ambience. |
| `manualWebhookUrl` | string | No | 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 | No | Compliance (TCPA): when on, the line speaks the disclosure as an uninterruptible opener + gets the caller opt-out tool. |