Utiliser un serveur MCP dans votre Laravel

Les experts du langage naturel transforment Internet depuis un peu plus de deux ans avec l'IA. Régulièrement, nos fils d'actualités sont remplis de nouveaux termes ou acronymes qui challengent notre veille.

Une tendance qui m'a conquis, c'est le Model Context Protocol (MCP). Introduit par Anthropic fin 2024, il s'agit d'un standard de communication entre les assistants IA et "là où les données vivent", comme dit dans leur article, donc finalement tous les systèmes informatisés avec pour objectif de rendre les réponses des assistants IA plus pertinentes.

Ce protocole pallie deux soucis majeurs des modèles IA. L'entrainement des modèles IA se fait au prix d'un processus complexe d'intégrations et de qualifications de la donnée et malgré cela, à la mise en ligne d'un nouveau modèle, ses données d'entraînement peuvent déjà être obsolètes ou incomplète.

Sans être expert sur le machine learning ou en entrainement IA, il nous est tous arrivés de côtoyer les limites d'un assistant qui répondrait avec une donnée de 2020 et qui finira par avouer que ces données ne dépassent pas 2023.

Grâce au MCP, nous allons pouvoir injecter dans les réponses de nos assistants des données fraîches et facilement mises à jour. Dans ces conditions, on peut respecter un cycle de commercialisation plus court de nos produits.

Nous allons passer à la pratique avec le package opgginc/laravel-mcp-server qui permet une intégration en douceur d'un serveur MCP dans votre application.

Parmi ses avantages, ce package permet la communication MCP au travers du protocole HTTP, là où la plupart des librairies existantes reposent généralement sur l'entrée et la sortie standard (dans le terminal donc). Les auteurs de ce package avaient bien identifié ce dilemme pour l'intégration dans des applications web, ce qui nous facilitera la vie pour les mécanismes d'authentification.

Passons à l'action !

Autant que cela puisse l'être en six mois d'existence, les notions autour du MCP commencent à être matures. Néanmoins, restez vigilant, les notions pourraient encore évoluer, je vous recommande de suivre l'activité sur le dépôt GitHub pour suivre les dernières nouvelles.

Pour ce tutoriel, nous utiliserons la version 1.3.4 de opgginc/laravel-mcp-server.

• Installation de opgginc/laravel-mcp-server
• Utiliser les Outils MCP
• Analyse de l'Outil Hello World

Installation de opgginc/laravel-mcp-server

L'installation du package opgginc/laravel-mcp-server est tout à fait classique, on récupère le vendor via composer et on publie le fichier de configuration.

1composer require opgginc/laravel-mcp-server
2php artisan vendor:publish --provider="OPGG\LaravelMcpServer\LaravelMcpServerServiceProvider"

Le fichier de configuration config/mcp-server.php se présente en plusieurs sections.

On commencera par remplir les informations de notre serveur MCP, comme son nom et sa version et s'il est actif.

1<?php
2 
3'enabled' => true,
4 
5'server' => [
6    'name' => 'OP.GG MCP Server',
7    'version' => '0.1.0',
8],

Par défaut, le serveur MCP est utilisable via le protocole HTTP.

Le package propose un second type de communication, le "SSE", néanmoins déprécié en faveur du protocole HTTP. Le SSE semble fonctionner via un gestionnaire de file d'attente, ce qui provoque une latence dans les échanges avec les agents IA.

1<?php
2 
3'server_provider' => 'streamable_http',

Le package gère lui-même le routing et il réserve un segment d'URL pour fonctionner. Par défaut, il utilisera /mcp/ qui est bien sûr modifiable.

Vous pourrez également restreindre, ou non, l'utilisation de ce serveur MCP à un ou plusieurs domain en remplaçant la valeur par défaut (null pour aucune limitation) par une chaîne de caractères, ou un tableau, avec vos domains.

1<?php
2 
3'default_path' => 'mcp',
4'domain' => null,

Le serveur MCP est accessible dès l'installation, à condition que l'option enabled soit active.

La communication avec les endpoints MCP se fait au format JSON-RPC 2.0. Comme tout est transporté via HTTP, nous pouvons envoyer une requête pour valider notre installation avec cURL.

Ci-dessous, la requête exécutée permettra de lister les Outils ("Tools" en anglais) MCP proposés par votre application Laravel.

1curl \
2  -X POST http://localhost:8080/mcp \
3  -H "Content-Type: application/json" \
4  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Si la configuration est correcte, vous verrez apparaître la liste des Outils MCP déjà disponibles sur votre application.

Le package inclut deux Outils MCP à titre de démonstration : un "HelloWorld" et un outil pour récupérer la version de votre application Laravel.

 1{
 2  "jsonrpc": "2.0",
 3  "id": 1,
 4  "result": {
 5    "tools": [
 6      {
 7        "name": "hello-world",
 8        "description": "Say HelloWorld developer.",
 9        // ...
10      },
11      {
12        "name": "check-version",
13        "description": "Check the current Laravel version.",
14        // ...
15      }
16    ]
17  }
18}

Utiliser les Outils MCP

Si vous avez été curieux du mouvement IA alors, vous avez probablement essayé de vous familiariser avec les Outils IA.

LM Studio est une solution pour vous aider à franchir le pas simplement. Il permet de télécharger des modèles et dispose d'une interface pour chatter avec le modèle choisit.

Rappelez-vous que les modèles sont de gros consommateurs de ressources. Personnellement, j'ai adopté en local les modèles d'environ 1.5 Milliard (1.5B) de paramètres. Parmi mes favoris : Qwen3 1.7B, Lfm2 1.2B ainsi que les modèles MistralAI (🐔🥖). Attention également, tous les modèles ne sont pas capables d'utiliser la liaison avec le serveur MCP, veillez à choisir un modèle suffisamment récent.

Et bien sûr, LM Studio nous permettra de mettre en place une interconnexion entre un modèle et notre serveur MCP Laravel.

Une fois que vous aurez essayé quelques modèles et sélectionné quelques-uns fonctionnels sur votre machine. Vous pourrez vous inspirer des indications de la capture d'écran ci-dessous pour configurer le lien entre LM Studio et votre serveur MCP.

La configuration minimale est la suivante (ajustez le lien vers votre propre instance Laravel). Vous pouvez ajouter une infinité de serveurs MCP à cette liste.

1{
2  "servers": {
3    "LocalPHP": {
4      "url": "http://localhost:8080/mcp"
5    }
6  }
7}

Si votre serveur MCP apparaît dans le panneau latéral gauche, c'est bien configuré !

Vous pouvez maintenant faire interagir votre agent et votre serveur MCP. En fonction de votre paramétrage, l'agent vous demandera de valider l'exécution d'un Outil MCP.

Analyse de l'Outil Hello World

Le package vient avec son lot de commandes, et pour créer un nouvel Outil MCP il vous suffira de jouer php artisan make:mcp-tool MyCustomTool.

Les Outils sont répertoriés dans le fichier de configuration dans la rubrique "tools". Une fois ajouté à cette liste, l'Outil pourra être découvert par les agents IA.

1<?php
2 
3'tools' => [
4    \App\MCP\MyCustomTool::class,
5    \OPGG\LaravelMcpServer\Services\ToolService\Examples\HelloWorldTool::class,
6],

Votre Outil devra implémenter l'interface ToolInterface.

Vous devrez alors renseigner un nom, une description et des annotations (des meta tags en langage MCP) pour définir votre Outil. Ainsi que les paramètres attendus (via inputSchema()) qui seront collectés lors de vos échanges avec un agent IA.

Ces étapes sont importantes, car cela sera utilisé par les agents IA connectés au serveur MCP pour enrichir leurs réponses.

 1public function inputSchema(): array
 2{
 3    return [
 4        'type' => 'object',
 5        'properties' => [
 6            'name' => [
 7                'type' => 'string',
 8                'description' => 'Developer Name',
 9            ],
10        ],
11        'required' => ['name'],
12    ];
13}

Enfin, il faudra définir le fonctionnement de notre outil, sa logique et son code, ce qui sera notre partie préférée !

Et en cas d'erreur d'exécution dans votre outil, vous devrez adapter votre format de réponse. Suivez la spécification JSON-RPC 2.0 et utilisez, par exemple, l'exception JsonRpcErrorException.

 1 
 2public function execute(array $arguments): array
 3{
 4    $validator = Validator::make($arguments, [
 5        'name' => ['required', 'string'],
 6    ]);
 7    if ($validator->fails()) {
 8        throw new JsonRpcErrorException(
 9            message: $validator->errors()->toJson(),
10            code: JsonRpcErrorCode::INVALID_REQUEST
11        );
12    }
13 
14    $name = $arguments['name'] ?? 'MCP';
15 
16    return [
17        'name' => $name,
18        'message' => "Hello, HelloWorld `{$name}` developer.",
19    ];
20}

Une fois codé, il suffira de retourner sur LM Studio pour tester le bon fonctionnement de notre nouvel Outil MCP.

Super ! Nous avons intégré notre serveur MCP dans notre application ! Grâce à lui, nous pouvons maintenant enrichir rapidement les résultats d'une IA et créer plus simplement des automatisations en langage naturel.

Si les Outils MCP ont un fort impact pour travailler avec les agents IA, ce ne sont pas les seuls atouts de ce package opgginc/laravel-mcp-server.

Il implémente plus largement les directives MCP et entre autres, vous pourrez également profiter des Resources, endpoints MCP qui permettront de mettre à disposition des données à votre agent. Ou encore les Prompts qui sont des commandes comme les Outils, mais qui s'utilisent à la demande explicite de l'utilisateur lors d'un échange avec l'agent IA, cela fonctionne comme les commandes IRC ou Discord ;)

Une dernière chose, comme je sais que vous êtes pressé de mettre en production. opgginc/laravel-mcp-server peut utiliser les middlewares pour contrôler les accès au serveur MCP. Ci-dessous, un dernier exemple pour passer des headers dans votre configuration LM Studio.

 1{
 2  "servers": {
 3    "LocalPHP": {
 4      "url": "http://localhost:8080/mcp",
 5      "headers": {
 6        "Authorization": "Bearer <ACCESS_TOKEN>"
 7      }
 8    }
 9  }
10}

Antoine Benevaut

PHP & Laravel Consultant - Lead Developer, Paris / Passionate / Cat lover / #laravel 😍