Authentication

The MCP server supports two authentication paths. Pick the one that matches how you are calling it.

Bearer token (BYO)

For self-hosted clients, scripts, CI pipelines, and the standard config-file flow used by Claude Desktop, Cursor, and VS Code. You supply your VertexSMS API token directly via the Authorization header on every request:

Authorization: Bearer YOUR_VERTEXSMS_TOKEN

The MCP server forwards the token to the VertexSMS API. It is never stored, logged, or shared between sessions. Tokens scoped at the API level (per-IP whitelist, per-route permissions) keep their scope when used through MCP.

Get a token

Sign in to your VertexSMS account, open Settings → API in the dashboard, create a token with the routes you need (typically POST /sms and GET /rates), then paste it into your MCP client's config (see Quickstart).

Don't have an account yet? Request access through the contact form — registration is invite-only.

OAuth 2.1 (one-click connect)

For desktop and cloud MCP clients that support automatic OAuth discovery (Claude.ai, Claude Desktop with custom connectors, and others), the MCP server advertises an authorization server. The user clicks "Connect VertexSMS" inside the client, gets redirected to a VertexSMS consent screen, approves the requested scopes, and the client receives an access token automatically — no manual token paste.

Discovery happens via /.well-known/oauth-protected-resource per RFC 9728:

GET https://mcp.vertexsms.com/.well-known/oauth-protected-resource

{
  "resource": "https://mcp.vertexsms.com/mcp",
  "authorization_servers": ["https://tool.vertexsms.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": [
    "sms:send",
    "sms:rates",
    "sender:write",
    "hlr:lookup",
    "numbers:read"
  ]
}

Scopes

The MCP server defines five scopes. The consent screen shows the user a plain-language description of each one before they approve.

OAuth scopes

Scope

Description

Tools it covers

Scopesms:send

DescriptionSend SMS on your behalf.

Toolssend_sms

Scopesms:rates

DescriptionRead SMS rates.

Toolsget_sms_rates

Scopesender:write

DescriptionRegister and confirm Sender IDs on your account.

Toolsregister_sender_id, register_msisdn_sender, confirm_msisdn_sender

Scopehlr:lookup

DescriptionRun HLR lookups (billable per query).

Toolslookup_hlr

Scopenumbers:read

DescriptionRead mobile network metadata and validate phone numbers.

Toolsget_operator, get_mcc_mnc_list, get_mobile_prefixes, correct_phone_number

Granted scopes map directly to the underlying VertexSMS API permissions on the issued token. A token issued with only sms:rates will be rejected by the API for any non-rates request — no client-side enforcement, the API is the gatekeeper.

Revocation

OAuth tokens appear in your dashboard's Settings → API page alongside any manually-created bearer tokens, prefixed with oauth:access: and oauth:refresh:. Delete them at any time to revoke access; the connected MCP client will see a 401 on its next call and either re-prompt the user or fail loudly.

Authentication errors

When auth fails the MCP server responds with HTTP 401 and a structured error envelope:

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "A VertexSMS API token is required. ...",
    "retryable": false,
    "signup_url": "https://vertexsms.com/en/contact",
    "signin_url": "https://vertexsms.com/en/login",
    "token_url": "https://tool.vertexsms.com/settings/api"
  }
}

The WWW-Authenticate header includes the resource-metadata URL so OAuth-aware clients can auto-recover. See the full error catalog at Errors.