Laravel Uygulaması İçine MCP Sunucusu Yerleştirme: Yapay Zeka Araçları için Çift Kimlik Doğrulama ve RBAC

Her uygulamanın gelişim sürecinde birisi, “AI asistanı bu şeyle sadece konuşabilir mi?” diye sorar. Kullanıcı arayüzünü taramak, REST API’yi tersine mühendislik yapmak yerine, uygulamanın kasıtlı olarak sunduğu yazılı aletleri çağırmak isteği söz konusudur. Model Bağlam Protokolü (MCP), işte bu sorunu çözer ve bugünkü çalışmam MCP sunucusunu bir Laravel uygulamasına entegre etmekti.

Bu dersi öğretici ve genel tutacağım — burada kullanılan desenler, çalıştığım spesifik ürüne bağlı değil, herhangi bir Laravel uygulamasına uygulanabilir. Hem kararları hem de ilginç olan bölümleri ele alacağım, çünkü “bir aracı nasıl kaydedersiniz?” kısmı kolaydır. Asıl zorluklar kimlik doğrulama, yetkilendirme ve aradaki yerleşimdir.

Analojik Yaklaşım: MCP sunucusu bir resepsiyon masasıdır, arka kapı değil

Uygulamanızı bir ofis binası olarak düşünün. Web kullanıcı arayüzü insanlar için ön lobi gibidir. REST API, diğer sistemler için personel girişi gibidir. MCP sunucusu ise AI ajanları için özel olarak inşa edilmiş bir resepsiyon masasıdır: ajanın kimliğini gösterip ve resepsiyondan belirli bir görevi gerçekleştirmesini istediğinde, “bu etkinlik için katılımcıları listele”, “bu kullanıcının detaylarını al” gibi taleplerle gelir. Resepsiyonist binanın anahtarlarını vermez. Öncelikle kim olduğunuzu kontrol eder, neye izin verildiğini kontrol eder, yalnızca istenen görevi yerine getirir ve yapılandırılmış bir yanıtı geri verir.

MCP’yi anlamanın önemli noktası: veritabanınızı veya iç yapınızı ortaya çıkarmıyorsunuz. Bunun yerine, bir niyetler menüsü sunuyorsunuz — ayrı, adlandırılmış, yazılı aletler — ve diğer her şey masanın arkasında kalıyor.

Tek bir uç nokta, ağaç gibi rotalar değil

Gerçek karar, her şeyi tek bir /mcp uç noktasına indirmek oldu. Erken aşamada genişlemek cazip olabilir — burada bir rota, orada bir ayar sayfası, başka bir yerde bir token. Tüm bunları, protokolün konuştuğu tek bir MCP uç noktasına çekerek, insanlarla yüz yüze ayarları, sistem yapılandırmasının geri kalanı ile birlikte yönetim alanında tutmayı tercih ettim.

Bu, on beş farklı webhook URL’si açmadığınız için aynı sebepten: iyi tanımlanmış bir yüzey, karmaşık bir yapıya göre daha kolay güvenli hale getirilir, belgelenir ve düşünülür. Protokol zaten araç keşfi sunar — istemci sunucuya “ne yapabilirsin?” diye sorar ve bir liste alır — bu yüzden her bir yetenek için ayrı rotalara ihtiyacınız yoktur. Araçlar kendilerini kaydeder; uç nokta tek kalır.

Protokol altyapısını kendi başınıza oluşturmaktansa bir paket kullanmaya yönelin. Ben Laravel’in MCP desteğini kullanarak kendi cleaniquecoders/laravel-mcp-kit projemle bir başlangıç yapma şansı buldum — sunucu kaydı, araç temel sınıfları, token tabloları — böylece işimi kimlik doğrulama ve gerçekten mevcut aletler üzerinde odaklayabildim.

Çift kimlik doğrulaması: Sanctum ve OAuth 2.1

Burada durmak istiyorum çünkü birçok “AI uç noktasını ekleyin” girişimleri burada kayar.

Bir MCP sunucusunun iyi tanımlanmış iki farklı istemcisi vardır:

• Bir birinci taraf istemci — kendi arka plan işiniz, CLI, dahili bir entegrasyon. Bunlar için en doğru araç kişisel erişim tokenıdır (Sanctum). Basit, geri alınabilir, kapsamlıdır.
• Bir üçüncü taraf ajan, bir kullanıcı adına hareket eden — dışardan kullanıcı tarafından bağlanan AI istemcisi. Bu durumda, gerçek bir devredilen yetkilendirme akışı istersiniz, ki bu da OAuth 2.1 içindir. Kullanıcı onay verir, ajan kullanıcıya bağlı bir token alır ve bu token’ı geri almanız, diğerlerini etkilemeden mümkündür.

Birini seçmek ve diğer yarısını rahatsız etmemek yerine, sunucu her ikisini de kabul ediyor. Hilesi ise çözümleme işlemini tutarlı tutmaktır: hangi yol isteği doğruladıysa — bir araç içerisinde olduğunuzda, elinizde yalnızca bir şey vardır: kimliği doğrulanan bir kullanıcı — ve araç kodunun oraya nasıl ulaştıkları umurumda değildir.

Bir sürücü tarzı koruma çözücü bu durumu temiz hale getiriyor. Kavramsal olarak:

interface ResolvesMcpIdentity
{
    public function resolve(Request $request): ?Authenticatable;
}

Her bir şemaya bir çözücü uyguluyorsunuz (bir Sanctum çözümü, bir OAuth çözümü), bunları sırayla deneyin ve başarılı olan ilk çözüm kazanır. Sonradan yeni bir şema mı eklenecek? Bir sürücü ekleyin, kaydedin, tamam — araçlar asla değişmez. Bu, her yerde güvendiğim değiştirilebilir arka uç deseniyle aynı: sözleşmenin üzerinden program yapın, uygulamayı değiştirin.

Yetkilendirme kimlik doğrulama değildir — yetenekleri araçlara eşleştirin

Arayanın kimliğini doğrulamak, size kimi gösterir. Bu, ne yapabilecekleri hakkında hiçbir şey göstermez. Sürekli gördüğüm bir hata: bir uygulama MCP bağlantısını dikkatlice kimlik doğruladıktan sonra, herhangi bir kimliği doğrulanmış arayanın herhangi bir aracı çağırmasına izin verir. Bu, resepsiyon masası kostümü giymiş bir arka kapıdır.

Bu nedenle her araç bir yeteneğe eşlenir ve web arayüzü tarafından uygulanan aynı RBAC kuralları burada da geçerlidir. Bunu en temiz şekilde ifade etmenin yolu, her aracın neye ihtiyacı olduğunu belirlemesine izin vermektir:

final class ListEventParticipantsTool extends Tool
{
    public function ability(): string
    {
        return ;
    }

    public function handle(Request $request): array
    {
        // $request->user() zaten koruma katmanı ile çözülmüş.
        // Yetkilendirme merkezi olarak kontrol edilir.
        return Participant::query()
            ->where(, $request->validated())
            ->paginate()
            ->through(fn ($p) => $p->only([, , ]))
            ->toArray();
    }
}

Aracın bilgi yayılımını daraltarak döndürdüğünü unutmayın — yalnızca UUID, ad ve durum bilgisi — tam Eloquent modelini değil. Araçlar, dış bir yüzeydir; çıktıları, bir API kaynağı gibi değerlendirilmelidir; iç dökümler gibi değil. Controller’dan doğrudan $model->toArray() döndürmemekle aynı disiplin.

Yetenek kontrolü tek bir yerde — bir middleware veya temel araç kancasında — olur; ability() kontrol edilir ve mevcut kapıdan geçirilir. Tek bir sıkışma noktası, her araç kapsandı, her bir araç için ayrı if karmaşası olmadan.

Dizinin araçları, kavramsal olarak

Paketlediğim gerçek araçlar küçük bir “dizi” setiydi — bir etkinlik için katılımcıları listele, bir organizasyonun kullanıcılarını listele, tek bir kullanıcıyı ara, tüm kullanıcıları listele. Kasitli olarak sıkıcı olan bu durum doğası gereği öyle. Bir MCP aracı, bir ince, iyi adlandırılmış, iyi yetkilendirilmiş fiil olarak mevcut veriler üzerinde olmalı, yeni kurallar gerektiren akıllıca bir yol değil. Her biri, girişlerini form isteği üzerinden doğrular, yeteneklerini kontrol eder ve daraltılmış bir çıktı döner. Eğer bir araç, uygulamanın geri kalanının vermediği özel bir erişim istemeye başlarsa, bu bir kokudur — çözüm, izin modelini düzeltmek olmalıdır, araca gizli bir tünel vermek değil.

Sınırı test et, mutlu yolu değil

Buradaki değerli testler, “araç veri döndürüyor mu?” değil, “araç bunu reddediyor mu?” şeklindedir. Pest, olumsuz durumları okunabilir hale getirir:

it(, function () {
            $user = User::factory()->create(); // yetenek yok: participants.view

            $this->actingAs($user)
                ->postJson(, mcpCall(, [=> $event->uuid]))
                ->assertForbidden();
        });

        it(, function () {
            $user = User::factory()->withAbility()->create();

            $response = $this->actingAs($user)
                ->postJson(, mcpCall(, [=> $event->uuid]))
                ->assertOk();

            expect($response->json())
                ->toHaveKeys([, , ])
                ->not->toHaveKey(); // projeksiyon, ekstra alan sızdırmamalıdır
        });
        

not->toHaveKey('email') ifadesi benim için en önemli olanıdır. Bu, bir regresyon sınırıdır: bir gün birisi “istemeden” bir araçtan tüm modeli döndürdüğünde, bu test, yazılmadan önce kırılır. Yüzeyiniz, otonom bir ajan tarafından tüketildiğinde, test seti, ne kadar dikkatli bir projeksiyon ile veri sızıntısı arasında kalan bir engel olur.

Bir token + ayar arayüzü, çünkü geri çağırma insan hızında olmalı

Son parça: MCP sunucusunu açıp kapatacak ve tokenları yönetecek küçük bir yönetici UI’si. Bu, bir incelik gibi görünse de aslında güvenlik modelinin bir parçasıdır. Başarısız bir ajanın kesilmesinin tek yolu SSH ile komut çalıştırmaksa, ateş alarmını butonsuz inşa etmiş olursunuz. Bir insanın, “bu tokenlar mevcut, bu yanlış görünüyor, iptal et” diyerek birkaç tıklama ile bunu görebilmesi gerekir. Acil durumda bulabileceği yerde kesme düğmesi yer almalıdır.

Alınacak Ders

Bir MCP sunucusunu bir Laravel uygulamasına eklemek kolaydır. Bunu sorumlu bir şekilde yapmak ise üç sınıra dayanmaktadır: her çağrıyı kimlik doğrulamak (ve birinci taraf ile üçüncü taraf çağrılarının farklı şemalara ihtiyaç duyacağını kabul etmek), her aracı mevcut izin modeline göre yetkilendirmek ve her aracın çıktısını bir genel API kaynağı gibi değerlendirmek. Bunları doğru bir şekilde yaparsanız, AI asistanı iyi davranan bir konuğuna dönüşür — bir pencereden girmeyen birisi.

Gelecek: OAuth yolunda onay ekranını sıkılaştırmak ve alet menüsünü dikkatlice, her defasında tek bir iyi yetkilendirilmiş fiil ile genişletmek.