A parte mais difícil do comércio com agentes é que a maioria dos produtos nunca foi concebida para agentes. Os fluxos de cartão em ficheiro pressupõem que há um humano a apertar os olhos perante um ecrã de faturação. As aplicações de eSIM pressupõem um telemóvel com a câmara pronta a digitalizar um código QR. A Stripe pressupõe uma página de checkout associada a um cookie de sessão, que um servidor MCP não consegue fornecer.
A Roamzy foi reconstruída a partir da camada da API para baixo, de modo a eliminar esses pressupostos. O resultado é uma instalação de cinco minutos que permite ao Claude Desktop consultar, estimar e (com a sua autorização explícita) comprar um eSIM global em USDT — e um modelo de segurança explícito que limita o raio de impacto de um token comprometido.
Com o que vai ficar no final
Depois deste tutorial:
- Claude Desktop com oito ferramentas Roamzy registadas (catálogo, detalhe de país, estimativa, estado, além de ferramentas de leitura autenticadas para os seus próprios eSIMs e encomendas)
- Um token de API na sua configuração do Claude que permite ao agente atuar em seu nome, limitado por predefinição a apenas leitura
- A possibilidade de ativar compras alterando uma única variável de ambiente quando estiver pronto
Tempo total: cerca de 60 segundos de instalação e 4 minutos a pedir ao Claude que faça coisas interessantes.
Passo 1: Crie um token de API no painel da Roamzy
Inicie sessão em roamzy.io/dashboard com o Google ou o Telegram. Abra Definições → API e Agentes. Clique em Criar novo token.
O texto simples do token aparece uma única vez — copie-o de imediato para um gestor de palavras-passe. O servidor nunca armazena o texto simples depois de este ecrã fechar; guarda um hash SHA-256 para verificação e uma sugestão de prefixo de 12 caracteres (rk_live_abc1…) para exibição.
Deixe a caixa Permitir compras desmarcada na sua primeira instalação. Os tokens de apenas leitura não podem gastar USDT — só conseguem consultar catálogos e verificar o estado. Esta é a predefinição correta. Pode sempre criar mais tarde um segundo token com o âmbito de compra ativado.
Passo 2: Encontre o ficheiro de configuração do Claude Desktop
No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
No Windows: %APPDATA%\Claude\claude_desktop_config.json
Se o ficheiro ainda não existir, crie-o. É JSON simples.
Passo 3: Adicione o servidor MCP da Roamzy
{
"mcpServers": {
"roamzy": {
"command": "npx",
"args": ["-y", "https://roamzy.io/mcp/roamzy-mcp-latest.tgz"],
"env": {
"ROAMZY_API_TOKEN": "rk_live_xxx",
"ROAMZY_ENABLE_PURCHASE": "false"
}
}
}
}
Substitua rk_live_xxx pelo seu token real. O comando npx irá descarregar o tarball diretamente do nosso domínio — não são necessárias credenciais do GitHub nem do NPM.
Se já tiver outros servidores MCP configurados, integre a chave roamzy no seu objeto mcpServers existente, em vez de substituir o ficheiro inteiro.
Passo 4: Reinicie o Claude Desktop
Encerre o Claude Desktop por completo (Cmd-Q no Mac, não basta fechar a janela) e volte a abri-lo. Ao arrancar, o Claude lê o ficheiro de configuração uma vez e inicia cada servidor MCP como um subprocesso.
Deverá ver as ferramentas Roamzy surgir no menu de ferramentas (o pequeno ícone no canto inferior direito da área de introdução de texto). Se não aparecerem no espaço de dez segundos, verifique o registo do Claude Desktop em busca de erros — normalmente trata-se de um erro de escrita na configuração JSON ou de um token incorreto.
Passo 5: Peça algo interessante ao Claude
Experimente este pedido:
Vou voar para Tóquio na próxima semana numa viagem de 10 dias. Quanto me vai custar um eSIM através da Roamzy se prever usar cerca de 2 GB no total?
O que o Claude faz nos bastidores:
- Chama
roamzy_country_detail(country_slug="esim-japan")para confirmar que o Japão tem cobertura e obter a tarifa atual por MB. - Chama
roamzy_estimate(country_slug="esim-japan", mb_estimated=2048)para projetar o custo em USDT. - Devolve uma resposta concisa com o custo projetado e o carregamento mínimo.
Para 2 GB no Japão à nossa tarifa atual de $0.0033/MB, o custo projetado ronda os $7 USDT. O carregamento mínimo na Roamzy é de $20, por isso o Claude dir-lhe-á que carregue pelo menos $20 para ficar com margem.
Ativar compras (quando estiver pronto)
Para permitir que o Claude compre efetivamente um eSIM em vez de apenas o estimar, têm de ser verdadeiras duas condições:
- O token tem de ter o âmbito de compra ativado. Edite o token no painel ou revogue-o e crie um novo com a caixa Permitir compras marcada.
- A configuração do servidor MCP tem de ter
ROAMZY_ENABLE_PURCHASE: "true". Esta é uma opção separada do âmbito do token — mesmo com um token com compras ativadas, o servidor MCP não disponibilizará ferramentas de compra a menos que esta variável de ambiente esteja definida. Defesa em profundidade contra erros de escrita na configuração.
Quando ambas forem verdadeiras, reinicie o Claude Desktop e experimente:
Compra-me um eSIM da Roamzy para a viagem a Tóquio com um carregamento de $20.
O Claude irá chamar roamzy_create_order, que gasta a partir do orçamento diário do token (predefinição de $50). A API devolve um URL de pagamento em USDT — o Claude partilha-o consigo, você paga a partir da sua carteira, o webhook confirma, e o Claude pode então obter o URL da imagem do QR para a apresentar no chat. Digitalize com a câmara do telemóvel e o eSIM instala-se.
O modelo de segurança num parágrafo
Cinco camadas protegem-no de um agente descontrolado. Limites de gasto diário e mensal por token (predefinição de $50/dia, $500/mês, configuráveis até $1000/$10000). Um período de arrefecimento de 7 dias com um gasto total de $50 em cada novo token, não aumentável. Confirmação de transações grandes: qualquer valor acima de $200 USDT é bloqueado ao nível da API e exige que você confirme no painel. O âmbito de compra é opcional por token. E existem três interruptores de emergência independentes: revogação por token, bloqueio de agente por utilizador e pausa global de agentes, com o estado visível em /api/v1/status.
Para mais detalhe, consulte /llms-full.txt — a orientação em formato longo que publicamos especificamente para agentes e motores de IA.
E quanto a outros clientes de IA?
O Cursor, o Continue, o Cline, o Windsurf e qualquer outro cliente compatível com MCP usam o mesmo bloco de configuração — basta colocá-lo no respetivo ficheiro de configuração. Para clientes que não usam MCP (LangChain, function calling da OpenAI, n8n, scripts Python personalizados), chame a API REST diretamente em /api/v1/docs. Mesmo token, mesmo modelo de segurança.
É este o tutorial completo. Se ficar bloqueado, o bot de apoio da Roamzy no Telegram está em @roamzy_support_bot.