# MCP server — Authentication


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

The MCP server supports two authentication paths.

## Bearer token (BYO)

For self-hosted clients, scripts, CI pipelines, and the standard config-file flow used by Claude Desktop, Cursor, and VS Code. Supply your VertexSMS API token 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](https://vertexsms.com/en/contact) — 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 — no manual token paste.

Discovery happens via `/.well-known/oauth-protected-resource` per [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728):

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

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

| Scope | Description | Tools it covers |
|-------|-------------|-----------------|
| sms:send | Send SMS on your behalf. | send_sms |
| sms:rates | Read SMS rates. | get_sms_rates |
| sender:write | Register and confirm Sender IDs on your account. | register_sender_id, register_msisdn_sender, confirm_msisdn_sender |
| hlr:lookup | Run HLR lookups (billable per query). | lookup_hlr |
| numbers:read | Read mobile network metadata and validate phone numbers. | get_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` is 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 to revoke access; the connected MCP client sees a 401 on its next call and either re-prompts the user or fails loudly.

## Authentication errors

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

```json
{
  "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 in the Errors section.