# MCP server — Tools reference


Source: https://vertexsms.com/en/mcp/tools

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`

| Field | Type | Description |
|-------|------|-------------|
| to | string | Recipient phone number in E.164 format. Required. |
| from | string | Sender ID (max 11 alphanumeric chars) or registered phone number. Required. |
| message | string | Message body. Long messages are split into multi-part SMS automatically. Required. |
| priority | enum | `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 | `0` = GSM-7, `1` = 8-bit, `2` = UCS-2. |
| expireIn | int | Message expiry in seconds (360 – 432000). |

Example prompt: `"Send 'Your verification code is 4815' from VERTEXSMS to +37069555555."`

Example response:

```json
{
  "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 the REST API errors.

## get_sms_rates

Look up per-operator SMS rate for a country. Read-only. Server-side cached for one hour.

Required scope: `sms:rates`

| Field | Type | Description |
|-------|------|-------------|
| country | string | ISO 3166-1 alpha-2 code, e.g. `LT`, `US`, `DE`. Required. |

Example prompt: `"What does it cost to send an SMS to Lithuania?"`

Example response:

```json
{
  "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
}
```

## 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`

| Field | Type | Description |
|-------|------|-------------|
| numbers | array | Array of `{ number, country }` objects. `country` is ISO 3166-1 alpha-2. Required. |

Example prompt: `"Validate these numbers as Lithuanian: 861860698, (370)-618-60698, 6186 0698."`

Example response:

```json
{
  "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`

| Field | Type | Description |
|-------|------|-------------|
| operator_id | string \| int | Internal VertexSMS operator identifier (e.g. `493`). Required. |

Example prompt: `"Which operator does VertexSMS ID 493 correspond to?"`

Example response:

```json
{
  "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`

| Field | Type | Description |
|-------|------|-------------|
| country | string | ISO 3166-1 alpha-2 country code. Required. |
| page | int | Optional 1-based page number. |

Example prompt: `"List the mobile networks in Lithuania."`

Example response:

```json
{
  "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`

| Field | Type | Description |
|-------|------|-------------|
| country | string | ISO 3166-1 alpha-2 country code. Required. |

Example prompt: `"Which operator owns Lithuanian numbers starting with 3706000?"`

Example response:

```json
{
  "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 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`

| Field | Type | Description |
|-------|------|-------------|
| msisdn | string | International subscriber number, e.g. `37069912345`. Required. |

Example prompt: `"Run an HLR lookup on +37069912345."`

Example response:

```json
{
  "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. 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`

| 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: `"Register 'ACMECORP' as a brand sender for our outgoing notifications."`

Example response:

```json
{
  "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`

| Field | Type | Description |
|-------|------|-------------|
| msisdn | string | Mobile number in E.164 format without leading `+`, e.g. `37069555555`. Required. |

Example prompt: `"Register +37069555555 as a sender."`

Example response:

```json
{
  "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 sent to the registered phone number.

Required scope: `sender:write`

| Field | Type | Description |
|-------|------|-------------|
| sender_id | string | Sender ID returned by `register_msisdn_sender`. Required. |
| code | string | 5-digit PIN from the verification SMS. Required. |

Example prompt: `"Confirm sender 5678 with PIN 12345."`

Example response:

```json
{
  "sender_id": "5678",
  "status": "confirmed"
}
```