Laravel MCP : serveurs, tools, ressources et prompts pour l’IA

Le package laravel/mcp permet de créer des serveurs MCP (Model Context Protocol) dans une application Laravel. Un serveur MCP expose des tools, des resources et des prompts que les clients IA (Claude, Cursor, etc.) peuvent appeler pour interagir avec votre app. Les serveurs sont déclarés dans routes/ai.php et peuvent être web (HTTP) ou locaux (Artisan). Ce guide présente l’installation, la création d’un serveur avec make:mcp-server et l’enregistrement web et local.

Prérequis

• Laravel 11+ (ou 12)
• Composer
• Client MCP (Cursor, Claude, Laravel Boost, etc.) pour consommer le serveur

1. Installation

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

Cela crée routes/ai.php, où sont enregistrés les serveurs MCP.

2. Créer un serveur MCP

php artisan make:mcp-server WeatherServer

Une classe est générée dans app/Mcp/Servers/WeatherServer.php (ou un namespace configuré par le package). Elle étend Laravel\Mcp\Server et définit :

• $name, $version : identification du serveur
• $instructions : instructions pour le LLM (rôle, capacités)
• $tools : liste de classes Tool
• $resources : liste de classes Resource
• $prompts : liste de classes Prompt

Exemple de squelette :

namespace App\Mcp\Servers;

use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    protected string $name = 'Weather Server';
    protected string $version = '1.0.0';
    protected string $instructions = 'Ce serveur fournit des informations météo et des prévisions.';

    protected array $tools = [
        // GetCurrentWeatherTool::class,
    ];

    protected array $resources = [
        // WeatherGuidelinesResource::class,
    ];

    protected array $prompts = [
        // DescribeWeatherPrompt::class,
    ];
}

3. Enregistrement dans routes/ai.php

Serveur web (HTTP)

Un serveur web est exposé via une route HTTP (POST). Les clients MCP distants ou les proxies peuvent s’y connecter.

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

Mcp::web('/mcp/weather', WeatherServer::class);

Middleware (auth, throttle) :

Mcp::web('/mcp/weather', WeatherServer::class)
    ->middleware(['throttle:mcp']);

Serveur local (Artisan)

Un serveur local est destiné à être démarré par un client MCP en local (ex. Cursor, Laravel Boost) via la commande mcp:start ou un script. Il tourne en stdio (ou canal équivalent) et n’est pas exposé sur le web.

Mcp::local('weather', WeatherServer::class);

Le client doit être configuré pour lancer, par exemple :
php artisan mcp:start weather (ou la commande documentée par le package).

4. Tools, Resources, Prompts

• Tools : actions que le LLM peut invoquer (ex. « récupérer la météo pour Paris »). Chaque tool est une classe avec une définition (nom, description, paramètres) et une méthode handle().
• Resources : blocs de contexte que le LLM peut lire (doc, schéma, morceaux de BDD). Une resource expose des URIs et du contenu (texte, JSON, etc.).
• Prompts : modèles de prompts pré-définis que le client peut proposer à l’utilisateur ou au LLM (ex. « Explique la météo du jour »).

La création des classes Tool, Resource et Prompt se fait via les make Artisan du package (ex. make:mcp-tool, make:mcp-resource, make:mcp-prompt selon la doc officielle). Chacune est ensuite référencée dans $tools, $resources, $prompts du serveur.

5. Sécurité et bon usage

• Serveur web : protéger par auth (token, API key) et throttle pour limiter les abus.
• Données exposées : les resources et tools peuvent accéder à la BDD ou à des APIs ; ne pas exposer de données sensibles sans contrôle d’accès.
• Local : le serveur local s’exécute avec les droits de l’utilisateur qui lance la commande ; adapter les tools à un usage développement (schéma, routes, etc.) si besoin.

Dépannage

Bonnes pratiques

• $instructions claires pour que le LLM sache quand et comment utiliser les tools/resources.
• Documenter les paramètres des tools (types, requis/optionnels) pour une bonne utilisation par le client.
• Pour un usage dev : exposer des resources (routes, schéma, config) ; pour un usage prod, limiter les tools à des opérations autorisées et auditées.

Ressources

• Tech Verse Daily – Introducing Laravel MCP
• Package laravel/mcp – GitHub / Packagist
• Model Context Protocol – specification

Cet article s’inscrit dans notre série de guides technique et développement web. Pour un serveur ou une application sur-mesure, contact.