Créer son propre serveur MCP avec laravel/mcp : tutoriel pas à pas

Le Model Context Protocol (MCP) permet à un assistant IA d'interagir avec vos applications de façon standardisée : lire des données, exécuter des actions, consulter des ressources. Le package officiel laravel/mcp vous permet de transformer une application Laravel en serveur MCP en quelques classes. Dans notre article Laravel et MCP en action, nous avons vu le panorama ; voici maintenant un tutoriel concret.

Ce que vous allez construire

Un petit serveur MCP qui expose un outil permettant à une IA de rechercher des commandes dans votre application, en lecture seule. Le principe est le même pour n'importe quel cas d'usage : consulter un CRM, générer un rapport, déclencher une tâche.

1. Installation

Dans un projet Laravel existant :

composer require laravel/mcp
php artisan vendor:publish --tag=ai-routes

La seconde commande publie le fichier routes/ai.php, où vous déclarerez vos serveurs. Vérifiez toujours les commandes exactes dans la documentation officielle, le package évoluant rapidement.

2. Créer le serveur

php artisan make:mcp-server OrdersServer

Cette commande génère une classe de serveur dans app/Mcp/Servers. Vous y décrivez son nom, ses instructions pour le modèle, et la liste des outils, ressources et prompts disponibles :

class OrdersServer extends Server
{
    protected string $name = 'Orders Server';
    protected string $version = '1.0.0';
    protected string $instructions = 'Permet de rechercher des commandes en lecture seule.';

    protected array $tools = [
        SearchOrdersTool::class,
    ];
}

3. Créer un outil

php artisan make:mcp-tool SearchOrdersTool

Un outil déclare son schéma d'entrée (ce que l'IA doit fournir) et sa méthode handle (ce qu'il fait) :

class SearchOrdersTool extends Tool
{
    protected string $description = 'Recherche des commandes par statut.';

    public function schema(JsonSchema $schema): array
    {
        return [
            'status' => $schema->string()->description('pending, paid ou shipped')->required(),
        ];
    }

    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'status' => 'required|in:pending,paid,shipped',
        ]);

        $orders = Order::where('status', $validated['status'])
            ->limit(20)
            ->get(['id', 'reference', 'total']);

        return Response::text($orders->toJson());
    }
}

Trois principes à retenir : décrire précisément l'outil (le modèle choisit ses outils d'après leur description), valider systématiquement les entrées, et limiter les données renvoyées.

4. Enregistrer le serveur

Dans routes/ai.php, vous exposez le serveur de deux façons possibles :

use Laravel\Mcp\Facades\Mcp;

// Serveur web (HTTP), accessible par des clients distants
Mcp::web('/mcp/orders', OrdersServer::class)
    ->middleware('auth:sanctum');

// Serveur local, lancé en processus par un client sur la machine
Mcp::local('orders', OrdersServer::class);

5. Tester avec l'Inspector

Le package fournit une commande pour inspecter visuellement votre serveur :

php artisan mcp:inspector mcp/orders

Vous pouvez lister les outils, appeler SearchOrdersTool avec des paramètres et vérifier la réponse avant de connecter un vrai client IA. Pensez aussi à écrire des tests automatisés : un outil est une classe PHP comme une autre.

6. Sécuriser votre serveur

Donner à une IA l'accès à votre application suppose de la rigueur :

• Authentification : protégez toute route web par Sanctum ou OAuth, jamais en accès libre.
• Moindre privilège : un outil de lecture n'a pas besoin d'écrire. Séparez les outils sensibles.
• Validation et limites : bornez les résultats, validez chaque argument, journalisez les appels.
• Confirmation humaine : pour toute action destructrice, exigez une validation côté client.
• Données sensibles : ne renvoyez jamais de secrets ni d'informations personnelles inutiles.

Ces réflexes rejoignent les bonnes pratiques de cybersécurité habituelles et la checklist de sécurité Laravel : une IA est un client comme un autre, et il faut le traiter comme tel.

Aller plus loin

Après les outils, explorez les ressources (contenus que l'IA peut lire) et les prompts (modèles d'instructions réutilisables). Pour accélérer votre développement avec l'IA, consultez aussi notre guide sur Laravel Boost. Si vous préférez garder vos données en interne, découvrez comment intégrer un LLM local avec Ollama dans Laravel.

Conclusion

Avec laravel/mcp, créer un serveur MCP revient à écrire quelques classes Laravel classiques : un serveur, des outils, des routes. La vraie difficulté n'est pas technique mais de conception : décider ce que l'IA a le droit de faire, et le sécuriser en conséquence.