Bir Laravel Uygulamasının İçine MCP Sunucusu Yerleştirmek
Yapay zeka ajanlarının sadece kazınmış (scraped) bir kullanıcı arayüzünden fazlasına ihtiyacı vardır. Belirli araçları uygun izinlerle çağırabilmeleri gerekir. Model Context Protocol (MCP) tam olarak bunu yapar.
Yakın zamanda bir MCP sunucusunu doğrudan bir Laravel uygulamasına entegre ettim. Bunu güvenli bir şekilde inşa etmek için aldığım mimari kararları paylaşmak istiyorum.
Resepsiyonist Metaforu Uygulamanızı bir ofis binası olarak düşünün.
- Web arayüzü (UI), insanlar için lobi kısmıdır.
- REST API, sistemler için personel girişidir.
- MCP sunucusu, yapay zeka ajanları için bir resepsiyon masasıdır.
Ajan bir kimlik gösterir ve belirli bir görev ister. Resepsiyonist onlara binanın anahtarlarını vermez. İzinleri kontrol eder, tek bir görevi yerine getirir ve yapılandırılmış bir yanıt döner.
Temel Tasarım Kararları
Tek bir uç nokta (endpoint) kullanın Farklı araçlar için birçok rota oluşturmayın. Tek bir
/mcpuç noktası kullanın. Protokol, araç keşfini (tool discovery) otomatik olarak halleder. Tek bir yüzeyi güvenli hale getirmek ve belgelemek daha kolaydır.Çift kimlik doğrulamayı destekleyin Farklı çağırıcılar farklı güvenlik yöntemlerine ihtiyaç duyar:
- Birinci taraf çağırıcılar (CLI araçları gibi) Sanctum kişisel erişim jetonlarını (personal access tokens) kullanır.
- Üçüncü taraf ajanlar (kullanıcılar adına hareket edenler) OAuth 2.1 kullanır.
Her ikisini de yönetmek için sürücü (driver) tarzı bir çözücü (resolver) kullanın. Araç kodu, kullanıcının nasıl giriş yaptığıyla değil, yalnızca kimliği doğrulanmış kullanıcıyla ilgilenmelidir.
Mevcut RBAC'ı uygulayın Kimlik doğrulama yalnızca çağırıcının kim olduğunu kanıtlar. Neleri yapabileceğini hala kontrol etmeniz gerekir. Her araç mevcut bir yetenekle (ability) eşleşmelidir. Eğer bir kullanıcı web arayüzünde katılımcıları görüntüleyemiyorsa, bunu MCP üzerinden de yapamamalıdır.
Veri çıktısını sınırlayın Asla tam bir veritabanı modelini döndürmeyin. MCP çıktısını halka açık bir API gibi değerlendirin. Yalnızca ajanın ihtiyaç duyduğu belirli alanları döndürün. Bu, kazara veri sızıntılarını önler.
Güvenlik İçin Test Etme Testleriniz, sistemin hataları doğru şekilde yönettiğini kanıtlamalıdır. Şunları test edin:
- Yetkisiz bir kullanıcı 403 Forbidden hatası alır.
- Yetkili bir kullanıcı yalnızca izin verilen alanları alır.
Otonom ajanlar kullanırken iyi bir test paketi, veri sızıntılarına karşı en iyi savunmanızdır.
Özet Sorumlu bir MCP sunucusu oluşturmak için şu üç kuralı izleyin:
- Her çağırıcıyı doğru şemayı kullanarak kimlik doğrulayın.
- Her aracı mevcut izin modelinizi kullanarak yetkilendirin.
- Her araç çıktısını sınırlı bir halka açık kaynak olarak değerlendirin.