platfone-com/mcp

Platfone provides virtual phone numbers for account verification, testing, and automation workflows. The Platfone MCP server enables AI agents to obtain temporary numbers and receive SMS messages from MCP-compatible clients like Claude, VS Code Copilot, Codex, etc.
📖 Docs · 🔧 Setup Guide · 🔑 Get API Key · 📦 npm
Why MCP?
Instead of manually integrating the API, AI agents can:
- Order numbers autonomously by country and service name
- Wait for SMS codes
- Retry or cancel activations
All via structured tool calls — no custom backend required.
Features
- **Full activation lifecycle** — from ordering a number to receiving SMS
- **ETag-cached catalog** — countries and services are cached in-memory with 5-minute TTL and ETag-based conditional refresh — never sent to the agent
- **Human-friendly inputs** — use "Israel" or "Telegram" instead of IDs; names are auto-resolved server-side
- **Dual transport** — stdio and http from a single codebase
- **API key auth** — works with your existing Platfone API key
Installation
See the full Installation Guide for detailed instructions.
Quick Start
**NPM:**
Agent Guidelines
- Always call check_price first to verify cost and availability
- Then call order_number to rent a number
- Call check_sms until SMS is received or expired
- Use retry_activation if no SMS arrives
- Use cancel_activation to release funds if no longer needed
Tools
| Tool | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| get_balance | Check account balance: total, reserved, and available funds. |
| check_price | Check pricing and availability for a country + service pair before ordering. |
| order_number | Order a virtual phone number. Accepts names ("Israel") or IDs ("il"). Returns activation_id + phone. |
| check_sms | Poll activation state. Returns SMS code when received, or current status with polling instructions. |
| retry_activation | Request another SMS on the same number. Free of charge. |
| cancel_activation | Cancel an active activation before SMS is received. Refunds reserved amount. |
> **Note:** Country and service catalogs are cached server-side and auto-resolved from human-readable names.
> The agent never receives the full catalog — only resolved IDs or disambiguation hints.
Typical AI Agent Flow
Optional steps:
- retry_activation — request another SMS on the same number (free)
- cancel_activation — cancel before SMS arrives (refunds balance)
Development
Read the full Development Guide for setup instructions and testing tips.