SMSZ MCP Server

SMSZ is available as a remote Model Context Protocol server. Point an AI assistant at it and you can buy a number, wait for the verification code and read it back in conversation — no code, nothing to install, nothing to run locally.

https://www.smsz.net/api/mcp

It is the same product as the REST API, addressed by an assistant instead of a program. The same API keys, the same scopes, the same rate limits, the same balance. A number bought through a tool call shows up in GET /v1/activations a second later, and vice versa.

Is this for me?

One warning, up front. Purchases spend real balance. There is no test mode and no sandbox: if an assistant calls buy_activation, money leaves the account. Read Spending safely before you connect a key that can buy.

1. Create a key. Sign in at smsz.net, open the account menu and choose API keys. Grant only the scopes the assistant needs — see Spending safely. The key is shown once.

2. Add the connector. Most clients want a URL and a header:

URL:     https://www.smsz.net/api/mcp
Header:  Authorization: Bearer smsz_live_9f2a1c4d_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

In Claude (desktop or web), that is Settings → Connectors → Add custom connector. In Claude Code:

claude mcp add --transport http smsz https://www.smsz.net/api/mcp \
  --header "Authorization: Bearer $SMSZ_API_KEY"

In Cursor, Windsurf and anything else reading mcp.json:

{
  "mcpServers": {
    "smsz": {
      "url": "https://www.smsz.net/api/mcp",
      "headers": { "Authorization": "Bearer smsz_live_9f2a1c4d_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

For a client that only speaks stdio, bridge it:

npx mcp-remote https://www.smsz.net/api/mcp \
  --header "Authorization: Bearer $SMSZ_API_KEY"

3. Check it. Ask the assistant to run check_connection. It costs nothing and reports which account the key belongs to and which scopes it carries. If that works, everything else will.

# The same check by hand
curl -s https://www.smsz.net/api/mcp \
  -H "Authorization: Bearer $SMSZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"check_connection","arguments":{}}}'

Four tools spend money: buy_activation, rent_number, extend_rental, and cancel_* in the sense that it moves balance back. Everything else is read-only. The safeguards, strongest first:

1. Scope the key. This is the real control, and the only one that does not depend on a model behaving well. A tool the key has no scope for is not merely refused — it is never shown to the assistant at all.

A key holding only the :read scopes can research prices and read codes all day and cannot spend a cent. Start there.

2. Keep the balance at what you are willing to lose. An assistant cannot top the account up — only you can, from the website. A low balance is a hard ceiling on any mistake.

3. Idempotency. Every purchase tool accepts an idempotency_key. If a call fails ambiguously and the assistant retries with the same key, it gets the original result back rather than a second number. The tool descriptions instruct the model to do this; it is worth checking that yours does.

4. Rate limits. Purchases are metered separately and much more tightly than reads — 20 per minute against 120 for everything else — so a runaway loop stops quickly.

Two things to know

• Message text is untrusted. Anyone who learns your number can text it, and that text goes into the assistant's context. A message could try to instruct the assistant. The server tells the model to treat message text as data and never as instructions, but if you are building an agent, do not let message content steer what it does next.
• Webhook secrets land in the transcript. create_webhook_endpoint returns the signing secret once. Through MCP, "once" means "in this conversation". If you share or export that transcript, delete the endpoint and register a new one.

What a well-behaved assistant does when you ask for a WhatsApp code:

1. list_services and list_countries — map "WhatsApp" and "the US" onto the exact slugs. 2. check_activation_prices — the live price and stock for that pair. available: 0 means the purchase would fail. 3. get_account — confirm the balance covers it. 4. It tells you the price and waits. 5. buy_activation with an idempotency_key — the number comes back immediately. 6. get_activation_messages every 10-15 seconds until the code arrives. Codes usually land in 30-90 seconds. 7. finish_activation once you confirm the code worked, releasing the number.

The prompts below encode exactly this, so you can invoke it as a single command rather than describing it each time.

Beyond tools, the server publishes reference material a client can pull into context. Reading a resource costs nothing and never touches a supplier.

The documentation resources are readable with any valid key. The catalogue and account resources follow the same scopes as the equivalent tools.

For anyone implementing a client by hand rather than using an SDK.

Why stateless. Nothing here needs continuity between calls: every request carries its own key, and every tool is a complete operation. The trade is that the server cannot push, so there are no listChanged notifications and no subscriptions — for push, use webhooks or poll list_events.

Browser clients must be allowlisted. Requests with no Origin header — which is every desktop, IDE and server-side client — are unaffected; a browser-based client on another domain is rejected with 403 unless its origin is configured. Get in touch if you need one added.

Errors follow the split the MCP specification asks for. A problem with the *request* — unknown method, unknown tool — comes back as a JSON-RPC error. A problem with the *call* — bad arguments, no stock, no balance, missing scope — comes back as a normal result with isError: true, carrying the same error code the REST API documents, so the assistant can read the reason and correct itself.

Rate limits, scopes, idempotency and error codes are shared with the REST API; the API documentation covers them in full. Base URL for the REST equivalent: https://www.smsz.net/api/v1.