Platfone - Receive SMS & Virtual Numbers MCP

oficial

Plataforma de números de telefone virtuais para agentes de IA — alugue números em mais de 200 países, receba SMS e gerencie todo o ciclo de vida da ativação.

GitHub

O que você pode fazer com Platfone Receive SMS & Virtual Numbers MCP?

Verificar saldo da conta — Peça à IA para consultar seus fundos totais, reservados e disponíveis usando get_balance.
Verificar custo e disponibilidade — Confira o preço e a disponibilidade de números para um par de país e serviço com check_price antes de fazer o pedido.
Solicitar um número virtual — Alugue um número de telefone temporário por país e nome de serviço via order_number para receber um ID de ativação e número de telefone.
Consultar SMS recebido — Verifique se um código SMS chegou para uma ativação usando check_sms, com status e orientações de consulta retornados.
Solicitar um novo SMS — Acione uma nova tentativa gratuita para receber outro SMS no mesmo número com retry_activation.
Cancelar e reembolsar — Libere uma ativação ativa e recupere os fundos reservados usando cancel_activation antes de receber um SMS.

Documentação

Servidor MCP Platfone

Platfone fornece números de telefone virtuais para verificação de contas, testes e fluxos de trabalho de automação. O servidor MCP Platfone permite que agentes de IA obtenham números temporários e recebam mensagens SMS de clientes compatíveis com MCP, como Claude, VS Code Copilot, Codex, etc.

📖 Documentação · 🔧 Guia de Configuração · 🔑 Obter Chave de API · 📦 npm

Por que MCP?

Em vez de integrar a API manualmente, os agentes de IA podem:

Solicitar números de forma autônoma por país e nome do serviço
Aguardar por códigos SMS
Tentar novamente ou cancelar ativações

Tudo por meio de chamadas de ferramentas estruturadas — sem necessidade de backend personalizado.

Funcionalidades

Ciclo de vida completo da ativação — desde a solicitação de um número até o recebimento do SMS
Catálogo com cache ETag — países e serviços são armazenados em cache na memória com TTL de 5 minutos e atualização condicional baseada em ETag — nunca enviados ao agente
Entradas amigáveis — use "Israel" ou "Telegram" em vez de IDs; os nomes são resolvidos automaticamente no lado do servidor
Transporte duplo — stdio e http a partir de uma única base de código
Autenticação por chave de API — funciona com sua chave de API Platfone existente

Instalação

Consulte o Guia de Instalação completo para instruções detalhadas.

Início Rápido

NPM:

PLATFONE_API_KEY=your_key npx @platfone/mcp

Diretrizes para Agentes

Sempre chame check_price primeiro para verificar custo e disponibilidade
Em seguida, chame order_number para alugar um número
Chame check_sms até que o SMS seja recebido ou expire
Use retry_activation se nenhum SMS chegar
Use cancel_activation para liberar fundos se não for mais necessário

Ferramentas

Ferramenta	Descrição
`get_balance`	Verificar saldo da conta: fundos totais, reservados e disponíveis.
`check_price`	Verificar preço e disponibilidade para um par país + serviço antes de solicitar.
`order_number`	Solicitar um número de telefone virtual. Aceita nomes ("Israel") ou IDs ("il"). Retorna `activation_id` + `phone`.
`check_sms`	Consultar estado da ativação. Retorna o código SMS quando recebido, ou o status atual com instruções de consulta.
`retry_activation`	Solicitar outro SMS no mesmo número. Gratuito.
`cancel_activation`	Cancelar uma ativação ativa antes que o SMS seja recebido. Reembolsa o valor reservado.

Nota: Os catálogos de países e serviços são armazenados em cache no lado do servidor e resolvidos automaticamente a partir de nomes legíveis. O agente nunca recebe o catálogo completo — apenas IDs resolvidos ou dicas de desambiguação.

Fluxo Típico do Agente de IA

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

Etapas opcionais:

retry_activation — solicitar outro SMS no mesmo número (grátis)
cancel_activation — cancelar antes que o SMS chegue (reembolsa o saldo)

Desenvolvimento

Leia o Guia de Desenvolvimento completo para instruções de configuração e dicas de teste.

Solução de Problemas

Erro	Solução
`UnauthorizedException`	Verifique se sua `PLATFONE_API_KEY` é válida
`PaymentRequiredException`	Recarregue seu saldo Platfone
`NoNumbersAvailableException`	Tente um país ou serviço diferente
`TooManyRequestsException`	Limite de taxa atingido — aguarde e tente novamente
`MaxPriceExceededException`	Tente novamente `order_number` com o `max_price` sugerido e o `order_id` retornado
`TooManyActivationsException`	Máximo de ativações ativas simultâneas atingido — cancele ou aguarde a expiração

Licença

Consulte LICENSE.md. Licenciado sob a Licença MIT.

O uso da API Platfone está sujeito aos Termos de Serviço e à Política de Privacidade.