Çoğu çevrimiçi hizmet tarayıcılar için inşa edildi. Bir kullanıcı, oturum çerezi ile kimlik doğrulanmış bir sayfanın önünde oturur, düğmelere tıklar, alanlara yazı yazar ve arka uç bu iş akışını baştan sona varsayar. Yapay zeka ajanları bu kalıba uymaz — tarayıcı oturumları, tıklanacak bir DOM'ları, QR kodu tarayacak bir kameraları ve OAuth danslarına sabırları yoktur. Ajanlar için inşa etmek; kimlik doğrulama, ödeme ve teslimat katmanlarını farklı varsayımlar etrafında yeniden inşa etmek demektir.
Bu yazı, Roamzy MCP sunucusunun arkasındaki mimari kararları adım adım anlatıyor. Gerçek ticaret sistemleriyle etkileşime giren yapay zeka ajanları geliştiren geliştiricilere ve "ajana hazır" bir API'nin üretimde gerçekte nasıl göründüğünü merak eden diğer hizmetlerdeki mühendislere yöneliktir.
MCP sunucusu ince bir sarmalayıcıdır
MCP sunucusunun kendisi küçüktür — yaklaşık 400 satır TypeScript, esbuild aracılığıyla 100KB'lık bir tarball'a paketlenmiştir. Yalnızca iki protokol arasında çeviri yapmak için vardır: Claude Desktop / Cursor / Continue'dan gelen stdio tabanlı MCP istekleri ve https://roamzy.io/api/v1/* adresine yapılan HTTPS REST çağrıları.
MCP sunucusunda hiçbir iş mantığı yoktur. Harcama limitleri, token doğrulama, ödeme doğrulama — bunların tümü, izole olarak test edilebilen, merkezi olarak denetlenebilen ve her ajan kullanıcısını MCP sunucusunu güncellemeye zorlamadan değiştirilebilen arka uçta yaşar. MCP sunucusu yalnızca protokol köprüsüdür.
Bu, doğru sınırdır. İş mantığını MCP sunucusuna koymak, onu N+1 yere (sunucu + her istemcinin kurulu tarball'ı) bölerdi, yükseltme gecikmesi getirirdi ve kullanıcının dizüstü bilgisayarında saldırı yüzeyi oluştururdu. MCP sunucusunu saf HTTP istemci yapıştırıcısı olarak tutarak, kolayca denetlenebilen (güvenliğe önem veren bir kullanıcı için yaklaşık 30 dakika) ve aynı URL'deki tarball'ı yeniden yayınlayarak basitçe güncellenebilen ince bir katman elde ediyoruz.
Token'lar SHA-256 ile özetlenir, bir kez gösterilir
Token formatı Stripe tarzında rk_live_<32-char-base64url> şeklindedir. Önek sabittir, böylece GitHub Secret Scanning ve benzeri araçlar sızıntıları tespit edebilir. Gövde, base64url olarak kodlanmış 24 rastgele bayttan oluşur ve 192 bit entropi sağlar.
Oluşturma sırasında düz metin, kullanıcıya sarı bir uyarı kutusunda tam olarak bir kez gösterilir. Sunucu yalnızca SHA-256 özetini saklar. Birden fazla token aktif olduğunda kullanıcının hangi token'ın hangisi olduğunu tanımlayabilmesi için görüntüleme amacıyla 12 karakterlik bir önek ipucu (rk_live_abc1) tutulur.
Karşılaştırma, zamanlama saldırılarını etkisiz kılmak için Node'un timingSafeEqual fonksiyonunu kullanır. Token iptali, denetim izinin korunması için yumuşak silme olarak (revoked_at ayarlanarak) uygulanır. İptal anındadır; iptal edilmiş bir token ile yapılan bir sonraki API çağrısı milisaniyeler içinde 401 döndürür.
Beş katmanlı harcama savunması
Token tabanlı sistemlerin çoğunda bir veya iki harcama limiti vardır. Bizde beş tane var, her biri farklı bir hata durumunu ele alıyor:
- Token başına günlük limit (varsayılan 50 $ USDT, 1-1000 $ arası yapılandırılabilir). Yuvarlanan 24 saatlik harcama üst sınırı.
- Token başına aylık limit (varsayılan 500 $, 1-10000 $ arası yapılandırılabilir). Yuvarlanan 30 günlük harcama üst sınırı.
- Bekleme süresi — token oluşturulduktan sonraki ilk 7 günde, günlük limitten bağımsız olarak toplam harcama 50 $ USDT ile sınırlandırılır. Sabit kodlanmıştır; artırılamaz. Bu, bir token oluşturulduktan hemen sonra sızarsa (bir geliştirici yanlışlıkla onu herkese açık bir gist'e yapıştırırsa) etki alanını sınırlar.
- Büyük işlem eşiği (varsayılan 200 $) — bunun üzerindeki satın almalar, insan kullanıcının panelde manuel onayını gerektirir. API
big_txn_needs_confirmationdöndürür ve ajan bunu kullanıcıya iletmelidir. - Satın alma kapsamı tercihi — varsayılan olarak, token oluşturulurken "Satın almalara izin ver" kutusu işaretsizdir; bu da token'ın yalnızca okuma uç noktalarını çağırabileceği anlamına gelir. Kullanıcının bilinçli olarak tercih etmesi gerekir. Yalnızca kataloğu sorgulaması gereken bir ajan için bu, en güvenli yapılandırmadır.
Sayaçlar, tembel pencere döndürmesiyle api_tokens tablosunda yaşar: bir istek sayacı okuduğunda, depolanan pencere (günlük için YYYY-MM-DD, aylık için YYYY-MM) mevcut olanla eşleşmezse, sayaç sıfır olarak kabul edilir. Bu, günlük bir cron işinden kaçınır ve makine saati kaymasına toleranslıdır.
Uygulama iki kez gerçekleşir. Sipariş oluşturma anında, sunucu bir yumuşak kontrol yapar: tutar + bugün harcanan, günlük limiti aşar mı? Evetse, istek kararlı bir hata koduyla ve kalan-pay ipucuyla reddedilir. Ödeme webhook'u anında ise sayaç sert bir şekilde artırılır — yalnızca gerçek USDT fiilen alındığında.
Ödeme bütünlüğü — HMAC ve benzersizlik kısıtlamaları
En önemli sahtekarlık önleme katmanı, NowPayments webhook'unda HMAC-SHA-512 doğrulamasıdır. Paylaşılan gizli anahtar (IPN_SECRET) sunucu ortamında yaşar. Her webhook yükü bir x-nowpayments-sig başlığıyla gelir; sunucu, ham istek gövdesi üzerinden HMAC hesaplar ve karşılaştırır. Gizli anahtar olmadan, bir saldırgan "ödendi" yükünü taklit edemez — sipariş kimliğini ve niyet kimliğini bilse bile (muhtemelen biliyorlardır, çünkü bunlar sipariş yanıtında döndürülür).
İkinci katman, defter tablosundaki (ref_type, ref_id) üzerinde DB düzeyinde bir BENZERSİZ kısıtlamadır. Her kredi, ref_type="nowpayments" ve ref_id=<payment_id> ile yazılır. Webhook aynı payment_id için iki kez tetiklenirse (ağ yeniden denemesi, tekrar saldırısı), ikinci ekleme benzersizlik kısıtlamasında başarısız olur ve uygulama alreadyApplied=true ile kısa devre yapar. Çift kredi mümkün değildir.
Üçüncü katman mimaridir: yalnızca services/billing.ts fonksiyonları eSIM bakiyesini değiştirebilir. Keyfi olarak bakiye eklemek için bir yönetici uç noktası yoktur; "eSIM'i manuel olarak etkinleştir" yönetici aracı bile aynı kredi yolundan geçer. Bu, saldırı yüzeyini en aza indirir — bakiyenin artabileceği tam olarak bir kod yolu vardır ve bu, tüm güvenlik kontrollerine sahip olandır.
Olay müdahalesi için üç acil durdurma düğmesi
Bazı şeyler ters gidecektir. Token'lar sızar. Bir kullanıcının ajanı bozulur ve siparişlere spam yapar. Bir ödeme sağlayıcısında kesinti olur. Müdahalenin orantılı olabilmesi için üç bağımsız acil durdurma düğmesi inşa ettik:
- Token başına iptal — kullanıcı panelde İptal'e tıklar. Yalnızca o token'ı etkiler. Bir ajan yaramazlık yaptığında veya bir token sızdığında kullanılır.
- Kullanıcı başına ajan engelleme — yönetici, bir gerekçeyle
POST /api/admin/users/:id/agent-blockçağrısını yapar. O kullanıcının tüm token'larını etkiler. Bireysel hesap kötüye kullanımı veya ele geçirilmesi için kullanılır. - Küresel ajan duraklatma — yönetici
POST /api/admin/agents/pauseçağrısını yapar. Tüm kullanıcılardaki her Bearer token 503 döndürür. Altyapı olayları veya güvenlik soruşturmaları için kullanılır.
Durum, ajanlara GET /api/v1/status adresinde görünür (kimlik doğrulama yok, CORS *). İyi davranan ajanlar satın almalardan önce bunu yoklar ve purchases_paused veya agents_paused doğru olduğunda geri çekilir. Roamzy, durum uç noktasını yok sayan ajanları kısıtlama hakkını saklı tutar.
Daha ince taneli bir duraklatma da vardır: agents.purchases.paused yalnızca POST /orders'ı engeller ve okuma uç noktalarını canlı bırakır. Bilgilendirici API çağrılarını karartmadan ödeme tarafındaki bir sorunu araştırırken kullanışlıdır.
Birincil etkinleştirme yüzeyi LPA değil, QR'dır
Çoğu ajan akışı, eSIM'in bulunduğu yerden farklı bir cihazda çalışır. Ajan, bir Mac'te Claude Desktop olabilirken, eSIM'in kullanıcının iPhone'una inmesi gerekir. Bu cihazlar arası durumda QR doğru yüzeydir: API qr_image_url (qrserver.com oluşturucu aracılığıyla bir PNG URL'si) döndürür, ajan bunu sohbete satır içi yerleştirir ve kullanıcı telefonunun kamerasıyla tarar.
lpa_url alanı da döndürülür, ancak yalnızca ajan ve hedef cihaz aynı olduğunda kullanışlıdır — örneğin kullanıcının iPhone'unda çalışan bir ajan. iOS 17.4+ ve Android 14+ üzerinde, bir lpa: URL'sine dokunmak sistem eSIM kurulumunu doğrudan açar. Ancak çoğu ajan kullanıcı deneyimi için QR daha güvenilirdir.
Bu küçük bir tasarım kararıdır ama önemlidir: birçok MCP sunucusu, kullanıcının ajanın yanında oturduğu ve bir bağlantıya dokunacağı bir "tarayıcı sekmesi" zihniyetiyle yazılmıştır. Tüketici eSIM kullanımının gerçeği ise cihazlar arasıdır.
Neden fiat değil de USDT
Kripto ödemeleri, her zaman bariz olmayan üç nedenden dolayı ajan yereldir:
- Kart depolama uyumluluğu yok. Kart bilgilerini saklamak, PCI DSS Seviye 1 uyumluluğunu ve kart sahibinin her işlemi nasıl kimlik doğrulaması gerektiğine dair kart ağı kurallarını gerektirir. Bu kuralların çoğu, klavyenin başında bir insanın olduğunu varsayar. Kripto, bu rejimin tamamını atlar.
- Ters ibraz riski yok. Bir USDT işlemi zincir üzerinde onaylandığında, kesindir. "Kart sahibi bu işleme altı ay sonra itiraz etti" diye bir yol yoktur. Bu, tarayıcı ticaretinden çok ajan ticareti için önemlidir, çünkü harcamayı gerçek zamanlı olarak inceleyip onaylayan insan kullanıcı olmayabilir.
- Mutabakat netliği. Ajan bütçesi USDT cinsindendir. Kullanıcı cüzdanı USDT tutar. Satıcı USDT ile mutabakat yapar. Aradan fiat dönüşümü, döviz kuru maruziyeti veya banka saatleri gecikmesi yoktur. Tüm akış baştan sona API biçimlidir.
Bu, hedef pazarı daraltır — kripto yerlisi olmayan çoğu gezgin USDT ile eSIM satın almaz. Ancak bunu yapan kesim için (kripto yerlisi gezginler, ajan güdümlü akışlar, seyahati otomatikleştiren geliştiriciler) bir sürü sürtünmeyi ortadan kaldırır.
İnşa etmediklerimiz (ve nedenleri)
OAuth tarzı kapsamlı token'lar. Ayrıntılı bir kapsam listesi yerine tek bir izin bayrağımız (satın al / satın alma) var. Mantık şu: 2026'daki ajanlar henüz "yalnızca bakiye oku" veya "yalnızca eSIM oku" ayrımına ihtiyaç duymuyor. Daha sonra ihtiyaç duyarlarsa, kapsamlar ekleyeceğiz. Erken kapsam modelleri, önledikleri kadar çok hata yaratır.
Anonim, ajan öncelikli kayıt. Ajan şu anda anında bir Roamzy kullanıcısı oluşturamaz; insanın token vermek için bir kez tarayıcıda oturum açması gerekir. Bu bir sürtünmedir. Bunu ajan öncelikli akış (anonim kullanıcı oluşturma + sihirli bağlantı talebi) olarak yapılacaklar listemizde tutuyoruz, ancak inşa etmeden önce trafik verisini bekliyoruz. Potansiyel kullanıcıların %50'si "hesap oluştur" aşamasında vazgeçiyorsa, bu optimize etmeye değer bir sinyaldir; %5 ise değildir.
Ajan olayları için webhook teslimatı. Şu anda ajan, durum güncellemeleri için GET /orders/:id yoklar. İtme tabanlı bir webhook, ölçekte daha verimli olurdu, ancak karmaşıklık ekler (ajanın bir uç nokta barındırması, imza doğrulaması, yeniden deneme politikası gerekir). 10 dakikalık bir USDT onay penceresinde 5 saniyelik aralıklarla yoklama yapmak 120 istek demektir — ucuzdur.
Kendiniz deneyin
Bir yapay zeka ajanı geliştiriyorsanız ve eSIM satın almalarını entegre etmek istiyorsanız, en hızlı yol MCP sunucusudur. Claude Desktop'a 60 saniyede kurun — rehbere bakın. MCP olmayan istemciler için tam OpenAPI 3.0 spesifikasyonu /api/v1/openapi.json adresinde, etkileşimli Swagger arayüzü /api/v1/docs adresinde ve uzun biçimli ajan rehberi /llms-full.txt adresindedir.
Daha derin sorular için Telegram destek botu @roamzy_support_bot adresindedir.