The MCP server exposes ten 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 an SMS message to one or more recipients. Charges your account at the per-operator rate for the destination.
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
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. |