Laravel MCP - Knowledge of Laravel

Qu’est-ce que MCP ?

Le Model Context Protocol (MCP) est une spécification qui définit un protocole standardisé pour la communication entre des clients IA (Claude, Cursor, GitHub Copilot, etc.) et une application. En implémentant un serveur MCP, un agent IA peut accéder aux données de votre application Laravel ou y exécuter des actions.

Laravel MCP est un package officiel introduit dans Laravel 13. Distribué sous le nom laravel/mcp, il fournit tout le nécessaire pour construire un serveur MCP.

Un serveur MCP peut exposer trois types de fonctionnalités.

Fonctionnalité	Description
Tools	Fonctions appelables par le client IA : recherche, mise à jour, intégration à une API externe, etc.
Resources	Données ou informations de contexte lisibles par le client IA
Prompts	Templates de prompts réutilisables

Installation

Installez le package avec Composer.

composer require laravel/mcp

Puis exécutez la commande Artisan vendor:publish pour générer le fichier routes/ai.php.

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

Cette commande crée routes/ai.php, où vous déclarez vos serveurs MCP.

Création d’un serveur

Générez la classe de serveur avec la commande make:mcp-server.

php artisan make:mcp-server WeatherServer

La classe est créée dans le répertoire 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

Une fois la classe créée, déclarez-la dans routes/ai.php. Deux modes sont disponibles : serveur Web et serveur local.

Serveur Web

Un serveur Web est accessible via une requête HTTP POST. Il convient parfaitement aux clients IA distants et aux intégrations Web.

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

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

Vous pouvez y appliquer des middlewares comme sur n’importe quelle route.

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

Serveur local

Un serveur local s’exécute comme une commande Artisan. Il est destiné aux clients IA locaux comme Claude Desktop.

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

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

Les serveurs locaux sont généralement lancés automatiquement par le client MCP. Inutile d’exécuter mcp:start à la main.

Tools

Les tools sont les fonctions que le client IA peut appeler : lecture de données, intégration à une API externe, opérations en base, etc.

Créer un tool

Générez la classe avec la commande Artisan make:mcp-tool.

php artisan make:mcp-tool CurrentWeatherTool

Enregistrez-la dans la propriété $tools du serveur.

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

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

Voici un exemple d’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ération des données 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 du tool

Le nom et le titre sont générés par défaut à partir du nom de classe. Pour CurrentWeatherTool, le nom devient current-weather et le titre Current Weather Tool. Personnalisez-les via les attributs 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 d’un tool (Description) n’est pas générée automatiquement. Elle est indispensable pour que le modèle comprenne comment utiliser le tool : fournissez toujours une description explicite.

Schéma d’entrée

La méthode schema définit le schéma des paramètres d’entrée. Le builder JSON schema de Laravel permet d’exprimer types et contraintes.

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 définit la structure de la réponse, ce qui facilite son parsing par le client IA.

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 standard de Laravel 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.',
    ]);

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

Après un échec de validation, le client IA réessaiera en s’appuyant sur le message d’erreur. Fournissez des messages précis et exploitables.

Injection de dépendances

Les tools sont résolus via le service container Laravel : vous pouvez donc type-hinter des dépendances dans le constructeur ou dans handle.

<?php

namespace App\Mcp\Tools;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    public function handle(Request $request, WeatherRepository $weather): Response
    {
        $location = $request->get('location');
        $forecast = $weather->getForecastFor($location);

        return Response::text("Forecast: {$forecast}");
    }
}

Annotations

Vous pouvez ajouter des annotations aux tools pour informer le client IA sur leur comportement.

use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tool;

#[IsIdempotent]
#[IsReadOnly]
class CurrentWeatherTool extends Tool
{
    // ...
}

Annotation	Description
`#[IsReadOnly]`	Indique que le tool ne modifie pas son environnement
`#[IsDestructive]`	Indique que le tool peut effectuer des mises à jour destructrices
`#[IsIdempotent]`	Indique qu’un appel répété avec les mêmes arguments n’a pas d’effets secondaires
`#[IsOpenWorld]`	Indique que le tool peut interagir avec des entités externes

Enregistrement conditionnel

En implémentant shouldRegister, vous décidez à l’exécution si un tool doit être exposé.

public function shouldRegister(Request $request): bool
{
    return $request?->user()?->subscribed() ?? false;
}

En renvoyant false, le tool est masqué aux clients IA.

Réponses

Un tool doit retourner une instance de Laravel\Mcp\Response.

Réponse texte

return Response::text('Weather Summary: Sunny, 22°C');

Réponse d'erreur

return Response::error('Unable to fetch weather data. Please try again.');

Réponse image / audio

return Response::image(file_get_contents(storage_path('weather/radar.png')), 'image/png');

return Response::audio(file_get_contents(storage_path('weather/alert.mp3')), 'audio/mp3');

// Lecture directe depuis le storage (le type MIME est détecté)
return Response::fromStorage('weather/radar.png');

Réponse multi-contenu

public function handle(Request $request): array
{
    return [
        Response::text('Weather Summary: Sunny, 22°C'),
        Response::text("**Detailed Forecast**\n- Morning: 18°C\n- Afternoon: 25°C"),
    ];
}

Réponse structurée

Renvoie une donnée structurée facilement analysable par le client IA.

return Response::structured([
    'temperature' => 22.5,
    'conditions' => 'Partly cloudy',
    'humidity' => 65,
]);

Réponse en streaming

Envoie l’avancement en temps réel pour les traitements longs.

public function handle(Request $request): Generator
{
    $locations = $request->array('locations');

    foreach ($locations as $index => $location) {
        yield Response::notification('processing/progress', [
            'current' => $index + 1,
            'total' => count($locations),
            'location' => $location,
        ]);

        yield Response::text($this->forecastFor($location));
    }
}

Prompts

Les prompts sont des templates réutilisables. Ils permettent d’offrir aux clients IA des requêtes prêtes à l’emploi pour dialoguer avec le modèle de langage.

Créer un prompt

php artisan make:mcp-prompt DescribeWeatherPrompt

Enregistrez-le dans la propriété $prompts du serveur.

use App\Mcp\Prompts\DescribeWeatherPrompt;

class WeatherServer extends Server
{
    protected array $prompts = [
        DescribeWeatherPrompt::class,
    ];
}

Arguments d’un prompt

Déclarez les paramètres du prompt via arguments.

<?php

namespace App\Mcp\Prompts;

use Laravel\Mcp\Server\Prompt;
use Laravel\Mcp\Server\Prompts\Argument;

class DescribeWeatherPrompt extends Prompt
{
    public function arguments(): array
    {
        return [
            new Argument(
                name: 'tone',
                description: 'The tone to use in the weather description (e.g., formal, casual, humorous).',
                required: true,
            ),
        ];
    }
}

Validation

Les arguments d’un prompt sont validés automatiquement d’après leur définition, mais vous pouvez appliquer des règles plus complexes. Laravel MCP s’intègre nativement à la validation de Laravel. Validez les arguments à l’intérieur du handle du prompt.

<?php

namespace App\Mcp\Prompts;

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

class DescribeWeatherPrompt extends Prompt
{
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'tone' => 'required|string|max:50',
        ]);

        $tone = $validated['tone'];

        // Générer le prompt avec le ton spécifié...
    }
}

En cas d’échec, le client IA réessaiera à partir du message : fournissez des messages précis et exploitables.

$validated = $request->validate([
    'tone' => ['required', 'string', 'max:50'],
], [
    'tone.*' => 'Veuillez indiquer un ton. Exemples : "formal", "casual", "humorous".',
]);

Injection de dépendances

Les prompts étant résolus via le service container, vous pouvez type-hinter des dépendances dans le constructeur ou dans handle.

<?php

namespace App\Mcp\Prompts;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Prompt;

class DescribeWeatherPrompt extends Prompt
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}
}

handle accepte également des types injectés automatiquement.

public function handle(Request $request, WeatherRepository $weather): Response
{
    $isAvailable = $weather->isServiceAvailable();

    // ...
}

Enregistrement conditionnel

En implémentant shouldRegister, vous décidez à l’exécution si le prompt doit être exposé.

<?php

namespace App\Mcp\Prompts;

use Laravel\Mcp\Request;
use Laravel\Mcp\Server\Prompt;

class CurrentWeatherPrompt extends Prompt
{
    public function shouldRegister(Request $request): bool
    {
        return $request?->user()?->subscribed() ?? false;
    }
}

Renvoyer false rend le prompt invisible et non-invocable pour le client IA.

Réponse d’un prompt

Un handle de prompt peut renvoyer des messages utilisateur ou assistant. Utilisez asAssistant() pour marquer un message comme provenant de l’assistant.

<?php

namespace App\Mcp\Prompts;

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

class DescribeWeatherPrompt extends Prompt
{
    public function handle(Request $request): array
    {
        $tone = $request->string('tone');

        $systemMessage = "You are a helpful weather assistant. Please provide a weather description in a {$tone} tone.";
        $userMessage = 'What is the current weather like in Tokyo?';

        return [
            Response::text($systemMessage)->asAssistant(),
            Response::text($userMessage),
        ];
    }
}

Resources

Les resources sont des données ou informations que le client IA peut charger comme contexte : documentation, configuration, données dynamiques… tout ce qui améliore la qualité des réponses de l’IA.

Créer une resource

php artisan make:mcp-resource WeatherGuidelinesResource

Enregistrez-la dans la propriété $resources.

use App\Mcp\Resources\WeatherGuidelinesResource;

class WeatherServer extends Server
{
    protected array $resources = [
        WeatherGuidelinesResource::class,
    ];
}

<?php

namespace App\Mcp\Resources;

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

#[Description('Comprehensive guidelines for using the Weather API.')]
class WeatherGuidelinesResource extends Resource
{
    public function handle(Request $request): Response
    {
        $guidelines = "# Weather API Guidelines\n\n- Always specify a location...";

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

URI et type MIME

Par défaut, l’URI est déduite du nom de classe (par exemple weather://resources/weather-guidelines). Personnalisez-les via Uri et MimeType.

use Laravel\Mcp\Server\Attributes\MimeType;
use Laravel\Mcp\Server\Attributes\Uri;
use Laravel\Mcp\Server\Resource;

#[Uri('weather://resources/guidelines')]
#[MimeType('application/pdf')]
class WeatherGuidelinesResource extends Resource
{
    // ...
}

Resource templates

Pour définir une resource dynamique dont l’URI contient des variables, implémentez l’interface HasUriTemplate.

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Attributes\MimeType;
use Laravel\Mcp\Server\Contracts\HasUriTemplate;
use Laravel\Mcp\Server\Resource;
use Laravel\Mcp\Support\UriTemplate;

#[Description('Access user files by ID')]
#[MimeType('text/plain')]
class UserFileResource extends Resource implements HasUriTemplate
{
    public function uriTemplate(): UriTemplate
    {
        return new UriTemplate('file://users/{userId}/files/{fileId}');
    }

    public function handle(Request $request): Response
    {
        $userId = $request->get('userId');
        $fileId = $request->get('fileId');

        // Récupérer et renvoyer le contenu du fichier...

        return Response::text("File {$fileId} for user {$userId}");
    }
}

Les variables de l’URI sont automatiquement injectées dans la requête et récupérables via get.

Requête d’une resource

Contrairement aux tools et aux prompts, les resources ne définissent pas de schéma d’entrée ni d’arguments. Vous accédez néanmoins aux informations de la requête via l’objet Request dans handle.

<?php

namespace App\Mcp\Resources;

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

class WeatherGuidelinesResource extends Resource
{
    public function handle(Request $request): Response
    {
        // Accéder aux informations de la requête...
    }
}

Injection de dépendances pour les resources

Les resources étant résolues via le service container, vous pouvez type-hinter des dépendances dans le constructeur ou dans handle.

<?php

namespace App\Mcp\Resources;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}
}

handle accepte également des types injectés.

public function handle(WeatherRepository $weather): Response
{
    return Response::text($weather->guidelines());
}

Annotations de resource

Les resources peuvent porter des annotations d’audience, de priorité, de date de dernière modification, etc.

use Laravel\Mcp\Enums\Role;
use Laravel\Mcp\Server\Annotations\Audience;
use Laravel\Mcp\Server\Annotations\LastModified;
use Laravel\Mcp\Server\Annotations\Priority;
use Laravel\Mcp\Server\Resource;

#[Audience(Role::User)]
#[LastModified('2025-01-12T15:00:58Z')]
#[Priority(0.9)]
class UserDashboardResource extends Resource
{
    // ...
}

Annotation	Type	Description
`#[Audience]`	Role ou tableau	Audience cible (`Role::User`, `Role::Assistant`, ou les deux)
`#[Priority]`	float	Score d’importance (0.0 à 1.0)
`#[LastModified]`	string	Date de dernière modification au format ISO 8601

Enregistrement conditionnel d’une resource

En implémentant shouldRegister, vous décidez à l’exécution si la resource doit être exposée.

<?php

namespace App\Mcp\Resources;

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

class WeatherGuidelinesResource extends Resource
{
    public function shouldRegister(Request $request): bool
    {
        return $request?->user()?->subscribed() ?? false;
    }
}

Renvoyer false rend la resource invisible et non-accessible.

Réponse d’une resource

Une resource doit retourner une instance de Laravel\Mcp\Response. Pour un contenu texte, utilisez text.

return Response::text($weatherData);

Réponse de type resource link

Utilisez resourceLink pour retourner un lien de resource. Contrairement à une resource embarquée, il fournit un pointeur URI que le client IA récupérera de manière indépendante.

return Response::resourceLink(
    uri: 'file:///data/report.json',
    name: 'monthly-report',
    mimeType: 'application/json',
);

Vous pouvez aussi passer directement une classe ou une instance de resource enregistrée : URI, nom, titre, description et MIME type seront hérités.

return Response::resourceLink(new WeatherForecastResource);

Réponse Blob

Pour un contenu binaire, utilisez blob. Le type MIME est défini via l’attribut #[MimeType] de la resource.

return Response::blob(file_get_contents(storage_path('weather/radar.png')));

#[MimeType('image/png')]
class WeatherGuidelinesResource extends Resource
{
    // ...
}

Réponse d’erreur

Pour signaler une erreur, utilisez error.

return Response::error('Impossible de récupérer les données météo pour ce lieu.');

Apps

Laravel MCP prend en charge les MCP Apps, une extension du protocole permettant à un tool de rendre une application HTML interactive dans une iframe sandbox à l’intérieur d’un hôte compatible. Cela ouvre la voie à des tableaux de bord, des formulaires, des visualisations et autres expériences riches qui vont bien au-delà d’une simple réponse texte. Une MCP App est composée de deux éléments :

App resource — retourne le HTML auto-suffisant de l’application.
Tool — associé à l’app resource via l’attribut #[RendersApp]. Lorsque le tool est appelé, l’hôte récupère la resource associée et la rend.

Créer une app resource

La commande Artisan make:mcp-app-resource crée une app resource.

php artisan make:mcp-app-resource WeatherDashboardApp

Elle crée deux fichiers : une classe PHP dans app/Mcp/Resources et une vue Blade dans resources/views/mcp. Le nom de la vue est déduit du nom de la classe : WeatherDashboardApp correspond à mcp.weather-dashboard-app.

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\AppMeta;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\AppResource;

#[Description('An interactive weather dashboard.')]
#[AppMeta]
class WeatherDashboardApp extends AppResource
{
    /**
     * Handle the app resource request.
     */
    public function handle(Request $request): Response
    {
        return Response::view('mcp.weather-dashboard-app', [
            'title' => $this->title(),
        ]);
    }
}

AppResource hérite de la classe de base Resource et configure automatiquement le schéma d’URI ui:// et le type MIME text/html;profile=mcp-app exigés par la spécification MCP Apps. Comme n’importe quelle resource, elle doit être déclarée dans le tableau $resources du serveur. La vue Blade générée utilise le composant <x-mcp::app>, qui produit un document HTML complet incluant le SDK MCP côté client.

<x-mcp::app :title="$title">
    <x-slot:head>
        <script type="module">
        createMcpApp(async (app) => {
            document.getElementById('run-btn').addEventListener('click', async () => {
                const result = await app.callServerTool('get-weather-data', {});
                document.getElementById('output').textContent = result.content[0]?.text ?? '';
            });
        });
        </script>
    </x-slot:head>

    <div id="app">
        <button id="run-btn">Refresh</button>
        <p id="output"></p>
    </div>
</x-mcp::app>

La fonction globale createMcpApp fournie par le SDK gère la connexion de l’iframe au serveur, l’application du thème de l’hôte et expose des helpers comme callServerTool, sendMessage, openLink, ainsi que des callbacks d’événements. Pour l’API cliente complète, référez-vous à la spécification MCP Apps.

Rendre une app depuis un tool

Pour afficher une app resource, liez un tool à celle-ci via l’attribut #[RendersApp]. Quand le tool est appelé, Laravel MCP inclut l’URI de la resource dans les métadonnées du tool afin que l’hôte puisse rendre l’app dans une iframe sandbox.

<?php

namespace App\Mcp\Tools;

use App\Mcp\Resources\WeatherDashboardApp;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\RendersApp;
use Laravel\Mcp\Server\Tool;

#[RendersApp(resource: WeatherDashboardApp::class)]
class ShowWeatherDashboard extends Tool
{
    /**
     * Handle the tool request.
     */
    public function handle(Request $request): Response
    {
        return Response::text('Weather dashboard loaded.');
    }
}

Dès qu’une AppResource est enregistrée, Laravel MCP annonce automatiquement la capability io.modelcontextprotocol/ui. Aucune configuration serveur supplémentaire n’est requise.

Visibilité des tools d’app

Chaque tool #[RendersApp] peut restreindre ses appelants via l’argument visibility. C’est utile pour masquer au modèle les tools privés que l’UI utilise en interne pour charger ou actualiser des données.

use Laravel\Mcp\Server\Attributes\RendersApp;
use Laravel\Mcp\Server\Ui\Enums\Visibility;

#[RendersApp(resource: WeatherDashboardApp::class, visibility: [Visibility::App])]
class GetWeatherData extends Tool
{
    // ...
}

L’enum Visibility a deux valeurs, Model et App ; par défaut les deux sont actives. Utilisez [Visibility::App] pour une action backend appelée uniquement par l’UI, et [Visibility::Model] pour empêcher l’UI de l’utiliser.

Configuration d’une app

L’attribut #[AppMeta] de l’app resource permet de configurer la Content Security Policy de l’iframe, les autorisations du navigateur et les bibliothèques à inclure dans le <head>.

use Laravel\Mcp\Server\Attributes\AppMeta;
use Laravel\Mcp\Server\Ui\Enums\Library;
use Laravel\Mcp\Server\Ui\Enums\Permission;

#[AppMeta(
    connectDomains: ['https://api.weather.com'],
    permissions: [Permission::Geolocation],
    libraries: [Library::Tailwind, Library::Alpine],
)]
class WeatherDashboardApp extends AppResource
{
    // ...
}

L’enum Library inclut les scripts CDN de bibliothèques front populaires comme Library::Tailwind ou Library::Alpine, dont l’origine CDN est ajoutée automatiquement à la CSP. L’enum Permission couvre les autorisations navigateur : Camera, Microphone, Geolocation, ClipboardWrite, etc.

Pour une configuration dynamique, surchargez la méthode appMeta de la resource en utilisant les builders fluent AppMeta, Csp et Permissions de l’espace de noms Laravel\Mcp\Server\Ui.

Développement d’app avec Boost

Laravel MCP inclut une référence Boost dédiée à la création de MCP Apps. Si Laravel Boost est installé, un agent de code IA peut invoquer la skill mcp-development pour générer automatiquement l’app resource, la vue Blade et le tool associé. Pour la référence complète du protocole (API cliente, détails de schéma…), consultez la documentation officielle MCP Apps.

Métadonnées

Vous pouvez ajouter le champ _meta de la spécification MCP aux réponses des tools, resources et prompts.

// Métadonnées sur le contenu de la réponse
return Response::text('The weather is sunny.')
    ->withMeta(['source' => 'weather-api', 'cached' => true]);

Pour attacher des métadonnées à l’enveloppe complète de la réponse, utilisez Response::make.

return Response::make(
    Response::text('The weather is sunny.')
)->withMeta(['request_id' => '12345']);

Pour associer des métadonnées à la classe même du tool, de la resource ou du prompt, définissez la propriété $meta.

class CurrentWeatherTool extends Tool
{
    protected ?array $meta = [
        'version' => '2.0',
        'author' => 'Weather Team',
    ];
}

Icônes

Les clients MCP peuvent afficher des icônes pour le serveur et ses primitives. Utilisez l’attribut Icon pour déclarer des icônes sur un serveur, un tool, une resource ou un prompt.

use Laravel\Mcp\Enums\IconTheme;
use Laravel\Mcp\Server\Attributes\Icon;

#[Icon('mcp/server.png', mimeType: 'image/png', sizes: ['48x48'])]
#[Icon('mcp/server-dark.svg', theme: IconTheme::Dark)]
class WeatherServer extends Server
{
    // ...
}

L’attribut Icon est répétable : vous pouvez donc en déclarer plusieurs pour différentes tailles ou pour les variantes light / dark. Vous pouvez également définir les icônes de manière programmatique en surchargeant la méthode icons. C’est utile quand elles dépendent de conditions d’exécution.

use Laravel\Mcp\Schema\Icon;

class CurrentWeatherTool extends Tool
{
    /**
     * Retourne les icônes du tool.
     *
     * @return array<int, Icon>
     */
    public function icons(): array
    {
        return [
            Icon::from('mcp/tool.png', mimeType: 'image/png'),
        ];
    }
}

Les icônes définies via attribut et via la méthode icons sont fusionnées automatiquement. Le chemin est résolu ainsi :

Un chemin avec un schéma d’URI (https:, data:, etc.) est utilisé tel quel.
Un chemin relatif est transformé en URL via le helper asset de Laravel.

Authentification

Les serveurs Web s’authentifient via les middlewares standard de Laravel.

Sanctum

Authentification par jeton avec Laravel Sanctum. Le client MCP envoie un en-tête Authorization: Bearer <token>.

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

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

OAuth 2.1

Authentification OAuth via Laravel Passport. Recommandée lorsque vous avez besoin d’une sécurité renforcée.

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

Mcp::oauthRoutes();

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

Publiez la vue d’autorisation de Passport et configurez-la dans un service provider.

php artisan vendor:publish --tag=mcp-views

// AppServiceProvider::boot()
use Laravel\Passport\Passport;

Passport::authorizationView(function ($parameters) {
    return view('mcp.authorize', $parameters);
});

Autorisation

$request->user() renvoie l’utilisateur authentifié, ce qui permet d’appliquer des vérifications d’autorisation dans les tools et resources.

public function handle(Request $request): Response
{
    if (! $request->user()->can('read-weather')) {
        return Response::error('Permission denied.');
    }

    // Continuer le traitement...
}

Client MCP

Laravel MCP fournit aussi un client pour se connecter à d’autres serveurs MCP. Grâce à lui, vous pouvez découvrir et invoquer les tools exposés par un serveur MCP externe. C’est particulièrement utile pour donner à un agent IA accès à un serveur MCP externe.

Se connecter à un serveur

Pour un serveur MCP accessible en HTTP, utilisez Client::web en lui passant l’URL.

use Laravel\Mcp\Client;

$client = Client::web('https://mcp.example.com');

Pour un serveur MCP local qui se lance comme une commande, utilisez Client::local en indiquant la commande et ses arguments.

use Laravel\Mcp\Client;

$client = Client::local('php', ['artisan', 'mcp:start']);

Le client se connecte de manière paresseuse (lazy connect) : la connexion est établie automatiquement à la première demande de tools ou au premier appel. Pour un contrôle manuel, utilisez connect, connected, ping et disconnect.

$client->connect();

$client->ping();

if ($client->connected()) {
    // ...
}

$client->disconnect();

withTimeout personnalise le timeout de requête.

$client = Client::web('https://mcp.example.com')->withTimeout(30);

Clients nommés

Plutôt que de construire un client à chaque fois, enregistrez un client nommé réutilisable. Cela se fait généralement dans la méthode boot d’un service provider via la façade Mcp.

use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;

Mcp::registerClient('github', fn () => Client::web('https://mcp.example.com'));

Une fois enregistré, résolvez-le par son nom.

use Laravel\Mcp\Facades\Mcp;

$client = Mcp::client('github');

Un client nommé est résolu une seule fois par requête et se déconnecte automatiquement à la fin du cycle de la requête.

Authentification du client

Pour un serveur MCP Web protégé par un jeton Bearer, utilisez withToken. Vous pouvez passer une chaîne ou une closure résolue paresseusement.

use Illuminate\Support\Facades\Auth;
use Laravel\Mcp\Client;

$client = Client::web('https://mcp.example.com')->withToken($token);

$client = Client::web('https://mcp.example.com')->withToken(
    fn () => Auth::user()->mcpToken(),
);

Pour un serveur protégé par OAuth 2.1, utilisez withOAuth.

use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;

Mcp::registerClient('github', fn () => Client::web('https://mcp.example.com')->withOAuth(
    clientId: config('services.github_mcp.client_id'),
    clientSecret: config('services.github_mcp.client_secret'),
));

Si le serveur MCP prend en charge l’enregistrement dynamique de client, clientId et clientSecret peuvent être omis : le client s’enregistrera lui-même.

Enregistrez ensuite les routes OAuth du client nommé dans routes/ai.php via oAuthRoutesFor. La closure passée reçoit le nom du client et un TokenSet après l’échange du code d’autorisation contre l’access token.

use Illuminate\Support\Facades\Auth;
use Laravel\Mcp\Client\OAuth\TokenSet;
use Laravel\Mcp\Facades\Mcp;

Mcp::oAuthRoutesFor('github', function (string $client, TokenSet $token) {
    Auth::user()->update([
        'github_mcp_token' => $token->accessToken,
    ]);

    return redirect('/dashboard');
});

Deux routes nommées sont enregistrées : la route de connexion (mcp.oauth.{client}.connect) qui redirige l’utilisateur vers le serveur d’autorisation, et la route callback (mcp.oauth.{client}.callback) qui échange le code puis appelle le handler. Toutes deux utilisent le groupe de middleware web (surchargeable via l’argument middleware). Pour démarrer le flux d’autorisation, redirigez l’utilisateur vers la route de connexion.

return redirect()->route('mcp.oauth.github.connect');

Tools

tools renvoie les tools exposés par le serveur, sous forme de collection indexée par nom.

use Laravel\Mcp\Facades\Mcp;

$tools = Mcp::client('github')->tools();

foreach ($tools as $tool) {
    $tool->name;
    $tool->title;
    $tool->description;
    $tool->inputSchema;
}

Le client gère automatiquement la pagination pour récupérer l’ensemble. L’argument limit restreint le nombre de résultats.

$tools = Mcp::client('github')->tools(limit: 10);

Pour invoquer un tool, utilisez callTool en indiquant son nom et ses arguments. L’instance ToolResult retournée expose la réponse.

use Laravel\Mcp\Facades\Mcp;

$result = Mcp::client('github')->callTool('current-weather', [
    'location' => 'New York',
]);

$result->text();             // contenu texte
(string) $result;            // équivalent à text()
$result->isError;            // le tool a-t-il signalé une erreur ?
$result->structuredContent;  // contenu structuré (si présent)

Vous pouvez aussi invoquer directement un tool depuis l’instance retournée par la liste.

$tools = Mcp::client('github')->tools();

$result = $tools['current-weather']->call([
    'location' => 'New York',
]);

Si vous construisez un agent avec le Laravel AI SDK, passez directement les tools du client MCP à l’agent : le modèle pourra les invoquer en cours de génération. Consultez la section outils MCP de l’AI SDK pour plus de détails.

Prompts

prompts renvoie les prompts exposés par le serveur sous forme de collection indexée par nom.

use Laravel\Mcp\Facades\Mcp;

$prompts = Mcp::client('github')->prompts();

foreach ($prompts as $prompt) {
    $prompt->name;
    $prompt->title;
    $prompt->description;
    $prompt->arguments;
}

La pagination est automatique. limit restreint le nombre de résultats.

$prompts = Mcp::client('github')->prompts(limit: 10);

Pour récupérer un prompt, utilisez getPrompt avec son nom et ses arguments. L’instance PromptResult retournée expose les messages générés.

use Laravel\Mcp\Facades\Mcp;

$result = Mcp::client('github')->getPrompt('describe-weather', [
    'location' => 'New York',
]);

$result->text();        // contenu texte des messages
(string) $result;       // équivalent à text()
$result->messages;      // messages bruts renvoyés par le prompt
$result->description;   // description du prompt (si présente)

Resources

resources renvoie les resources exposées par le serveur, indexées par URI.

use Laravel\Mcp\Facades\Mcp;

$resources = Mcp::client('github')->resources();

foreach ($resources as $resource) {
    $resource->uri;
    $resource->name;
    $resource->title;
    $resource->description;
    $resource->mimeType;
    $resource->size;
}

La pagination est automatique. limit restreint le nombre de résultats.

$resources = Mcp::client('github')->resources(limit: 10);

Pour lire une resource, utilisez readResource en passant son URI. L’instance ResourceReadResult retournée expose son contenu.

use Laravel\Mcp\Facades\Mcp;

$result = Mcp::client('github')->readResource('weather://guidelines');

$result->content();   // contenu (le blob base64 est décodé automatiquement)
(string) $result;     // équivalent à content()
$result->mimeType();  // type MIME (si présent)
$result->contents;    // contenus bruts renvoyés

Tests

MCP Inspector

Pour tester le comportement d’un serveur MCP, utilisez l’outil de debug interactif « MCP Inspector ».

# Serveur Web
php artisan mcp:inspector mcp/weather

# Serveur local (dont le nom est "weather")
php artisan mcp:inspector weather

L’exécution démarre MCP Inspector et vous permet de copier la configuration client. Si un middleware d’authentification est actif, incluez un en-tête Authorization à la connexion.

Tests unitaires

Vous pouvez écrire des tests unitaires pour les tools, les resources et les prompts.

test('tool', function () {
    $response = WeatherServer::tool(CurrentWeatherTool::class, [
        'location' => 'Tokyo',
        'units' => 'celsius',
    ]);

    $response
        ->assertOk()
        ->assertSee('The current weather in Tokyo is 22°C and sunny.');
});

public function test_tool(): void
{
    $response = WeatherServer::tool(CurrentWeatherTool::class, [
        'location' => 'Tokyo',
        'units' => 'celsius',
    ]);

    $response
        ->assertOk()
        ->assertSee('The current weather in Tokyo is 22°C and sunny.');
}

Les prompts et resources se testent de la même manière.

$response = WeatherServer::prompt(DescribeWeatherPrompt::class, ['tone' => 'casual']);
$response = WeatherServer::resource(WeatherGuidelinesResource::class);

Pour simuler un utilisateur authentifié, utilisez actingAs.

$response = WeatherServer::actingAs($user)->tool(CurrentWeatherTool::class, [...]);

Les assertions les plus utiles :

$response->assertOk();           // vérifie l'absence d'erreur
$response->assertSee('...');     // vérifie la présence d'un texte donné

Pour vérifier la présence ou l’absence d’erreurs, utilisez assertHasErrors / assertHasNoErrors.

$response->assertHasErrors();

$response->assertHasErrors([
    'Something went wrong.',
]);

$response->assertHasNoErrors();

Vous pouvez également vérifier le nom, le titre ou la description d’un tool, d’une resource ou d’un prompt.

$response->assertName('current-weather');
$response->assertTitle('Current Weather Tool');
$response->assertDescription('Fetches the current weather forecast for a specified location.');

Pour vérifier les notifications d’une réponse en streaming, utilisez assertSentNotification et assertNotificationCount.

$response->assertSentNotification('processing/progress', [
    'step' => 1,
    'total' => 5,
]);

$response->assertSentNotification('processing/progress', [
    'step' => 2,
    'total' => 5,
]);

$response->assertNotificationCount(5);

Pour déboguer le contenu d’une réponse, utilisez dd ou dump.

$response->dd();
$response->dump();

​Qu’est-ce que MCP ?

​Installation

​Création d’un serveur

​Enregistrer le serveur

​Serveur Web

​Serveur local

​Tools

​Créer un tool

​Nom et description du tool

​Schéma d’entrée

​Schéma de sortie

​Validation

​Injection de dépendances

​Annotations

​Enregistrement conditionnel

​Réponses

​Prompts

​Créer un prompt

​Arguments d’un prompt

​Validation

​Injection de dépendances

​Enregistrement conditionnel

​Réponse d’un prompt

​Resources

​Créer une resource

​URI et type MIME

​Resource templates

​Requête d’une resource

​Injection de dépendances pour les resources

​Annotations de resource

​Enregistrement conditionnel d’une resource

​Réponse d’une resource

​Réponse de type resource link

​Réponse Blob

​Réponse d’erreur

​Apps

​Créer une app resource

​Rendre une app depuis un tool

​Visibilité des tools d’app

​Configuration d’une app

​Développement d’app avec Boost

​Métadonnées

​Icônes

​Authentification

​Sanctum

​OAuth 2.1

​Autorisation

​Client MCP

​Se connecter à un serveur

​Clients nommés

​Authentification du client

​Tools

​Prompts

​Resources

​Tests

​MCP Inspector

​Tests unitaires

Qu’est-ce que MCP ?

Installation

Création d’un serveur

Enregistrer le serveur

Serveur Web

Serveur local

Tools

Créer un tool

Nom et description du tool

Schéma d’entrée

Schéma de sortie

Validation

Injection de dépendances

Annotations

Enregistrement conditionnel

Réponses

Prompts

Créer un prompt

Arguments d’un prompt

Validation

Injection de dépendances

Enregistrement conditionnel

Réponse d’un prompt

Resources

Créer une resource

URI et type MIME

Resource templates

Requête d’une resource

Injection de dépendances pour les resources

Annotations de resource

Enregistrement conditionnel d’une resource

Réponse d’une resource

Réponse de type resource link

Réponse Blob

Réponse d’erreur

Apps

Créer une app resource

Rendre une app depuis un tool

Visibilité des tools d’app

Configuration d’une app

Développement d’app avec Boost

Métadonnées

Icônes

Authentification

Sanctum

OAuth 2.1

Autorisation

Client MCP

Se connecter à un serveur

Clients nommés

Authentification du client

Tools

Prompts

Resources

Tests

MCP Inspector

Tests unitaires