Intégrer un serveur MCP dans une application Laravel
Les agents IA ont besoin de plus qu'une simple interface web scrapée. Ils ont besoin d'un moyen d'appeler des outils spécifiques avec les permissions appropriées. C'est précisément ce que fait le Model Context Protocol (MCP).
J'ai récemment intégré un serveur MCP directement dans une application Laravel. Je souhaite partager les décisions architecturales prises pour construire cela de manière sécurisée.
La métaphore de la réceptionniste
Considérez votre application comme un immeuble de bureaux.
- L'interface web est le hall d'accueil pour les humains.
- L'API REST est l'entrée du personnel pour les systèmes.
- Le serveur MCP est un bureau de réception pour les agents IA.
L'agent présente une pièce d'identité et demande une tâche spécifique. La réceptionniste ne lui donne pas les clés de l'immeuble. Elle vérifie les permissions, effectue une seule tâche et renvoie une réponse structurée.
Décisions de conception clés
1. Utiliser un point de terminaison unique
Ne créez pas de nombreuses routes pour différents outils. Utilisez un seul endpoint /mcp. Le protocole gère automatiquement la découverte des outils. Une surface d'attaque unique est plus facile à sécuriser et à documenter.
2. Prendre en charge la double authentification
Différents appelants nécessitent différentes méthodes de sécurité :
- Les appelants de première partie (comme les outils CLI) utilisent des jetons d'accès personnels Sanctum.
- Les agents tiers (agissant pour le compte des utilisateurs) utilisent OAuth 2.1.
Utilisez un résolveur de type "driver" pour gérer les deux. Le code de l'outil ne doit se soucier que de l'utilisateur authentifié, et non de la méthode de connexion.
3. Appliquer le RBAC existant
L'authentification prouve seulement qui est l'appelant. Vous devez toujours vérifier ce qu'il peut faire. Chaque outil doit correspondre à une capacité (ability) existante. Si un utilisateur ne peut pas voir les participants dans l'interface web, il ne devrait pas pouvoir le faire via MCP.
4. Limiter la sortie des données
Ne renvoyez jamais un modèle de base de données complet. Traitez la sortie MCP comme une API publique. Ne renvoyez que les champs spécifiques dont l'agent a besoin. Cela évite les fuites de données accidentelles.
Tester la sécurité
Vos tests doivent prouver que le système échoue correctement. Testez que :
- Un utilisateur non autorisé reçoit une erreur
403 Forbidden. - Un utilisateur autorisé ne reçoit que les champs autorisés.
Une bonne suite de tests est votre meilleure défense contre les fuites de données lors de l'utilisation d'agents autonomes.
Résumé
Pour construire un serveur MCP responsable, suivez ces trois règles :
- Authentifiez chaque appelant en utilisant le bon schéma.
- Autorisez chaque outil en utilisant votre modèle de permissions existant.
- Traitez chaque sortie d'outil comme une ressource publique limitée.