Skip to main content
Glama
Platfone MCP - Receive SMS & Virtual Numbers

Platfone MCP - Receive SMS & Virtual Numbers

by platfone-com

Platfone MCP Server

npm version npm downloads License: MIT Smithery

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.

Related MCP server: agentline-mcp

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:

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 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. Licensed under the MIT License.

Use of the Platfone API is subject to Terms of Service and Privacy Policy.

Available Tools

6 tools
cancel_activationCancel ActivationA
Destructive
Inspect

Cancel a Platfone activation and release the phone number. Allowed when activation_status is "active", sms_status is "smsRequested", and the cancelable_after timestamp has passed. If cancelable_after is null, cancellation is not supported.

Inputs: activation_id (required).

check_priceCheck PriceA
Read-onlyIdempotent
Inspect

Check pricing for a country + service pair before ordering. Returns min, max, and suggested price, average quality score, and number of available phone numbers. Use this before order_number to verify cost and availability. Accepts country and service as human-readable names or IDs.

Inputs: country (required), service (required), max_price.

check_smsCheck SMSA
Read-onlyIdempotent
Inspect

Retrieve the current state of a Platfone activation: SMS text, parsed code, status, and expiration. Can be used to poll periodically or check once on demand.

Inputs: activation_id (required).

get_balanceGet BalanceA
Read-onlyIdempotent
Inspect

Returns the current Platfone account balance: total available funds and the amount reserved by active orders. All values are in USD cents. Use this after a 402 error to inform the user how much they need to top up.

Inputs: no named parameters.

order_numberOrder NumberAInspect

Rent a virtual phone number via the Platfone API for the given country and service category. Returns phone number, activation_id, resolved country & service names, price, expiry time, retriable flag, and whether/when the activation can be canceled. Accepts country and service as human-readable names or IDs — names are auto-resolved from the cached catalog. Use check_price first to verify cost and availability. Use check_sms with the activation_id to poll for incoming SMS. Only received messages are billed. IMPORTANT: Only call this tool once per order. Never call it multiple times in parallel — duplicate orders will be rejected.

Inputs: country (required), service (required), max_price, quality_factor.

retry_activationRetry ActivationAInspect

Request an additional SMS on the same Platfone number. Overwrites the previous SMS data with the next message. Free of charge. Only possible when sms_status is "smsReceived" or "retryReceived", activation_status is "active", and is_retriable is true. After calling, poll check_sms every 5 seconds until sms_status becomes "retryReceived" or the activation expires.

Inputs: activation_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: cancel activation, check price, check SMS, get balance, order number, and retry activation. No overlap in functionality.

    Naming Consistency5/5

    All tools follow the snake_case verb_noun pattern (e.g., cancel_activation, check_price), which is consistent and predictable.

    Tool Count5/5

    With 6 tools, the set is well-scoped for the domain of receiving SMS via virtual numbers, covering ordering, checking, retrying, canceling, and balance/price queries.

    Completeness4/5

    Core lifecycle operations are present, but missing an explicit tool to list supported countries/services. However, the tools accept names directly, reducing the gap.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for provisioning dedicated real-SIM US phone numbers, receiving inbound SMS, and extracting OTP codes. Built for AI agents automating phone verification workflows.
      12
      134 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Gives AI agents phone numbers, email, SMS, and voice calls as MCP tools, enabling them to provision numbers, capture 2FA codes, send messages, and make calls.
      15
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connect AI agents to Wavix's communications platform to send SMS, make and manage voice calls, run 2FA flows, and access speech analytics, phone number management, and SIP infrastructure.
      5
      MIT