{
  "markdown": "# Platfone MCP Server\n\n[![npm version](https://img.shields.io/npm/v/@platfone/mcp)](https://www.npmjs.com/package/@platfone/mcp)\n[![npm downloads](https://img.shields.io/npm/dw/@platfone/mcp)](https://www.npmjs.com/package/@platfone/mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Smithery](https://smithery.ai/badge/dima-p0g6/platfone)](https://smithery.ai/server/dima-p0g6/platfone)\n\n[Platfone](https://platfone.com) 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.\n\n📖 [Docs](https://platfone.com/docs/mcp/) · 🔧 [Setup Guide](https://platfone.com/docs/mcp/setup/) · 🔑 [Get API Key](https://platfone.com/app/api) · 📦 [npm](https://www.npmjs.com/package/@platfone/mcp)\n\n\n## Why MCP?\n\nInstead of manually integrating the API, AI agents can:\n\n- Order numbers autonomously by country and service name\n- Wait for SMS codes\n- Retry or cancel activations\n\nAll via structured tool calls — no custom backend required.\n\n## Features\n\n- **Full activation lifecycle** — from ordering a number to receiving SMS\n- **ETag-cached catalog** — countries and services are cached in-memory with 5-minute TTL and ETag-based conditional refresh — never sent to the agent\n- **Human-friendly inputs** — use \"Israel\" or \"Telegram\" instead of IDs; names are auto-resolved server-side\n- **Dual transport** — `stdio` and `http` from a single codebase\n- **API key auth** — works with your existing Platfone API key\n\n## Installation\n\nSee the full [Installation Guide](https://platfone.com/docs/mcp/setup) for detailed instructions.\n\n### Quick Start\n\n**NPM:**\n\n```bash\nPLATFONE_API_KEY=your_key npx @platfone/mcp\n```\n\n## Agent Guidelines\n\n- Always call `check_price` first to verify cost and availability\n- Then call `order_number` to rent a number\n- Call `check_sms` until SMS is received or expired\n- Use `retry_activation` if no SMS arrives\n- Use `cancel_activation` to release funds if no longer needed\n\n## Tools\n\n| Tool                | Description                                                                                               |\n| ------------------- | --------------------------------------------------------------------------------------------------------- |\n| `get_balance`       | Check account balance: total, reserved, and available funds.                                              |\n| `check_price`       | Check pricing and availability for a country + service pair before ordering.                              |\n| `order_number`      | Order a virtual phone number. Accepts names (\"Israel\") or IDs (\"il\"). Returns `activation_id` + `phone`. |\n| `check_sms`         | Poll activation state. Returns SMS code when received, or current status with polling instructions.       |\n| `retry_activation`  | Request another SMS on the same number. Free of charge.                                                   |\n| `cancel_activation` | Cancel an active activation before SMS is received. Refunds reserved amount.                              |\n\n> **Note:** Country and service catalogs are cached server-side and auto-resolved from human-readable names.\n> The agent never receives the full catalog — only resolved IDs or disambiguation hints.\n\n### Typical AI Agent Flow\n\n```\n1. check_price         (country: \"Israel\", service: \"Telegram\")  → verify cost & availability\n2. order_number        (country: \"Israel\", service: \"Telegram\")  → returns activation_id + phone\n3. check_sms           (activation_id)                            → poll or check once for SMS\n```\n\nOptional steps:\n- `retry_activation` — request another SMS on the same number (free)\n- `cancel_activation` — cancel before SMS arrives (refunds balance)\n\n## Development\n\nRead the full [Development Guide](docs/DEVELOPMENT.md) for setup instructions and testing tips.\n\n\n## Troubleshooting\n\n| Error                         | Solution                                                                    |\n| ----------------------------- | --------------------------------------------------------------------------- |\n| `UnauthorizedException`       | Check your `PLATFONE_API_KEY` is valid                                      |\n| `PaymentRequiredException`    | Top up your Platfone balance                                                |\n| `NoNumbersAvailableException` | Try a different country or service                                          |\n| `TooManyRequestsException`    | Rate limited — wait and retry                                               |\n| `MaxPriceExceededException`   | Retry `order_number` with the suggested `max_price` and returned `order_id` |\n| `TooManyActivationsException` | Max concurrent active activations reached — cancel or wait for expiry       |\n\n## License\n\nSee [LICENSE.md](./LICENSE.md). Licensed under the MIT License.\n\nUse of the Platfone API is subject to [Terms of Service](https://platfone.com/compliance#terms) and [Privacy Policy](https://platfone.com/compliance#privacy).\n",
  "bytes": 5165,
  "sha": "c10094a0a1167fdc150524a7d9134db71cceb96f5e84be7371981a5bcc18c222",
  "repo_slug": "platfone-com/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_platfone_com_platfone_9f8b3c1d/readme"
}