Laravel MCP - Knowledge of Laravel

Qu’est-ce que MCP

Model Context Protocol (MCP) est une spécification pour la communication standardisée entre clients IA (Claude, Cursor, GitHub Copilot…) et les applications. En implémentant un serveur MCP, votre agent IA peut accéder aux données de votre app Laravel et déclencher des actions.

Laravel MCP est un package officiel ajouté sous Laravel 13, disponible sous laravel/mcp.

Un serveur MCP fournit trois choses :

Fonctionnalité	Description
Tools	Fonctions appelables par le client IA (recherche, mise à jour, appel d’API externe…)
Resources	Données et contexte que le client peut lire
Prompts	Modèles de prompts réutilisables

Installation

composer require laravel/mcp

Publiez les routes AI :

php artisan vendor:publish --tag=ai-routes

Le fichier routes/ai.php est créé.

Créer un serveur

php artisan make:mcp-server WeatherServer

app/Mcp/Servers :

<?php

namespace App\Mcp\Servers;

use Laravel\Mcp\Server\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;
use Laravel\Mcp\Server;

#[Name('Weather Server')]
#[Version('1.0.0')]
#[Instructions('This server provides weather information and forecasts.')]
class WeatherServer extends Server
{
    protected array $tools = [
        // GetCurrentWeatherTool::class,
    ];

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

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

Enregistrer le serveur

Dans routes/ai.php, deux modes possibles.

Serveur Web

Accessible via HTTP POST. Idéal pour les clients IA distants ou les intégrations web.

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

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

Middlewares habituels :

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

Serveur local

Commande Artisan. Pour les clients IA locaux comme Claude Desktop.

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

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

Le client MCP démarre habituellement la commande automatiquement. Pas besoin d’exécuter mcp:start manuellement.

Tools

Fonctions appelables par le client IA (accès aux données, appel d’API, opérations DB…).

Créer un tool

php artisan make:mcp-tool CurrentWeatherTool

Ajoutez-le à $tools du serveur.

use App\Mcp\Tools\CurrentWeatherTool;
use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    protected array $tools = [
        CurrentWeatherTool::class,
    ];
}

Implémentation :

<?php

namespace App\Mcp\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;

#[Description('Fetches the current weather forecast for a specified location.')]
class CurrentWeatherTool extends Tool
{
    public function handle(Request $request): Response
    {
        $location = $request->get('location');

        // Récupérer la météo...

        return Response::text('The weather is sunny, 22°C.');
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('The location to get the weather for.')
                ->required(),
        ];
    }
}

Nom et description

Nom et titre déduits du nom de classe (CurrentWeatherTool → current-weather / Current Weather Tool). Personnalisez avec Name et Title.

use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Title;

#[Name('get-optimistic-weather')]
#[Title('Get Optimistic Weather Forecast')]
class CurrentWeatherTool extends Tool
{
    // ...
}

La description (Description) n’est pas auto-générée. Elle est essentielle pour que le modèle comprenne l’usage — soignez-la.

Schéma d’entrée

schema() définit les paramètres via le builder de schéma JSON.

public function schema(JsonSchema $schema): array
{
    return [
        'location' => $schema->string()
            ->description('The location to get the weather for.')
            ->required(),

        'units' => $schema->string()
            ->enum(['celsius', 'fahrenheit'])
            ->description('The temperature units to use.')
            ->default('celsius'),
    ];
}

Schéma de sortie

outputSchema() structure la réponse, facilitant l’analyse par le client.

public function outputSchema(JsonSchema $schema): array
{
    return [
        'temperature' => $schema->number()
            ->description('Temperature in Celsius')
            ->required(),

        'conditions' => $schema->string()
            ->description('Weather conditions')
            ->required(),

        'humidity' => $schema->integer()
            ->description('Humidity percentage')
            ->required(),
    ];
}

Validation

Utilisez la validation Laravel standard dans handle().

public function handle(Request $request): Response
{
    $validated = $request->validate([
        'location' => 'required|string|max:100',
        'units' => 'in:celsius,fahrenheit',
    ], [
        'location.required' => 'You must specify a location. For example, "New York City" or "Tokyo".',
        'units.in' => 'You must specify either "celsius" or "fahrenheit" for the units.',
    ]);

    // Utilisez les données validées...
}

Les messages d’erreur sont retournés au client IA, qui peut alors reformuler l’appel.

Types de réponse

Response::text(), Response::error(), Response::json(), Response::structured().

return Response::text('Simple text response');

return Response::error('Something went wrong');

return Response::json(['data' => $data]);

return Response::structured([
    'temperature' => 22,
    'conditions' => 'sunny',
    'humidity' => 60,
]);

Notifications et pagination

Pour de longs traitements, envoyez des notifications de progression :

public function handle(Request $request): Response
{
    $this->notify('progress', ['step' => 1, 'total' => 3]);

    // Traitement...

    return Response::text('Done');
}

Resources

Données/contexte lisible par le client.

Créer une resource

php artisan make:mcp-resource WeatherGuidelinesResource

Ajoutez-la à $resources.

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

Implémentation :

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Resource;

#[Description('Guidelines for interpreting weather data.')]
class WeatherGuidelinesResource extends Resource
{
    public function handle(): Response
    {
        return Response::text(file_get_contents(
            resource_path('mcp/weather-guidelines.md')
        ));
    }
}

Prompts

Templates de prompts réutilisables.

Créer un prompt

php artisan make:mcp-prompt DescribeWeatherPrompt

Ajoutez-le à $prompts.

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

Implémentation :

<?php

namespace App\Mcp\Prompts;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Prompt;

#[Description('Prompt for describing weather conditions.')]
class DescribeWeatherPrompt extends Prompt
{
    public function handle(Request $request): Response
    {
        $location = $request->get('location');

        return Response::text("Describe the weather in {$location} using vivid imagery.");
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('Location for the weather description')
                ->required(),
        ];
    }
}

Authentification et autorisation

Un serveur web MCP peut utiliser les middlewares standard.

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

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

Dans un tool, contrôlez les droits :

public function handle(Request $request): Response
{
    if (! $request->user()->can('view-weather')) {
        return Response::error('Unauthorized');
    }

    // ...
}

Tests

Utilisez TestServer pour tester votre serveur MCP.

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Testing\TestServer;

test('current weather tool returns weather', function () {
    $server = new TestServer(WeatherServer::class);

    $response = $server->tool('current-weather', [
        'location' => 'Tokyo',
    ]);

    $response->assertSuccessful();
    $response->assertContains('sunny');
});

Testez schémas et validation :

$server = new TestServer(WeatherServer::class);

$response = $server->tool('current-weather', []);

$response->assertFailed();
$response->assertContains('location is required');

Récapitulatif

Composants principaux

Composant	Rôle
Server	Point d’entrée MCP
Tool	Fonction appelable par le client IA
Resource	Données lisibles par le client
Prompt	Template de prompt réutilisable

Web vs Local

Web (Mcp::web) : HTTP POST, clients distants ou intégrations web
Local (Mcp::local) : Commande Artisan, clients IA locaux (Claude Desktop, etc.)

Bonnes pratiques

Une description claire pour chaque tool
Schémas d’entrée avec enum / required / default pour orienter l’agent
Retournez des outputSchema structurés quand pertinent
Utilisez la validation Laravel pour renvoyer des erreurs compréhensibles
Testez avec TestServer

​Qu’est-ce que MCP

​Installation

​Créer un serveur

​Enregistrer le serveur

​Serveur Web

​Serveur local

​Tools

​Créer un tool

​Nom et description

​Schéma d’entrée

​Schéma de sortie

​Validation

​Types de réponse

​Notifications et pagination

​Resources

​Créer une resource

​Prompts

​Créer un prompt

​Authentification et autorisation

​Tests

​Récapitulatif

Qu’est-ce que MCP

Installation

Créer un serveur

Enregistrer le serveur

Serveur Web

Serveur local

Tools

Créer un tool

Nom et description

Schéma d’entrée

Schéma de sortie

Validation

Types de réponse

Notifications et pagination

Resources

Créer une resource

Prompts

Créer un prompt

Authentification et autorisation

Tests

Récapitulatif