MCP gelen kutusu: yapay zeka ajanı kendi kaydını doğrulasın

Bir ajanın REST API'de bulamadığı şey nedir?

Bu sitede bir REST API vardır ve onu kendi koduna entegre eden bir yazılımcı için sorun çıkmaz. Bir ajan için çıkar: referans sayfasını açıp üç uç noktadan hangisini istediğine karar veremez, doğru sorgu dizesiyle bir isteği elle yazamaz. Onun yerine sunucuya ne yapabileceğini sorar, makine tarafından okunabilir şemalar alır ve bunlardan birini çağırır.

Bu yüzden hizmetin yaptığı her şey ikinci kez, araçlar olarak da sunulur. Altı tanedirler ve çağrılar arasında yönetilecek bir durum yoktur:

Sunucu ayrıca initialize çağrısını kısa bir talimat paragrafıyla yanıtlar; çoğu istemci bunu doğrudan modele iletir. Böylece bir ajan, kimse bunu bir prompt'a yazmadan, bu hizmetin ne işe yaradığını ve tek gerçek uyarısının ne olduğunu zaten bilerek işe başlar.

Bir istemci tek satırda nasıl bağlanır?

Uç nokta tek bir URL'dir ve genel alan adları için kaydolunacak hiçbir şey yoktur. Her MCP istemcisi aynı biçimde bir yapılandırma alır — Claude Desktop, Claude Code, Cursor, Continue, OpenAI Agents SDK ve protokolü konuşan her şey:

{"mcpServers":{"grabmail":{"url":"https://grabmail.io/mcp"}}}

Taşıma katmanı Streamable HTTP'dir: JSON-RPC 2.0 taşıyan tek bir POST, tek bir JSON yanıt, açık tutulan bir akış yok. Dolayısıyla her şeyi, herhangi bir ajan işin içine girmeden önce bir terminalden kontrol edebilirsiniz:

curl -sX POST https://grabmail.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Bir insana sormadan önce sunucuyu arayan istemciler, alan adında aynı uç noktayı ve taşımasını tanımlayan /.well-known/mcp.json dosyasını bulur.

Kayıt akışının tamamı dört araç çağrısıyla nasıl tamamlanır?

Neredeyse her ajanın ihtiyaç duyduğu sıra budur, başka bir şey yoktur:

1. Önce create_inbox aracını çağırın. Karşılığında bir adres, bir takma ad, alan adı ve ikisinden hangisinin verileceğini söyleyen bir not gelir. Hiçbir şey oluşturulmadı — posta kutusu, içine ilk mesaj düştüğünde var olmaya başlar.
2. Takma adı forma yazın. Kaydolunan hizmet, posta kutusuna ulaşan ama onu okumak için kullanılamayan, çalışan bir adres almış olur.
3. Adresle birlikte wait_for_message aracını çağırın. Bir zamanlayıcıyla değil, gönderir gönderilmez. Çağrı bekletilir; ajanın kendi yazması gereken bir döngüde yoklama yapılmaz.
4. Kodu mesajın içinden okuyun. Bekleme çağrısı gövdenin tamamını da döndürür, bu yüzden genellikle ikinci bir çağrıya hiç gerek kalmaz — read_message yalnızca daha önce gelmiş bir şey için gereklidir.

wait_for_message posta gelmeden neden döner?

Bir ajanı işler kılan araç budur, ve davranışı insanları şaşırtan da odur — bu yüzden bir dakikayı hak ediyor. Bir çağrı şöyle görünür:

curl -sX POST https://grabmail.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":
        {"name":"wait_for_message",
         "arguments":{"address":"demo.5kuqarzuch@grabmail.io",
                       "subject_contains":"code"}}}'

En fazla 25 saniye bekletir. O zamana kadar hiçbir şey gelmediyse başarısız olmaz — sade bir yanıtla döner ve yeniden çağrılmasını ister:

{
  "timed_out": true,
  "waited_seconds": 25,
  "message": null,
  "note": "Nothing arrived yet. Call wait_for_message again ..."
}

Neden bir üst sınır var

Beklemenin her saniyesi, uyumaktan başka bir şey yapmayan bir sunucu işçisidir ve bunlardan sabit sayıda vardır. Beş dakika sürebilecek bir bekleme, yüz başka ajanın ihtiyaç duyduğu bir yuvayı tek bir ajanın tutması demektir. 25 saniye aynı zamanda her istemcinin varsayılan zaman aşımı süresinin içinde kalır, böylece çağrı, istemci ondan vazgeçmeden döner.

Aynı anda yalnızca 8 bekleme

Bu sayı aşıldığında araç, timed_out ve bunu açıklayan bir notla hemen yanıt verir. Geri gelmesi söylenmek, haberi olmadan yedi başka ajanın arkasında sıraya girmekten iyidir.

Filtreleme: yanlış posta bekleyişi bitirmesin diye

from_contains ve subject_contains, bu sırada gelen başka her şeyi bekleyişin görmezden gelmesini sağlar. Posta kutusunda zaten bir şey varsa geçilecek parametre since_id'dir: görülen en yeni kimliği ona verin, çağrıyı yalnızca gerçekten yeni bir posta tatmin etsin.

Takma ad mı, adres mi dışarı verilmeli?

Buradaki her posta kutusunun, aynı kutuya teslimat yapan ama onu okuyamayan, on iki karakter uzunluğunda ikinci bir adresi vardır. Bu ayrım bir ajan için bir insana göre çok daha önemlidir, çünkü bir ajan kendisine verileni bulduğu her alana seve seve yapıştırır.

Bu yüzden create_inbox tek bir adres verip umut etmekle yetinmez. İkisini birden döndürür, ve hangisinin hangisi olduğunu söyleyen bir next_step alanı ekler — ajan kendi araç sonucunu okur, böylece talimat, döngüdeki kimsenin okuyamadığı bir dokümantasyon sayfasında oturmak yerine ihtiyaç duyulan yere ulaşır.

Ajanın kendi talimatlarına ne yazılmalı?

Araçlar kendilerini yeterince iyi tanımlar, öyle ki yetenekli bir model bunu hiç yönlendirilmeden de doğru yapar. Beş satır, bunu olası olmaktan çıkarıp güvenilir kılar:

• Kayıt başına bir adres. Her yerde yeniden kullanılan tek bir adres değil: altı hizmetin postasını tutan bir posta kutusu, ajanın birbirinden ayırt etmesi gereken altı doğrulama ve hepsini birden açığa çıkaracak tek bir sızıntı demektir.
• Takma adı verin, adresi asla. Araç sonucu da bunu söylese bile açıkça belirtmeye değer.
• Gönderdikten hemen sonra wait_for_message aracını çağırın, ve timed_out aldığınızda bunu bir hata saymak yerine yeniden çağırın. İki ya da üç kez normaldir.
• Posta kutusu yeni değilse since_id geçirin, yoksa eski bir mesaj bekleyişi tatmin eder ve ajan bir saat önce süresi dolmuş bir kodu okur.
• Kod kullanıldıktan sonra mesajı silin. Zorunlu değildir — zaten her şey 5 gün içinde gider — ama pencereyi erken kapatır ve bedeli tek bir idempotent çağrıdır.

Bir talimat bloğu olarak yazıldığında, uzunluğu aşağı yukarı şu kadardır:

Bir e-posta adresine ihtiyacın olduğunda create_inbox aracını çağır ve
döndürdüğü TAKMA ADI ver, adresi asla. Formu gönderir göndermez
wait_for_message aracını adresle çağır. timed_out gelirse yeniden çağır —
bu normaldir, hiçbir şey kaybolmaz. Posta kutusu boş değilse since_id
parametresini geçir. Kod kullanılınca mesajı sil.

Bunun üzerine bir şey kurmadan önce hangi sınırları bilmek gerekir?

Hepsi keşfedilmek yerine yayımlanmıştır ve hiçbirini yükselten bir plan yoktur:

Gönderim için ne bir uç nokta ne de bir araç vardır. Bu hizmet yalnızca alır, kimliği doğrulanmamış bir posta kutusunun bir spam kaynağına dönüşmesini engelleyen de tam olarak budur — bu yüzden bir insana yanıt vermesi gereken bir ajanın başka bir yerde gerçek bir posta kutusuna ihtiyacı vardır.

Bir form genel alan adlarını reddederse ne yapılır?

Pek çok hizmet, tek kullanımlık posta alan adlarının listesini tutar ve buradaki üç genel alan adı da bu listelerdedir. Bir ajan bunu, kendisine az önce verilen adresi reddeden — ya da daha kötüsü, kabul edip hiçbir şey göndermeyen — bir form olarak yaşar.

Kalıcı çözüm, sahibi olduğunuz bir alan adıdır. Tek bir MX kaydı, üzerindeki her adresi burada bir posta kutusuna dönüştürür; hiçbir listede yoktur çünkü bu sitede hiçbir yerde yazılı değildir ve aynı altı araç onun üzerinde de değişmeden çalışır — bunun tek istisnası create_inbox'tur, çünkü o adresleri yalnızca genel alan adları üzerinde uydurur. Ajan basitçe siz-seçin@alan-adınız adresini kullanır ve onun üzerinde wait_for_message aracını çağırır.

Alan adınız için MX kaydı10 smtp.grabmail.ioKopyala

Adım adım tam anlatım burada — kayıt, onu yayımlamanın neyi kanıtladığı ve parolası olmayan bir posta kutusunun gerçek sınırları.

Bir ajana bununla neler yaptırılmamalı?

Dürüst olan kısım, ve bir öğleden sonrayı kurtaran kısım:

• Geri almanız gerekecek hiçbir şey için değil. Para, kimlik ya da iş barındıran hiçbir şey için. Posta kutusu 5 gün içinde yeniden boşalır ve adresi bilen herkes tarafından okunabilir, bu yüzden gelecek yıl oraya gönderilecek bir parola sıfırlama kimseye — ya da başka birine — ulaşır.
• İkinci bir doğrulama faktörü olarak değil. Parolası olmayan bir posta kutusu bir faktör değildir.
• Özel hiçbir şey için değil. Onu biz okuduğumuz için değil, devredeki tek sır adresin kendisi olduğu ve bir ajanın onu bir log'a, bir konuşma dökümüne ya da bir commit mesajına yazmış olması pekâlâ mümkün olduğu için.
• Hacim için değil. Yüzlerce hesap açan bir ajan, tam olarak her kara listenin var olma sebebi olan davranıştır ve genel alan adlarının başka herkes için de reddedilmesini sağlamanın en hızlı yoludur.

Ne ise o olarak kullanıldığında — bir ajanla asıl yapması istenen şey arasında duran doğrulama adımı — onu güvenilir biçimde durduran o tek adımı ortadan kaldırır.

Sorular