--- type: FAQ title: "VirtualSMS MCP Server for AI Agents: Claude, Cursor, Codex" description: "MCP server that lets AI agents verify accounts end to end: SMS codes, number rentals and matching-country proxies. 40 tools, 2500+ services, 145+ countries." resource: "https://virtualsms.io/mcp" tags: ["mcp"] updated: "2026-10-23T06:24:14.545Z" generated: at: "2026-10-23T06:22:46.012Z" by: "virtualsms-marketing-site" --- # SMS verification for AI agents MCP server that lets AI agents verify accounts end to end: SMS codes, number rentals and matching-country proxies. 40 tools, 2500+ services, 145+ countries. MCP Server · 40 tools · SMS, rentals, proxies 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. [Copy config](#install) [Create free API key](https://virtualsms.io/signup) [GitHub](https://github.com/virtualsms-io/mcp-server) Published 2026-06-05 Updated 2026-07-18 $ connect https://mcp.virtualsms.io/mcp { "status": "connected", "transport": "streamableHttp", "tools": 40 } > create_order service=telegram country=TH { "number": "+66812345678", "order_id": "ord_8f3k2", "cost": 0.08 } > wait_for_sms { order_id: ord_8f3k2 } { "status": "received", "code": "847291", "elapsed": "23s" } Tested with 10 MCP clients [Claude Desktop](https://virtualsms.io/mcp/claude-skill)[Claude Code](https://virtualsms.io/mcp/claude-skill)[Cursor](https://virtualsms.io/mcp/cursor-rules)[Windsurf](https://virtualsms.io/mcp/windsurf-workflow)[OpenClaw](https://virtualsms.io/mcp/openclaw-skill)[Codex](https://virtualsms.io/mcp/codex-config)[Hermes](https://virtualsms.io/mcp/hermes-mcp)[Cline](#setup)[Zed](#setup)[Continue](#setup) 40 tools 2500 + services 145 + countries from $0.05 Real SIMs, not VoIP Matching-country proxies ## Connected in three steps API key → paste config → ask your agent. Most setups finish in under two minutes. ### Create an API key Sign up free, open Settings, create a key, copy the token. ### Paste the MCP config One JSON block for hosted HTTP, or pick your client below for local stdio. ### Restart and verify "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 Hide 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: - receive one-time SMS verification codes from $0.05 - rent dedicated numbers for 1 to 30 days - buy matching-country residential, mobile and datacenter proxies - launch private cloud browser sessions that work alongside your number and proxy (beta) 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. Recommended ## Quick install: hosted MCP server StreamableHTTP transport. No npm install. Paste the block, plug in your API key, ask your agent a question. Open Standard Model Context Protocol by Anthropic Real Physical SIM Carrier networks, not VoIP Zero Install Hosted at mcp.virtualsms.io json { "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 . ## What this looks like in practice An agent runs the full loop in about 30 seconds. - 01 Connect hosted MCP at mcp.virtualsms.io/mcp , 40 tools ready. - 02 Ask “Get me a Telegram number for Thailand and wait for the code.” - 03 Tools find_cheapest -> create_order -> wait_for_sms - 04 Returns the OTP code. Total cost: ~$0.08 , ~30 seconds . Alternative ## Local install (npm) Prefer running the server locally? Same 40 tools, same auth, just stdio instead of HTTP. Pick your client below. ### Claude Desktop SMS verification Anthropic's flagship desktop client Config file macOS `~/Library/Application Support/Claude/claude_desktop_config.json` Windows `%APPDATA%\Claude\claude_desktop_config.json` Linux `~/.config/Claude/claude_desktop_config.json` 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. [Full Claude Skill guide](https://virtualsms.io/mcp/claude-skill) Standalone repo: github.com/virtualsms-io/claude-skill-sms-verification Replace your_key_here with a key from Settings -> API Keys or sign up free . ## 40 MCP tools, grouped by job 18 activation 9 rentals 10 proxy 3 other Agent 7 tools built for agent workflows, not REST wrappers Activation & Account 18 tools | 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. Rentals 9 tools | 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. Proxy 10 tools | 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. Other 3 tools | 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. ## Talk to your agent naturally Same prompts work in Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw, Codex, Hermes, Cline, Zed, and Continue.dev. Balance & account - What's my VirtualSMS balance? - Show my last 10 activations and total spend this month. - Pull my VirtualSMS profile: tier, referral code, created_at. Pricing & research - Which country has the cheapest WhatsApp verification right now? - Compare Telegram verification price across UK, Germany and Poland. - Find me the cheapest country for Discord verification under $0.80. Ordering - Buy me a German number for WhatsApp verification. - Order a US Telegram number under $1 and wait for the SMS code. - Grab 5 UK numbers for Instagram, one per account. - Rent me a British number for 7 days. - Buy a UK proxy to match my UK number, then give me the connection string. Operations - Cancel every VirtualSMS order older than 15 minutes. - Swap my current Telegram number, the last one got rate-limited. - Show all my active orders with the numbers and services. Developer workflows - Write a Python script that orders a US WhatsApp number and polls for the code using virtualsms-mcp. - I built this integration against sms-activate. Here's the code. Rewrite it to call VirtualSMS tools via MCP. ## Production-ready infrastructure ### Published on npm virtualsms-mcp on npm - install with npx, auto-updated on each agent restart. [npmjs.com/package/virtualsms-mcp ›](https://www.npmjs.com/package/virtualsms-mcp) ### Open source, MIT-licensed Source on GitHub. Read, fork, vendor, or open a PR. Bearer API key over TLS; no general per-key rate limit. [github.com/virtualsms-io/mcp-server ›](https://github.com/virtualsms-io/mcp-server) ### Same infra as the REST API MCP calls hit the same backend that powers the VirtualSMS dashboard and SDKs. No new stack, no experimental path. MCP clients ## Tested with 10 clients One npx virtualsms-mcp package, same config block in every client below. [Claude Desktop](https://virtualsms.io/mcp/claude-skill)[Claude Code](https://virtualsms.io/mcp/claude-skill)[Cursor](https://virtualsms.io/mcp/cursor-rules)[Windsurf](https://virtualsms.io/mcp/windsurf-workflow)[OpenClaw](https://virtualsms.io/mcp/openclaw-skill)[Codex](https://virtualsms.io/mcp/codex-config)[Hermes](https://virtualsms.io/mcp/hermes-mcp)[Cline](#setup)[Zed](#setup)[Continue](#setup) Listed on MCP directories [Glama MCP server](https://glama.ai/mcp/servers/virtualsms-io/mcp-server)[Smithery MCP install](https://smithery.ai/servers/virtualsms/virtualsms-mcp)[npm v1.3.1](https://www.npmjs.com/package/virtualsms-mcp) ## What makes VirtualSMS MCP different Dedicated inventory plus a carrier-vetted global supplier network, exposed to your agents directly through MCP. Real physical SIM cards, not VoIP 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 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. Rentals and matching-country proxies on the same account 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. Typed inputs and named tools that read like English 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. Same $0.05+ activation price as the REST API 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) 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 ## Frequently asked questions What is account verification infrastructure? 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. How do AI agents receive OTP codes automatically? 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. What is MCP and how does VirtualSMS use it? 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. Which AI assistants support the VirtualSMS MCP server? 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). Does this work with ChatGPT? 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. Do I need to install anything locally? 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. Does using MCP cost extra? 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. Is SMS content logged? 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. Can I use this in commercial agent products? Yes. The MCP server is MIT-licensed and the VirtualSMS API terms permit commercial use. Resellers and agent-platform operators are common. What's the rate limit on MCP tool calls? There is no general per-API-key rate limit. A small number of narrow, IP-based limits apply to specific write actions (account auth and order creation) — that handles every normal interactive-agent workflow. How is the MCP server different from your REST API or SDKs? 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. How many tools does VirtualSMS MCP expose? 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. Which MCP transport and spec version do you support? 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. ## Connect your agent in under two minutes Paste the config, create a free API key, ask for a balance, done. [Copy MCP config](#install) [Create free account](https://virtualsms.io/signup) MIT-licensed · No general per-key rate limit · Same price as REST API Run a blog, tool list, or Telegram channel? Earn up to 15% lifetime commission. [Become an affiliate](https://virtualsms.io/affiliate)