VertexSMS LLM-readable site index
We use cookies to improve your experience on this site and serve more relevant content to you. By continuing to browse our site you agree to our use of cookies, revised Privacy Policy and Terms of Service.  More information about cookies
mcp server

Let your AI talk.
We handle the SMS.

Connect Claude, Cursor, VS Code Copilot or your own AI agent to VertexSMS. Twelve tools, no glue code, no API plumbing.

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

FieldTypeDescription
tostringRecipient phone number in E.164 format. Required.
fromstringSender ID (max 11 alphanumeric chars) or a registered phone number. Required.
messagestringMessage body. Long messages are split into multi-part SMS automatically. Required.
priorityenumOne of high, normal, low.
scheduledstringISO 8601 datetime to schedule delivery.
correctBystringISO 3166-1 alpha-2 country code; auto-correct the recipient number for that country.
codingintEncoding: 0=GSM-7, 1=8-bit, 2=UCS-2.
expireInintMessage expiry in seconds (360 – 432000).

Example prompt

EXAMPLE PROMPT
"Send 'Your verification code is 4815' from VERTEXSMS to +37069555555."

Example response

RESPONSE
{ "message_id": "1281532560", "status": "queued", "parts": 1, "destination": "+37069555555" }

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

FieldTypeDescription
countrystringISO 3166-1 alpha-2 code, e.g. LT, US, DE. Required.

Example prompt

EXAMPLE PROMPT
"What does it cost to send an SMS to Lithuania?"

Example response

RESPONSE
{ "country": "LT", "country_name": "Lithuania", "rates": [ { "operator": "BITE", "network": "Bite", "rate_eur": "0.045", "mcc": "246", "mnc": "020" }, { "operator": "Telia", "network": "Telia", "rate_eur": "0.045", "mcc": "246", "mnc": "010" } ], "cache_age_seconds": 412 }

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

FieldTypeDescription
message_idstringMessage id returned by send_sms, digits only. Required.

Statuses

StatusMeaning
pendingAccepted, not yet handed to the operator.
sentHanded to the operator, no delivery report yet.
deliveredThe operator reported delivery to the handset.
undeliveredThe operator reported that delivery failed.
seenThe recipient opened the message (where the channel reports it).
expiredThe message expired before it could be delivered.

Example prompt

EXAMPLE PROMPT
"Was message 1281532560 delivered?"

Example response

RESPONSE
{ "message_id": "1281532560", "status": "delivered", "from": "MyShop", "to": "37069912345", "created_at": "2026-11-20 12:22:15", "sent_at": "2026-11-20 12:22:18", "delivered_at": "2026-11-20 12:22:22", "error_code": 0 }

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 PROMPT
"What is my VertexSMS balance?"

Example response

RESPONSE
{ "balance": 42.1234 }

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

FieldTypeDescription
numbersarrayArray of { number, country } objects. country is ISO 3166-1 alpha-2. Required.

Example prompt

EXAMPLE PROMPT
"Validate these numbers as Lithuanian: 861860698, (370)-618-60698, 6186 0698."

Example response

RESPONSE
{ "count": 3, "results": [ { "input_number": "861860698", "country": "LT", "number_type": "mobile", "mobile": true, "number_e164": "+37061860698", "error": null }, { "input_number": "(370)-618-60698", "country": "LT", "number_type": "mobile", "mobile": true, "number_e164": "+37061860698", "error": null } ] }

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

FieldTypeDescription
operator_idstring|intInternal VertexSMS operator identifier (e.g. 493). Required.

Example prompt

EXAMPLE PROMPT
"Which operator does VertexSMS ID 493 correspond to?"

Example response

RESPONSE
{ "operator_id": 493, "name": "BITE", "country": "LT", "mcc": "246", "mnc": ["020", "028"] }

get_mcc_mnc_list

List MCC/MNC entries for a country, with their VertexSMS operator IDs. Read-only. Paginated.

Required scope: numbers:read

Parameters

FieldTypeDescription
countrystringISO 3166-1 alpha-2 country code. Required.
pageintOptional 1-based page number.

Example prompt

EXAMPLE PROMPT
"List the mobile networks in Lithuania."

Example response

RESPONSE
{ "country": "LT", "page": 1, "count": 2, "entries": [ { "country": "LT", "mcc": "246", "mnc": "01", "operator_id": "1891" }, { "country": "LT", "mcc": "246", "mnc": "02", "operator_id": "493" } ] }

get_mobile_prefixes

List mobile number prefixes for a country, mapped to VertexSMS operator IDs. Read-only.

Required scope: numbers:read

Parameters

FieldTypeDescription
countrystringISO 3166-1 alpha-2 country code. Required.

Example prompt

EXAMPLE PROMPT
"Which operator owns Lithuanian numbers starting with 3706000?"

Example response

RESPONSE
{ "country": "LT", "count": 2, "prefixes": [ { "prefix": "3706000", "country": "LT", "operator_id": "2536" }, { "prefix": "3706001", "country": "LT", "operator_id": "2536" } ] }

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

FieldTypeDescription
msisdnstringInternational subscriber number, e.g. 37069912345. Required.

Example prompt

EXAMPLE PROMPT
"Run an HLR lookup on +37069912345."

Example response

RESPONSE
{ "msisdn": "37069912345", "id": "1203877133", "error_code": "0", "imsi": "246021005160001", "country": "LT", "mcc": "246", "mnc": "021", "operator_id": null, "ported": null }

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

FieldTypeDescription
namestringSender name, 3–11 alphanumeric characters. Required.
categoryenumOne of Company, Product, Brand, Shortcode, Landline, Other. Required.
category_descriptionstringDescription / comments shown to the reviewer. Required.
notification_urlstringOptional webhook URL for status-change notifications.

Example prompt

EXAMPLE PROMPT
"Register 'ACMECORP' as a brand sender for our outgoing notifications."

Example response

RESPONSE
{ "sender_id": "1234", "status": "submitted" }

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

FieldTypeDescription
msisdnstringMobile number in E.164 format without leading +, e.g. 37069555555. Required.

Example prompt

EXAMPLE PROMPT
"Register +37069555555 as a sender."

Example response

RESPONSE
{ "sender_id": "5678", "status": "pending_confirmation", "next_step": "Call confirm_msisdn_sender with the 5-digit PIN delivered via SMS." }

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

FieldTypeDescription
sender_idstringSender ID returned by register_msisdn_sender. Required.
codestring5-digit PIN from the verification SMS. Required.

Example prompt

EXAMPLE PROMPT
"Confirm sender 5678 with PIN 12345."

Example response

RESPONSE
{ "sender_id": "5678", "status": "confirmed" }