Skip to main content
Saperly MCP logo
  • Category: communication
  • Auth: API_KEY
  • Composio-managed OAuth available? N/A
  • Tools: 24
  • Triggers: 0
  • Slug: SAPERLY_MCP
  • Version: 00000000_00

Tools

Slug: SAPERLY_MCP_ASSIGN_NUMBER_CONNECTIONAttach a connection (the handler that answers calls) to a number — i.e. configure the line.

Input Parameters

string
required
Saperly number id
string
required
Saperly connection id
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).
Slug: SAPERLY_MCP_CREATE_CONNECTIONCreate a connection. hosted = an in-network AI assistant; manual = your own brain via BYO-LLM.

Input Parameters

string ("hosted" | "manual")
hosted | manual
string
required
Human-friendly name
string
Voice ID from list_voices, including a ready private cloned voice. Hosted agents only.
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.
string
The TCPA disclosure spoken as the line’s first, uninterruptible utterance when compliance is on.
string
System prompt / instructions for the assistant
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.
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).
string ("off" | "office")
Hosted background ambience. off clears it; office enables it.
number
Office volume, 0.1–1.0 in steps of 0.1 (default 0.2). Supplying volume alone enables office ambience.
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).
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.
Slug: SAPERLY_MCP_DELETE_CONNECTIONDelete a connection.

Input Parameters

string
required
Saperly connection id
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).
Slug: SAPERLY_MCP_GET_CALLFetch one call record by its Saperly id.

Input Parameters

string
required
Saperly call id
Slug: SAPERLY_MCP_GET_CONNECTIONFetch one connection by its Saperly id.

Input Parameters

string
required
Saperly connection id
Slug: SAPERLY_MCP_GET_NUMBERFetch one phone number by its Saperly id.

Input Parameters

string
required
Saperly number id
Slug: SAPERLY_MCP_GET_USAGESummarize calls, messages, and the current balance for this workspace.

Input Parameters

string
ISO timestamp lower bound (optional)
Slug: SAPERLY_MCP_LIST_CALLSList the calls in this workspace.
Slug: SAPERLY_MCP_LIST_CONNECTIONSList the connections (call/message handlers) configured in this workspace.
Slug: SAPERLY_MCP_LIST_CUSTOM_VOICESList 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.
Slug: SAPERLY_MCP_LIST_MESSAGESList SMS messages in this workspace, optionally filtered to one number.

Input Parameters

string
Filter to one Saperly number id
Slug: SAPERLY_MCP_LIST_NUMBERSList the active phone numbers (lines) provisioned in this workspace.
Slug: SAPERLY_MCP_LIST_VOICESList 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

string
Optional language prefix such as en.
Slug: SAPERLY_MCP_PLACE_CALLDial an outbound call from one of your numbers. The connection answers it.

Input Parameters

string
required
Destination phone number (E.164)
string
Connection to handle the call (optional)
string
required
Saperly number id to call from
string
Per-call system prompt — what the AI should say/do on this call, overriding the line saved instructions (optional)
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).
Slug: SAPERLY_MCP_PROVISION_NUMBEROrder 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

string
ISO 3166-1 alpha-2 country (e.g. US)
string
Preferred area code
string
Number type (e.g. local, toll-free)
string
A specific E.164 number to order, if known
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).
boolean
Proceed even if the live price exceeds the expected price.
number
The monthly price (cents) you expect. If the live price is higher, the order is rejected with PriceChanged unless approveHigherPrice is set.
number
The upfront price (cents) you expect (see expectedMonthlyPriceCents).
Slug: SAPERLY_MCP_RELEASE_NUMBERRelease a phone number and stop billing it.

Input Parameters

string
required
Saperly number id
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).
Slug: SAPERLY_MCP_SEARCH_AVAILABLE_NUMBERSSearch available inventory for numbers available to provision, priced for this workspace.

Input Parameters

number
Max results to return
string
required
ISO 3166-1 alpha-2 country (e.g. US)
string
Preferred area code
string
Number type (e.g. local, toll-free, mobile)
Slug: SAPERLY_MCP_SEND_SMSSend an SMS from one of your numbers.

Input Parameters

string
required
Destination phone number (E.164)
string
required
Message text
string
required
Saperly number id to send from
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).
Slug: SAPERLY_MCP_SET_CALLER_ID_NAMESet (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

string
required
Saperly number id
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).
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).
Slug: SAPERLY_MCP_SET_SMS_SENDERSet (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

string
required
Saperly number id
string
Alphanumeric sender name (1–11 letters/digits) for international SMS, or an empty string to clear it (send from the phone number).
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).
Slug: SAPERLY_MCP_SPEAK_INTO_CALLSpeak 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

string
required
Text to speak
string
required
Saperly call id
Slug: SAPERLY_MCP_SYNC_CONNECTIONReconcile a connection — create/update its assistant and mint its manual-mode secret.

Input Parameters

string
required
Saperly connection id
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).
Slug: SAPERLY_MCP_TRANSFER_CALLBlind-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

string
required
Transfer destination — an E.164 phone number or a sip: URI
string
required
Saperly call id of the live call to transfer
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).
Slug: SAPERLY_MCP_UPDATE_CONNECTIONUpdate 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

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