Laravel MCP : Exposez votre application Laravel aux agents IA avec le Model Context Protocol

Le Model Context Protocol (MCP) devient rapidement le standard universel pour connecter les applications aux agents IA. Laravel MCP permet de créer des serveurs MCP directement dans vos applications Laravel en quelques minutes.

Qu’est-ce que le Model Context Protocol ?

Le Model Context Protocol est un standard ouvert introduit par Anthropic. Il définit une manière structurée pour les clients IA (ChatGPT, Claude, Cursor, etc.) d’interagir avec des applications externes.

Concrètement, MCP permet à votre application Laravel de devenir une source de données et d’actions pour les agents IA. Vos utilisateurs peuvent interagir avec votre produit directement depuis leur assistant IA préféré, sans quitter leur interface de chat.

Laravel MCP supporte la spécification MCP version 2025-03-26 et fonctionne avec Laravel 10, 11 et 12 (PHP 8.1+).

Installation

L’installation se fait via Composer :

# Installation du package
composer require laravel/mcp

Publiez ensuite le fichier de routes dédié :

# Publication des routes MCP
php artisan vendor:publish --tag=ai-routes

Cette commande crée le fichier routes/ai.php où vous définirez vos serveurs MCP.

Les trois primitives MCP

Laravel MCP expose trois types de composants :

• Tools : Actions exécutables par l’IA (créer une facture, envoyer un email, lancer un robot aspirateur…)
• Resources : Données consultables par l’IA (documents, configurations, profils utilisateurs…)
• Prompts : Templates de prompts réutilisables pour des interactions cohérentes

Créer un serveur MCP

Générez un serveur avec la commande Artisan :

# Création d'un serveur MCP
php artisan make:mcp-server ProductServer

Le serveur généré ressemble à ceci :

<?php

namespace App\Mcp\Servers;

use Laravel\Mcp\Server;

class ProductServer extends Server
{
    // Nom affiché aux clients IA
    protected string $name = 'Product Server';

    // Version du serveur
    protected string $version = '1.0.0';

    // Instructions pour le LLM
    protected string $instructions = 'Ce serveur gère les produits du catalogue.';

    // Outils disponibles
    protected array $tools = [];

    // Ressources exposées
    protected array $resources = [];

    // Prompts prédéfinis
    protected array $prompts = [];
}

Enregistrez le serveur dans routes/ai.php :

<?php

use App\Mcp\Servers\ProductServer;
use Laravel\Mcp\Facades\Mcp;

// Serveur accessible via HTTP (pour clients distants)
Mcp::web('/mcp/products', ProductServer::class);

// Serveur local (pour assistants comme Laravel Boost)
Mcp::local('products', ProductServer::class);

Créer un Tool

Les Tools permettent à l’IA d’exécuter des actions. Créez-en un avec :

# Création d'un outil MCP
php artisan make:mcp-tool SearchProductsTool

Voici un exemple complet de Tool :

<?php

namespace App\Mcp\Tools;

use App\Models\Product;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class SearchProductsTool extends Tool
{
    // Description utilisée par l'IA pour comprendre l'outil
    protected string $description = 'Recherche des produits par nom ou catégorie.';

    // Définition du schéma d'entrée
    public function schema(JsonSchema $schema): array
    {
        return [
            'query' => $schema->string()
                ->description('Terme de recherche')
                ->required(),
            'category' => $schema->string()
                ->description('Catégorie optionnelle'),
            'limit' => $schema->integer()
                ->description('Nombre maximum de résultats')
                ->default(10),
        ];
    }

    // Logique d'exécution
    public function handle(Request $request): Response
    {
        $query = $request->get('query');
        $category = $request->get('category');
        $limit = $request->get('limit', 10);

        $products = Product::query()
            ->when($query, fn($q) => $q->where('name', 'like', "%{$query}%"))
            ->when($category, fn($q) => $q->where('category', $category))
            ->limit($limit)
            ->get(['id', 'name', 'price', 'category']);

        return Response::structured($products->toArray());
    }
}

Enregistrez l’outil dans votre serveur :

protected array $tools = [
    SearchProductsTool::class,
];

Créer une Resource

Les Resources exposent des données que l’IA peut consulter comme contexte :

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Resource;

class ProductCatalogResource extends Resource
{
    // URI unique de la ressource
    protected string $uri = 'products://catalog/guidelines';

    // Type MIME du contenu
    protected string $mimeType = 'text/markdown';

    // Description pour l'IA
    protected string $description = 'Guide du catalogue produits avec les règles métier.';

    public function handle(Request $request): Response
    {
        $guidelines = <<<'MD'
        # Règles du catalogue

        - Les prix sont en euros HT
        - Les produits épuisés ont un stock à 0
        - Les catégories valides : électronique, vêtements, alimentaire
        MD;

        return Response::text($guidelines);
    }
}

Templates de ressources dynamiques

Pour des ressources avec paramètres variables, implémentez HasUriTemplate :

<?php

namespace App\Mcp\Resources;

use App\Models\Product;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Contracts\HasUriTemplate;
use Laravel\Mcp\Server\Resource;
use Laravel\Mcp\Support\UriTemplate;

class ProductDetailResource extends Resource implements HasUriTemplate
{
    protected string $description = 'Détails complets d\'un produit par son ID.';
    protected string $mimeType = 'application/json';

    // Template d'URI avec variable
    public function uriTemplate(): UriTemplate
    {
        return new UriTemplate('products://catalog/{productId}');
    }

    public function handle(Request $request): Response
    {
        // La variable est extraite automatiquement
        $productId = $request->get('productId');

        $product = Product::findOrFail($productId);

        return Response::structured($product->toArray());
    }
}

Authentification

Laravel MCP s’intègre avec Sanctum et Passport pour sécuriser vos serveurs.

Avec Sanctum :

Mcp::web('/mcp/products', ProductServer::class)
    ->middleware('auth:sanctum');

Avec Passport (OAuth 2.1, recommandé pour la compatibilité MCP) :

use Laravel\Mcp\Facades\Mcp;

// Routes OAuth requises
Mcp::oauthRoutes();

Mcp::web('/mcp/products', ProductServer::class)
    ->middleware('auth:api');

Tester avec MCP Inspector

Laravel MCP inclut un inspecteur pour tester vos serveurs :

# Test d'un serveur web
php artisan mcp:inspector mcp/products

# Test d'un serveur local
php artisan mcp:inspector products

L’inspecteur affiche la configuration à copier dans votre client MCP (Claude, Cursor, etc.).

Bonnes pratiques

• Descriptions précises : L’IA choisit les outils selon leurs descriptions. Soyez explicite sur ce que fait chaque Tool.
• Validation robuste : Utilisez la validation Laravel dans handle() avec des messages d’erreur clairs pour guider l’IA.
• Annotations de comportement : Marquez vos Tools avec #[IsReadOnly] ou #[IsDestructive] pour informer l’IA des effets de bord.
• Enregistrement conditionnel : Implémentez shouldRegister() pour exposer des Tools uniquement aux utilisateurs autorisés.

Cas d’usage concrets

Laravel MCP ouvre de nombreuses possibilités :

• Support client : L’IA consulte l’historique des commandes et déclenche des remboursements
• CRM : Création de contacts et envoi d’emails depuis un chat IA
• E-commerce : Recherche produits, vérification de stock, suivi de commandes
• Administration : Génération de rapports, gestion des utilisateurs

L’application démo Locket illustre une implémentation complète avec interface web, API JSON et serveur MCP.

Résumé

Laravel MCP transforme votre application en point d’entrée pour les agents IA. Avec plus de 3 milliards de messages IA quotidiens, MCP devient un canal de distribution incontournable aux côtés du web et des API REST. Le package, actuellement en version 0.5.1, offre déjà une expérience de développement typiquement Laravel : fluide, élégante et productive.

Ressources

• Documentation officielle Laravel MCP
• Repository GitHub laravel/mcp
• Application démo Locket
• Annonce officielle Laravel MCP
• Spécification Model Context Protocol