Tools reference
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.
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
Example prompt
"Send 'Your verification code is 4815' from VERTEXSMS to +37069555555."
Example response
{
"message_id": "abc-123-...",
"status": "sent",
"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.
Look up the per-operator SMS rate for a country. Read-only. Server-side cached for one hour.
Required scope: sms:rates
Example prompt
"What does it cost to send an SMS to Lithuania?"
Example 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
}
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
Example prompt
"Validate these numbers as Lithuanian: 861860698, (370)-618-60698, 6186 0698."
Example 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 }
]
}
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
Example prompt
"Which operator does VertexSMS ID 493 correspond to?"
Example response
{
"operator_id": 493,
"name": "BITE",
"country": "LT",
"mcc": "246",
"mnc": ["020", "028"]
}
List MCC/MNC entries for a country, with their VertexSMS operator IDs. Read-only. Paginated.
Required scope: numbers:read
Example prompt
"List the mobile networks in Lithuania."
Example 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" }
]
}
List mobile number prefixes for a country, mapped to VertexSMS operator IDs. Read-only.
Required scope: numbers:read
Example prompt
"Which operator owns Lithuanian numbers starting with 3706000?"
Example response
{
"country": "LT",
"count": 2,
"prefixes": [
{ "prefix": "3706000", "country": "LT", "operator_id": "2536" },
{ "prefix": "3706001", "country": "LT", "operator_id": "2536" }
]
}
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
Example prompt
"Run an HLR lookup on +37069912345."
Example response
{
"msisdn": "37069912345",
"id": "1203877133",
"error_code": "0",
"imsi": "246021005160001",
"country": "LT",
"mcc": "246",
"mnc": "021",
"operator_id": null,
"ported": null
}
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
Example prompt
"Register 'ACMECORP' as a brand sender for our outgoing notifications."
Example response
{
"sender_id": "1234",
"status": "submitted"
}
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
Example prompt
"Register +37069555555 as a sender."
Example response
{
"sender_id": "5678",
"status": "pending_confirmation",
"next_step": "Call confirm_msisdn_sender with the 5-digit PIN delivered via SMS."
}
Confirm a pending MSISDN Sender ID by submitting the 5-digit PIN that VertexSMS sent to the registered phone number.
Required scope: sender:write
Example prompt
"Confirm sender 5678 with PIN 12345."
Example response
{
"sender_id": "5678",
"status": "confirmed"
}