Infrastructure for AI agents that need real-world phone verification. One MCP server for one-time SMS verification, dedicated number rentals, and matching-country proxies, all from one prepaid balance. Paste one config and every major MCP client gets 40 tools.
Tested with 10 MCP clients
API key → paste config → ask your agent. Most setups finish in under two minutes.
Sign up free, open Settings, create a key, copy the token.
One JSON block for hosted HTTP, or pick your client below for local stdio.
"What’s my VirtualSMS balance?" is the fastest smoke test.
TL;DR
Account verification for agents: SMS, rentals, proxies and cloud browser, one prepaid balance. Carrier-issued numbers on real physical SIM cards, not VoIP.
Show full summary
VirtualSMS is an account verification platform for individuals, developers, and AI agents. It combines one-time SMS verification, dedicated number rentals, matching-country proxies, and private cloud browser sessions behind one API, one MCP server, and one prepaid balance. The numbers are carrier-issued mobile numbers, backed by real physical SIM cards on operators like Vodafone, O2 and T-Mobile, not VoIP, so they pass the line-type checks that reject VoIP at signup.
From one prepaid balance you can:
Most providers solve one piece of the verification workflow. VirtualSMS combines numbers, rentals, proxies and cloud browser sessions behind one API, SDKs and an MCP server, so you use only the pieces you need or combine them into one workflow.
Use the platform through a REST API, official SDKs for Node, Python, PHP, Ruby and .NET, a hosted MCP server, or automation tools like n8n.
VirtualSMS can be used by individuals manually, integrated into applications with SDKs and APIs, or driven by AI agents through MCP.
Use the hosted endpoint at
mcp.virtualsms.io
or install virtualsms-mcp
locally. Your agent gets 40 tools spanning verification, rentals and proxies, against live VirtualSMS infrastructure. Free, MIT-licensed, 2500+ services across 145+ countries, from $0.05 per code.
Building autonomous agents with x402 pay-per-call? See the agents guide for the USDC deposit flow that skips API-key signup entirely.
StreamableHTTP transport. No npm install. Paste the block, plug in your API key, ask your agent a question.
{
"mcpServers": {
"virtualsms": {
"type": "streamableHttp",
"url": "https://mcp.virtualsms.io/mcp",
"headers": { "x-api-key": "vsms_your_api_key_here" }
}
}
}
Replace vsms_your_api_key_here with a key from
Settings -> API Keys
or sign up free.
An agent runs the full loop in about 30 seconds.
hosted MCP at mcp.virtualsms.io/mcp, 40 tools ready.
“Get me a Telegram number for Thailand and wait for the code.”
find_cheapest
->
create_order
->
wait_for_sms
the OTP code. Total cost: ~$0.08, ~30 seconds.
Prefer running the server locally? Same 40 tools, same auth, just stdio instead of HTTP. Pick your client below.
Anthropic's flagship desktop client
Config file
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json{
"mcpServers": {
"virtualsms": {
"command": "npx",
"args": ["-y", "virtualsms-mcp"],
"env": {
"VIRTUALSMS_API_KEY": "your_key_here"
}
}
}
}Restart Claude Desktop after saving. The virtualsms server appears in the MCP tool list.
Replace your_key_here with a key from
Settings -> API Keys
or sign up free.
Agent 7 tools built for agent workflows, not REST wrappers
| Tool | What it does | When to use |
|---|---|---|
list_services
virtualsms_list_services
|
Every verification service VirtualSMS supports, across 2500+ services and 145+ countries. Optional search filter. | First call when picking a service from a long list. |
list_countries
virtualsms_list_countries
|
Every country with real physical SIM numbers available. Optional service filter. | When picking a country before creating an order. |
get_price
virtualsms_get_price
|
Live price and availability for a service plus country pair. | When validating cost before placing an order. |
find_cheapest
Agent
virtualsms_find_cheapest
|
Cheapest countries for a service right now, sorted by price, with real stock counts. | When the agent should auto-pick by price. |
search_services
Agent
virtualsms_search_services
|
Natural-language service lookup. "telega" finds Telegram. | When the user gives an ambiguous service name. |
get_balance
virtualsms_get_balance
|
Account balance in USD. | When confirming spend headroom before bulk orders. |
get_profile
virtualsms_get_profile
|
Email, Telegram link, balance, lifetime spend, total orders, active API keys. | When the agent needs account context. |
get_stats
virtualsms_get_stats
|
Orders, success rate, spend, and status/service/country breakdown. | For dashboards or weekly reporting. |
get_transactions
virtualsms_get_transactions
|
Transaction history with type, date range, and pagination filters. | For audit, reconciliation, or expense reports. |
create_order
virtualsms_create_order
|
Buy a number for a service plus country. Returns order_id and phone_number. | When the user asks for a verification number. |
get_sms
virtualsms_get_sms
|
Poll an order for the code. Extracts the verification code automatically. | For batch or cron jobs that manage their own polling. |
wait_for_sms
Agent
virtualsms_wait_for_sms
|
Block until the SMS lands on an existing order_id, or until timeout. WebSocket-backed, so no polling loop. | Default for interactive agent flows. |
get_order
virtualsms_get_order
|
Full order detail plus every message received on the number. | When debugging or auditing a specific order. |
list_orders
virtualsms_list_orders
|
Your active orders. Essential for crash recovery. | When the agent needs live state of in-flight orders. |
order_history
virtualsms_order_history
|
Past orders with status, service, country, and date filters. | When the user asks about past activity. |
cancel_order
virtualsms_cancel_order
|
Cancel and refund, if no SMS arrived. 120s cooldown after purchase. | When the SMS times out. |
cancel_all_orders
virtualsms_cancel_all_orders
|
Bulk-cancel every active order. Refunds where eligible. | For end-of-session cleanup across many orders. |
swap_number
Agent
virtualsms_swap_number
|
Swap for a new number, same service and country, no extra charge. 120s cooldown. | When the current number is flagged or rate-limited. |
list_services
Every verification service VirtualSMS supports, across 2500+ services and 145+ countries. Optional search filter.
When: First call when picking a service from a long list.
list_countries
Every country with real physical SIM numbers available. Optional service filter.
When: When picking a country before creating an order.
get_price
Live price and availability for a service plus country pair.
When: When validating cost before placing an order.
find_cheapest
Agent
Cheapest countries for a service right now, sorted by price, with real stock counts.
When: When the agent should auto-pick by price.
search_services
Agent
Natural-language service lookup. "telega" finds Telegram.
When: When the user gives an ambiguous service name.
get_balance
Account balance in USD.
When: When confirming spend headroom before bulk orders.
get_profile
Email, Telegram link, balance, lifetime spend, total orders, active API keys.
When: When the agent needs account context.
get_stats
Orders, success rate, spend, and status/service/country breakdown.
When: For dashboards or weekly reporting.
get_transactions
Transaction history with type, date range, and pagination filters.
When: For audit, reconciliation, or expense reports.
create_order
Buy a number for a service plus country. Returns order_id and phone_number.
When: When the user asks for a verification number.
get_sms
Poll an order for the code. Extracts the verification code automatically.
When: For batch or cron jobs that manage their own polling.
wait_for_sms
Agent
Block until the SMS lands on an existing order_id, or until timeout. WebSocket-backed, so no polling loop.
When: Default for interactive agent flows.
get_order
Full order detail plus every message received on the number.
When: When debugging or auditing a specific order.
list_orders
Your active orders. Essential for crash recovery.
When: When the agent needs live state of in-flight orders.
order_history
Past orders with status, service, country, and date filters.
When: When the user asks about past activity.
cancel_order
Cancel and refund, if no SMS arrived. 120s cooldown after purchase.
When: When the SMS times out.
cancel_all_orders
Bulk-cancel every active order. Refunds where eligible.
When: For end-of-session cleanup across many orders.
swap_number
Agent
Swap for a new number, same service and country, no extra charge. 120s cooldown.
When: When the current number is flagged or rate-limited.
| Tool | What it does | When to use |
|---|---|---|
rentals_pricing
virtualsms_rentals_pricing
|
Full Access pricing tiers: durations and prices. | When quoting a rental before committing spend. |
rentals_available
virtualsms_rentals_available
|
Countries with rental stock, counts, and pricing, per tier. | First call when renting. Confirms real stock. |
rentals_services
virtualsms_rentals_services
|
Services available for Platform-tier rental in a country, with stock and price. | When the rental must be locked to one service. |
rentals_price
virtualsms_rentals_price
|
Retail price for a service, country, and duration combination. | When pricing an exact rental configuration. |
create_rental
virtualsms_create_rental
|
Rent a number. Check availability and price first. | When the user needs one number for days, not one code. |
list_rentals
virtualsms_list_rentals
|
Your rentals across both tiers, filterable by status. | When the agent needs live state of active rentals. |
get_rental
virtualsms_get_rental
|
Full detail for one rental: tier, number, service lock, status, expiry, SMS. | When reading messages on a rented number. |
extend_rental
virtualsms_extend_rental
|
Extend an active rental. Charges the current catalog price. | When a rental is about to expire and is still in use. |
cancel_rental
virtualsms_cancel_rental
|
Full refund, within 20 minutes of purchase and before any SMS. | When a rental was bought by mistake. |
rentals_pricing
Full Access pricing tiers: durations and prices.
When: When quoting a rental before committing spend.
rentals_available
Countries with rental stock, counts, and pricing, per tier.
When: First call when renting. Confirms real stock.
rentals_services
Services available for Platform-tier rental in a country, with stock and price.
When: When the rental must be locked to one service.
rentals_price
Retail price for a service, country, and duration combination.
When: When pricing an exact rental configuration.
create_rental
Rent a number. Check availability and price first.
When: When the user needs one number for days, not one code.
list_rentals
Your rentals across both tiers, filterable by status.
When: When the agent needs live state of active rentals.
get_rental
Full detail for one rental: tier, number, service lock, status, expiry, SMS.
When: When reading messages on a rented number.
extend_rental
Extend an active rental. Charges the current catalog price.
When: When a rental is about to expire and is still in use.
cancel_rental
Full refund, within 20 minutes of purchase and before any SMS.
When: When a rental was bought by mistake.
| Tool | What it does | When to use |
|---|---|---|
list_proxy_catalog
virtualsms_list_proxy_catalog
|
Pool types, countries, and price per GB. Pools sold: datacenter, residential, mobile. | First call when buying a proxy. |
list_proxy_locations
virtualsms_list_proxy_locations
|
Cities, states, ASNs, or ZIPs for a pool type plus country. No purchase required. | When planning geo-targeting before spending. |
buy_proxy
virtualsms_buy_proxy
|
Purchase proxy traffic in GB. Returns credentials and remaining balance. | When the agent needs an IP in the number's country. |
list_proxies
virtualsms_list_proxies
|
Your proxies with remaining GB and credentials. Returns proxy_id values. | When reusing a proxy you already own. |
generate_proxy_endpoint
Agent
virtualsms_generate_proxy_endpoint
|
Build a ready-to-use connection string: country, state, city, ZIP or ASN targeting, rotating or sticky, HTTP or SOCKS5. | When wiring a proxy into a browser or HTTP client. |
rotate_proxy
virtualsms_rotate_proxy
|
Request a fresh exit IP for an existing proxy. | When the current exit IP gets blocked. |
test_proxy
virtualsms_test_proxy
|
Prove a proxy works. Reports exit IP, country, city, ISP, and latency. | Before trusting a proxy in a real signup flow. |
get_proxy_usage
virtualsms_get_proxy_usage
|
Cached GB used and remaining, plus request count, for one proxy. | When checking headroom before a long run. |
get_proxy_usage_history
virtualsms_get_proxy_usage_history
|
Per-day traffic and request series over the last 7 or 30 days. | For usage reporting and cost attribution. |
set_proxy_targeting
virtualsms_set_proxy_targeting
|
Persist a default geo-targeting on a proxy sub-user. | When every request from a sub-user should share one geo. |
list_proxy_catalog
Pool types, countries, and price per GB. Pools sold: datacenter, residential, mobile.
When: First call when buying a proxy.
list_proxy_locations
Cities, states, ASNs, or ZIPs for a pool type plus country. No purchase required.
When: When planning geo-targeting before spending.
buy_proxy
Purchase proxy traffic in GB. Returns credentials and remaining balance.
When: When the agent needs an IP in the number's country.
list_proxies
Your proxies with remaining GB and credentials. Returns proxy_id values.
When: When reusing a proxy you already own.
generate_proxy_endpoint
Agent
Build a ready-to-use connection string: country, state, city, ZIP or ASN targeting, rotating or sticky, HTTP or SOCKS5.
When: When wiring a proxy into a browser or HTTP client.
rotate_proxy
Request a fresh exit IP for an existing proxy.
When: When the current exit IP gets blocked.
test_proxy
Prove a proxy works. Reports exit IP, country, city, ISP, and latency.
When: Before trusting a proxy in a real signup flow.
get_proxy_usage
Cached GB used and remaining, plus request count, for one proxy.
When: When checking headroom before a long run.
get_proxy_usage_history
Per-day traffic and request series over the last 7 or 30 days.
When: For usage reporting and cost attribution.
set_proxy_targeting
Persist a default geo-targeting on a proxy sub-user.
When: When every request from a sub-user should share one geo.
| Tool | What it does | When to use |
|---|---|---|
retry_order
virtualsms_retry_order
|
Ask for the SMS to be resent to the same number. Not all order types support it. | When the code never arrived but the number is still good. |
check_number
Agent
virtualsms_check_number
|
Carrier and line-type lookup for any E.164 number: mobile, landline or VoIP, plus spam risk. No API key required. | When screening a number before you trust it. |
start_manual_registration_session
Agent
beta
virtualsms_start_manual_registration_session
|
Private cloud browser sessions (beta, invite-only). Start a country-matched cloud browser and drive it yourself in a live viewer. Join for beta access and updates. | When a signup needs a guided browser session you drive yourself. |
retry_order
Ask for the SMS to be resent to the same number. Not all order types support it.
When: When the code never arrived but the number is still good.
check_number
Agent
Carrier and line-type lookup for any E.164 number: mobile, landline or VoIP, plus spam risk. No API key required.
When: When screening a number before you trust it.
start_manual_registration_session
Agent
beta
Private cloud browser sessions (beta, invite-only). Start a country-matched cloud browser and drive it yourself in a live viewer. Join for beta access and updates.
When: When a signup needs a guided browser session you drive yourself.
When to pick which: use
wait_for_sms for interactive flows; use
get_sms for batch or cron jobs.
Same prompts work in Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw, Codex, Hermes, Cline, Zed, and Continue.dev.
virtualsms-mcp on npm - install with npx, auto-updated on each agent restart.
npmjs.com/package/virtualsms-mcp ›Source on GitHub. Read, fork, vendor, or open a PR. Bearer API key over TLS; 120 req/min default.
github.com/virtualsms-io/mcp-server ›MCP calls hit the same backend that powers the VirtualSMS dashboard and SDKs. No new stack, no experimental path.
MCP clients
One npx virtualsms-mcp package, same config block in every client below.
Listed on MCP directories
Dedicated inventory plus a carrier-vetted global supplier network, exposed to your agents directly through MCP.
The numbers are carrier-issued mobile numbers, backed by real physical SIM cards, not VoIP. WhatsApp, Telegram, Google and Discord accept them. VoIP pools do not pass their line-type checks.
40 tools across four jobs. Verification, rentals, proxies and utilities in one server. find_cheapest, search_services, swap_number and wait_for_sms are built for agent workflows, not REST-wrapped dashboards.
Keep a number by the day: Full Access rentals run 1, 7 or 30 days for a number that works across any service; Platform rentals run 1, 3 or 7 days locked to one service. Both refund in full within 20 minutes of purchase and before the first SMS. And a matching-country proxy from the same balance keeps the number and the IP in agreement. One MCP server, the whole verification stack.
find_cheapest service=whatsapp is guessable. create_order service=telegram country=gb max_price=1.00 reads itself. Agents call them correctly on the first try.
No MCP premium. Tool calls bill the same as every other surface. Swap to the REST API or SDK at any time with zero data migration.
Private cloud browser sessions (beta, invite-only). Start a country-matched cloud browser and drive it yourself in a live viewer. Join for beta access and updates .
FAQ
Account verification infrastructure is the stack that gets a real account through a signup flow that demands a phone number. It has five layers, and a gap in any one fails the whole chain: a carrier-issued mobile number, the SMS code readable by software, a proxy IP in the same country as the number, a clean browser to drive the signup, and the automation that runs the chain end to end. Most providers sell the first two layers and leave you to source the rest, which is exactly where the number, the IP and the browser stop telling the same story. VirtualSMS provides the infrastructure behind all five.
Two tool calls. create_order buys a number for a given service and country and returns an order_id. wait_for_sms then blocks on that order_id and returns the moment the code arrives, pushed over WebSocket, typically in 2 to 15 seconds. The agent never polls, never sleeps in a loop, and never needs a human to read a phone. If you would rather drive your own loop, get_sms polls a single order.
MCP (Model Context Protocol) is an open spec by Anthropic that lets AI agents call external tools securely. VirtualSMS ships a signed npm package, virtualsms-mcp, that exposes 40 tools for verification, rentals and proxies to any MCP-compatible agent (18 activation & account | 9 rentals | 10 proxy | 3 other). The agent asks your question, the MCP server talks to our API, and verification codes land back in chat.
Claude Desktop, Claude Code (CLI), Cursor, Windsurf, OpenClaw, Codex (OpenAI CLI), Hermes, Cline (VS Code), Zed, Continue.dev, and any other client that implements the Model Context Protocol stdio transport. The same config block works everywhere (Codex uses TOML, the rest use JSON).
Yes. ChatGPT supports MCP via Developer Mode custom connectors (hosted MCP, streamable-HTTP/SSE, plan-gated to Plus/Pro/Business/Enterprise). Add https://mcp.virtualsms.io/mcp as a connector. The REST API is also available.
One step: npm install -g virtualsms-mcp (or let npx install it on first use). That's it. The AI client spawns the server with npx. You never run it manually.
No. Tool calls bill identically to REST API or dashboard usage. Verifications start at $0.05. The MCP server itself is free and MIT-licensed.
Verification codes and metadata are retained for 7 days so get_sms and get_order stay idempotent, then auto-purged. Codes are never shared, sold, or indexed. Cancel an order and the record is purged immediately.
Yes. The MCP server is MIT-licensed and the VirtualSMS API terms permit commercial use. Resellers and agent-platform operators are common.
120 requests per minute per API key by default. That handles every normal interactive-agent workflow. Need more? Email support. We raise limits for production accounts.
Same API under the hood. MCP is just the right surface for AI agents: tool descriptions, typed inputs, streaming results. Use the SDK when you want imperative code, use MCP when the caller is an AI.
40 tools spanning verification, rentals and proxies (18 activation & account | 9 rentals | 10 proxy | 3 other). Private cloud browser sessions via start_manual_registration_session are beta and invite-only - join https://t.me/VirtualSMS_io for access. Setting VIRTUALSMS_ENABLE_SESSIONS=1 exposes 3 more browser-session tools. The count is derived from the tool registry, not typed into the page.
Both stdio (local Node install) and StreamableHTTP (zero-install hosted at https://mcp.virtualsms.io/mcp). MCP 0.1+ spec. Pick whichever fits your workflow.
Paste the config, create a free API key, ask for a balance, done.
MIT-licensed · 120 req/min · Same price as REST API
Run a blog, tool list, or Telegram channel? Earn up to 15% lifetime commission.
Become an affiliate
