Ein MCP-Server in einer Laravel-App
KI-Agenten benötigen mehr als nur eine UI, die lediglich per Scraping ausgelesen wird. Sie brauchen eine Möglichkeit, spezifische Tools mit den entsprechenden Berechtigungen aufzurufen. Genau das macht das Model Context Protocol (MCP).
Ich habe vor Kurzem einen MCP-Server direkt in eine Laravel-Anwendung integriert. Ich möchte die architektonischen Entscheidungen teilen, die ich getroffen habe, um dies sicher umzusetzen.
Die Metapher des Empfangs
Stellen Sie sich Ihre App wie ein Bürogebäude vor.
- Die Web-UI ist die Lobby für Menschen.
- Die REST-API ist der Personaleingang für Systeme.
- Der MCP-Server ist der Empfangstresen für KI-Agenten.
Der Agent weist sich mit einer ID aus und bittet um eine spezifische Aufgabe. Die Empfangsperson gibt ihm nicht die Schlüssel zum Gebäude. Sie prüft die Berechtigungen, führt eine einzige Aufgabe aus und liefert eine strukturierte Antwort zurück.
Wichtige Design-Entscheidungen
1. Verwenden Sie einen einzigen Endpunkt
Erstellen Sie nicht viele Routen für verschiedene Tools. Verwenden Sie einen einzigen /mcp-Endpunkt. Das Protokoll übernimmt die Tool-Discovery automatisch. Eine einzige Schnittstelle ist einfacher abzusichern und zu dokumentieren.
2. Unterstützung dualer Authentifizierung
Verschiedene Aufrufer benötigen unterschiedliche Sicherheitsmethoden:
- First-Party-Aufrufer (wie CLI-Tools) verwenden Sanctum Personal Access Tokens.
- Third-Party-Agenten (die im Namen von Nutzern handeln) verwenden OAuth 2.1.
Verwenden Sie einen Resolver im Driver-Stil, um beides zu handhaben. Der Tool-Code sollte sich nur um den authentifizierten Benutzer kümmern, nicht darum, wie dieser sich eingeloggt hat.
3. Bestehendes RBAC erzwingen
Die Authentifizierung beweist nur, wer der Aufrufer ist. Sie müssen dennoch prüfen, was er tun darf. Jedes Tool sollte einer bestehenden Berechtigung (Ability) zugeordnet sein. Wenn ein Benutzer Teilnehmer in der Web-UI nicht sehen kann, sollte er dies auch nicht über MCP können.
4. Datenausgabe begrenzen
Geben Sie niemals ein vollständiges Datenbankmodell zurück. Behandeln Sie die MCP-Ausgabe wie eine öffentliche API. Geben Sie nur die spezifischen Felder zurück, die der Agent benötigt. Dies verhindert versehentliche Datenlecks.
Sicherheitstests
Ihre Tests müssen beweisen, dass das System im Fehlerfall korrekt reagiert. Testen Sie, ob:
- Ein nicht autorisierter Benutzer einen
403 Forbidden-Fehler erhält. - Ein autorisierter Benutzer nur die erlaubten Felder erhält.
Eine gute Testsuite ist Ihr bester Schutz gegen Datenlecks bei der Verwendung autonomer Agenten.
Zusammenfassung
Um einen verantwortungsvollen MCP-Server zu bauen, befolgen Sie diese drei Regeln:
- Authentifizieren Sie jeden Aufrufer mit dem richtigen Verfahren.
- Autorisieren Sie jedes Tool mithilfe Ihres bestehenden Berechtigungsmodells.
- Behandeln Sie jede Tool-Ausgabe als eine begrenzte öffentliche Ressource.