# Platfone Com Mcp

> MCP server for virtual phone number verification - SMS activations for AI agents via Claude, Cursor, VS Code Copilot and more...

- **Type:** MCP server
- **Install:** `agentstack add mcp-platfone-com-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [platfone-com](https://agentstack.voostack.com/s/platfone-com)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [platfone-com](https://github.com/platfone-com)
- **Source:** https://github.com/platfone-com/mcp
- **Website:** https://platfone.com/docs/mcp/

## Install

```sh
agentstack add mcp-platfone-com-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Platfone MCP Server

[](https://www.npmjs.com/package/@platfone/mcp)
[](https://www.npmjs.com/package/@platfone/mcp)
[](https://opensource.org/licenses/MIT)
[](https://smithery.ai/server/dima-p0g6/platfone)

[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.

📖 [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)

## 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](https://platfone.com/docs/mcp/setup) for detailed instructions.

### Quick Start

**NPM:**

```bash
PLATFONE_API_KEY=your_key npx @platfone/mcp
```

## 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

```
1. check_price         (country: "Israel", service: "Telegram")  → verify cost & availability
2. order_number        (country: "Israel", service: "Telegram")  → returns activation_id + phone
3. check_sms           (activation_id)                            → poll or check once for SMS
```

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](docs/DEVELOPMENT.md) for setup instructions and testing tips.

## Troubleshooting

| Error                         | Solution                                                                    |
| ----------------------------- | --------------------------------------------------------------------------- |
| `UnauthorizedException`       | Check your `PLATFONE_API_KEY` is valid                                      |
| `PaymentRequiredException`    | Top up your Platfone balance                                                |
| `NoNumbersAvailableException` | Try a different country or service                                          |
| `TooManyRequestsException`    | Rate limited — wait and retry                                               |
| `MaxPriceExceededException`   | Retry `order_number` with the suggested `max_price` and returned `order_id` |
| `TooManyActivationsException` | Max concurrent active activations reached — cancel or wait for expiry       |

## License

See [LICENSE.md](./LICENSE.md). Licensed under the MIT License.

Use of the Platfone API is subject to [Terms of Service](https://platfone.com/compliance#terms) and [Privacy Policy](https://platfone.com/compliance#privacy).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [platfone-com](https://github.com/platfone-com)
- **Source:** [platfone-com/mcp](https://github.com/platfone-com/mcp)
- **License:** MIT
- **Homepage:** https://platfone.com/docs/mcp/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-platfone-com-mcp
- Seller: https://agentstack.voostack.com/s/platfone-com
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.