The MCP server exposes twelve tools. Each section below documents one tool: required scope, parameters, an example natural-language prompt that triggers it, and the JSON response shape.
send_sms
Billable. Send one SMS message to one recipient. Your account is charged per message part at the rate for the destination. The call returns as soon as VertexSMS has accepted the message for processing, which does not guarantee delivery: account rules such as opt-outs, duplicate protection or insufficient balance can still block it afterwards. Use get_sms_status with the returned message_id to see the outcome.
Required scope: sms:send
Parameters
| Field | Type | Description |
|---|---|---|
| to | string | Recipient phone number in E.164 format. Required. |
| from | string | Sender ID (max 11 alphanumeric chars) or a registered phone number. Required. |
| message | string | Message body. Long messages are split into multi-part SMS automatically. Required. |
| priority | enum | One of high, normal, low. |
| scheduled | string | ISO 8601 datetime to schedule delivery. |
| correctBy | string | ISO 3166-1 alpha-2 country code; auto-correct the recipient number for that country. |
| coding | int | Encoding: 0=GSM-7, 1=8-bit, 2=UCS-2. |
| expireIn | int | Message expiry in seconds (360 – 432000). |
Example prompt
Example response
Tool-specific errors: VERTEX_SEND_FAILED for rejected messages (bad sender, blacklisted number, etc.). The vertex_error_code field on the envelope often disambiguates, cross-reference with REST API errors.
get_sms_rates
Look up the per-operator SMS rate for a country. Read-only. Server-side cached for one hour.
Required scope: sms:rates
Parameters
| Field | Type | Description |
|---|---|---|
| country | string | ISO 3166-1 alpha-2 code, e.g. LT, US, DE. Required. |
Example prompt
Example response
get_sms_status
Look up the delivery status of one message sent from your account, by the message_id that send_sms returned. Read-only. Only recent messages are found; archived or unknown ids return NOT_FOUND. The message text is not returned.
Required scope: sms:status
Parameters
| Field | Type | Description |
|---|---|---|
| message_id | string | Message id returned by send_sms, digits only. Required. |
Statuses
| Status | Meaning |
|---|---|
| pending | Accepted, not yet handed to the operator. |
| sent | Handed to the operator, no delivery report yet. |
| delivered | The operator reported delivery to the handset. |
| undelivered | The operator reported that delivery failed. |
| seen | The recipient opened the message (where the channel reports it). |
| expired | The message expired before it could be delivered. |
Example prompt
Example response
Timestamps that have not happened yet are null. Tool-specific errors: NOT_FOUND for an unknown or archived message_id.
get_balance
Read the current balance of your VertexSMS account as a number. Read-only, no parameters. The value is reported as stored on your account; the API does not state a currency in this response, and the value can be negative.
Required scope: account:balance
Example prompt
Example response
correct_phone_number
Validate and normalize phone numbers to E.164. Classifies each as mobile, landline, or unknown. Read-only. Up to 100 numbers per call.
Required scope: numbers:read
Parameters
| Field | Type | Description |
|---|---|---|
| numbers | array | Array of { number, country } objects. country is ISO 3166-1 alpha-2. Required. |
Example prompt
Example response
get_operator
Look up an operator by its internal VertexSMS operator ID. Returns name, country, MCC, and the list of MNCs. Read-only.
Required scope: numbers:read
Parameters
| Field | Type | Description |
|---|---|---|
| operator_id | string|int | Internal VertexSMS operator identifier (e.g. 493). Required. |
Example prompt
Example response
get_mcc_mnc_list
List MCC/MNC entries for a country, with their VertexSMS operator IDs. Read-only. Paginated.
Required scope: numbers:read
Parameters
| Field | Type | Description |
|---|---|---|
| country | string | ISO 3166-1 alpha-2 country code. Required. |
| page | int | Optional 1-based page number. |
Example prompt
Example response
get_mobile_prefixes
List mobile number prefixes for a country, mapped to VertexSMS operator IDs. Read-only.
Required scope: numbers:read
Parameters
| Field | Type | Description |
|---|---|---|
| country | string | ISO 3166-1 alpha-2 country code. Required. |
Example prompt
Example response
lookup_hlr
Billable. Synchronous Home Location Register lookup. Returns the operator, country, MCC/MNC, IMSI, and ported information for a phone number. Charged per query whether the result is "found" or "unknown."
Required scope: hlr:lookup
Parameters
| Field | Type | Description |
|---|---|---|
| msisdn | string | International subscriber number, e.g. 37069912345. Required. |
Example prompt
Example response
register_sender_id
Submit an alphanumeric Sender ID for VertexSMS approval. The registration goes through manual human review and may take several business days. Status updates can be received via the optional notification webhook.
Required scope: sender:write
Parameters
| Field | Type | Description |
|---|---|---|
| name | string | Sender name, 3–11 alphanumeric characters. Required. |
| category | enum | One of Company, Product, Brand, Shortcode, Landline, Other. Required. |
| category_description | string | Description / comments shown to the reviewer. Required. |
| notification_url | string | Optional webhook URL for status-change notifications. |
Example prompt
Example response
register_msisdn_sender
Register a mobile number as a Sender ID. VertexSMS sends a 5-digit PIN via SMS to the number; you must follow up with confirm_msisdn_sender to complete registration.
Required scope: sender:write
Parameters
| Field | Type | Description |
|---|---|---|
| msisdn | string | Mobile number in E.164 format without leading +, e.g. 37069555555. Required. |
Example prompt
Example response
confirm_msisdn_sender
Confirm a pending MSISDN Sender ID by submitting the 5-digit PIN that VertexSMS sent to the registered phone number.
Required scope: sender:write
Parameters
| Field | Type | Description |
|---|---|---|
| sender_id | string | Sender ID returned by register_msisdn_sender. Required. |
| code | string | 5-digit PIN from the verification SMS. Required. |