sv-number MCP: Phone Numbers as Tools for an Agent

sv-number is an MCP server that turns phone numbers into nine callable tools. An agent orders a private number in the country a service expects, the server waits for the SMS, pulls the code out of the message, and returns it; the activation is then closed, cancelled, or asked for one more code. It speaks stdio, so any Model Context Protocol client — Claude Code, Codex, Cursor, Claude Desktop, or a framework that hosts its own tools — loads it with a single config entry.

It is a thin layer over a commercial SMS-activation API, and the README is unusually explicit about the part most tools hide: the account has to be funded, and the numbers are for receiving one verification code, not for holding a conversation.

The nine tools

Tool	What it answers with
get_balance	What is left on the account, since ordering needs credit.
list_countries	Every country with its numeric id and the operators available there.
list_services	Look up a site by name or domain: the service code, price, how many numbers are online, and the share of codes that actually arrived.
order_number	A private number for one service in one country.
wait_for_code	Polls until the SMS lands and returns the parsed code.
finish_activation	Closes a successful activation — the step that should follow every success.
cancel_activation	Cancels when nothing arrives; the money goes back to the balance.
request_another_sms	One more code on the same number, for a re-send or a password reset.
totp_code	Computes an authenticator code locally, RFC 6238, when the second factor is TOTP rather than SMS.

Service codes are arbitrary and cannot be guessed from the site name: uk is Airbnb, re is Coinbase, tn is LinkedIn. The server handles that by search rather than by memory — list_services takes a domain and ranks whole-word matches above substrings, so discord.com finds Discord and x puts X.com above unrelated names that merely contain the letter.

Wiring it in

Install is one line for a CLI client, or one object in any JSON config that MCP clients read:

{
  "mcpServers": {
    "sv-number": {
      "command": "npx",
      "args": ["-y", "sv-number-mcp"],
      "env": { "SVN_API_KEY": "your_key_here" }
    }
  }
}

The key comes from the service's own profile page after signup, and it is read from the environment — no tool returns it and no error message quotes it. Three other settings are worth knowing: SVN_LANG (default en) also decides the currency of the prices, SVN_POLL_SECONDS (default 4) is the polling interval, and SVN_API_BASE points at the activation handler if you ever need to move it.

What the server does on your behalf

• Keeps the language on every call. The API answers without it, but then it prices in another currency, so the field is never left out.
• Turns markers into sentences. The API sometimes replies with a bare token instead of JSON; NO_NUMBERS arrives as "change country, or set operator to any", which is something an agent can act on.
• Polls politely and knows when to stop. wait_for_code fires at a sane interval instead of hammering the status endpoint, and gives up at the 20 minute life of a number.
• Prefers the delivery rate over the price. Where a service and country pair has statistics, deliveredPercent is the better signal than cost; where it is null — the common case — the size of the live pool is the fallback.

Where a typed decision fits

Tools like this are the point at which the site's own subject shows up: the calls are cheap and the choices are boring until the wrong one costs you a number, a balance, or a locked account.

• Picking a country and a service is a choice question. Options are the shortlist from list_services; the tie-breakers are delivery rate, live pool and price — a decision you can declare once instead of re-reasoning in prose on every order. See the routing pattern.
• "Did this number fail, or is the SMS just late?" is a noul question. It is the retry-versus-cancel branch, and the three-way answer is what keeps an agent from burning balance re-ordering when the honest answer is "not enough evidence yet".
• "Should this service be automated at all?" is a guardrail. A calibrated yes/no belongs in front of the order call — it is the same shape as any other policy check in an agent loop, and cheaper than discovering the answer from a ban.

The reason to put the decision in code rather than in a prompt is the same one that applies everywhere else on this site: the answer becomes a value with a probability, the threshold stays in your program, and nothing has to be parsed back out of a paragraph.

What it is not

• Receiving is the whole job. These numbers do not send SMS, do not take calls, and are not intended for banking, payment or government accounts. An agent that needs a permanent number for a conversation wants a carrier product.
• No free tier. Ordering requires a funded balance, so this is a paid tool in an agent stack, not a dev toy.
• The catalogue is not identical everywhere. A service available in one country may be missing in another, and the fallback code for "not on list" only receives SMS from senders outside the list — it is a safety net, not a wildcard.
• Not affiliated with this site. It is one project in the wider agent-tooling ecosystem; the numbers quoted here come from its README, read on September 21, 2026.

Last updated: 2026-09-21 · sources & corrections