Les agents IA Laravel prennent en charge les serveurs MCP

Aperçu

En juin 2026, le blog officiel Laravel a annoncé qu’un agent IA construit avec le Laravel AI SDK peut désormais se connecter à un serveur MCP (Model Context Protocol). Jusqu’ici, Laravel MCP proposait de « publier une application Laravel en tant que serveur MCP ». La nouveauté fonctionne dans l’autre sens : une application Laravel peut désormais se comporter comme un client MCP et se connecter à d’autres serveurs MCP.

Pour les détails sur le protocole MCP lui-même, consultez la documentation de Laravel MCP. Cette page se concentre sur la fonctionnalité client.

Pourquoi implémenter cela dans Laravel MCP plutôt que dans l’AI SDK ?

MCP est un protocole large : négociation de transport, handshake, flux d’authentification, etc. L’implémenter directement dans l’AI SDK empêcherait de le réutiliser dans des cas où l’on souhaite dialoguer avec un serveur MCP sans agent (jobs de queue, commandes console…). L’équipe Laravel a donc scindé la fonctionnalité en deux.

laravel/mcp : le client MCP proprement dit, chargé de la connexion, de la négociation, de l’authentification et des appels d’outils.
laravel/ai : une fine couche d’intégration permettant à l’agent d’utiliser ce client depuis tools() sans friction.

Chacun peut être utilisé indépendamment, et leur combinaison rend les outils d’un serveur MCP indiscernables d’outils écrits à la main du point de vue de l’agent.

Se connecter à un serveur MCP

Les deux modes de transport sont pris en charge : serveur STDIO lancé en processus local et serveur distant via HTTP.

use Laravel\Mcp\Client;

// Serveur local (STDIO)
$client = Client::local('npx', ['-y', '@modelcontextprotocol/puppeteer']);
$tools = $client->tools();

// Serveur distant (Streamable HTTP)
$client = Client::web('https://nightwatch.laravel.com/mcp');
$tools = $client->tools();

La connexion, le handshake et la négociation de version sont pris en charge par le client. Côté application, il suffit d’appeler tools().

Authentification

Jeton Bearer

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

OAuth

De nombreux serveurs MCP hébergés — comme Nightwatch — exigent OAuth. Enregistrez un client nommé dans un service provider.

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

Mcp::registerClient('nightwatch', fn () =>
    Client::web('https://nightwatch.laravel.com/mcp')->withOAuth()
);

Câblez ensuite les routes OAuth et le callback.

use Laravel\Mcp\Facades\Mcp;
use Laravel\Mcp\Client\OAuth\TokenSet;

Mcp::oAuthRoutesFor('nightwatch', function (string $provider, TokenSet $token) {
    auth()->user()->update([
        'mcp_nightwatch_token' => encrypt($token->accessToken),
        'mcp_nightwatch_refresh' => encrypt($token->refreshToken),
    ]);

    return redirect('/dashboard');
}, middleware: 'auth');

Cela génère la route mcp.oauth.nightwatch.connect ainsi que la route de callback correspondante. Il ne reste qu’à ajouter un bouton de connexion côté Blade.

<a href="{{ route('mcp.oauth.nightwatch.connect') }}">
    Connect Nightwatch
</a>

Lorsque l’utilisateur se connecte puis autorise l’application, la closure de callback reçoit le jeton. Aucune manipulation manuelle des URL de redirection ni de PKCE n’est nécessaire. Pour des traitements d’arrière-plan sans intervention utilisateur, un flux client_credentials est également disponible.

$token = Mcp::client('billing')->oAuthClient()->clientCredentials();

Intégration à un agent

Le point clé est que la méthode tools() de l’agent reste inchangée : on peut y intégrer des outils MCP.

use Laravel\Mcp\Facades\Mcp;
use App\Tools\SendSlackMessage;

class SupportAgent extends Agent
{
    public function instructions(): string
    {
        return 'You help triage production issues.';
    }

    public function tools(): array
    {
        return [
            ...Mcp::client('nightwatch')
                ->withToken(auth()->user()->mcp_nightwatch_token)
                ->tools(),
            new SendSlackMessage,
        ];
    }
}

Laravel AI détecte automatiquement que les éléments du tableau tools() sont des outils MCP et les enveloppe pour respecter le contrat des outils de l’agent. Le schéma d’entrée MCP est converti en un schéma JSON Laravel ; lorsque le modèle appelle un outil, l’appel distant est effectué, puis le résultat est normalisé avant d’être renvoyé. Les erreurs, les données structurées, le texte brut ou les mises à jour en streaming sont pris en charge automatiquement : aucun détail MCP ne remonte dans le code de l’agent. Vous pouvez même mélanger plusieurs transports au sein d’un même agent.

public function tools(): array
{
    return [
        ...Mcp::client('nightwatch')->tools(),
        ...Client::local('npx', ['-y', '@modelcontextprotocol/server-puppeteer'])->tools(),
        new SendSlackMessage,
    ];
}

Mieux encore, les classes d’outils écrites pour votre propre serveur Laravel MCP peuvent être transmises directement à l’agent, sans passer par un client. Vous pouvez donc réutiliser un même outil à la fois pour l’exposition publique et pour votre agent.

use App\Mcp\Tools\CurrentWeatherTool;

public function tools(): array
{
    return [
        new CurrentWeatherTool,
        new SendSlackMessage,
    ];
}

Mettre en cache la liste des outils

La récupération de la liste des outils implique un aller-retour avec le serveur. C’est particulièrement coûteux avec les serveurs distants OAuth, et inutile à chaque prompt puisque la liste évolue rarement : c’est un bon candidat au cache.

public function tools(): array
{
    $tools = Cache::remember('mcp.nightwatch.tools', now()->addHour(), fn () =>
        Mcp::client('nightwatch')->tools()
    );

    return [...$tools, new SendSlackMessage];
}

Les outils MCP étant retournés sous forme de données brutes, ils restent fonctionnels après restauration depuis le cache.

Tests

Même sans serveur MCP actif, vous pouvez tester un agent grâce aux fakes de Laravel AI. Les noms des outils MCP suivent la convention mcp_tools_<name> : un outil nommé search apparaît donc sous le nom mcp_tools_search.

use Laravel\Ai\Responses\Data\ToolCall;

SupportAgent::fake([
    new ToolCall('call_1', 'mcp_tools_search', ['query' => 'laravel']),
    'Found the issue.',
]);

$response = (new SupportAgent)->prompt('Find the latest error');

expect($response->toolCalls)->toHaveCount(1);
expect($response->toolResults->first()->result)->toContain('Found');

La boucle normale de l’agent reste active ; seul le texte du modèle est fixé par le fake. L’appel d’outil traverse bien la couche MCP réelle, ce qui permet de tester le même chemin qu’en production sans aucun accès réseau.

Périmètre actuel

Cette première version prend en charge à la fois les transports STDIO et Streamable HTTP, ainsi que les outils et les prompts. L’authentification par jeton Bearer et OAuth est disponible. Le périmètre continuera de s’étendre au fil de l’évolution du protocole MCP lui-même.

Pages associées

Créer un provider personnalisé pour l'AI SDK

Comment implémenter un provider personnalisé pour un service d’IA non pris en charge nativement.

Introduction à Laravel Nightwatch

Présentation du service de monitoring hébergé Nightwatch utilisé en exemple dans cet article.

Changelog

Laravel 13

Produits

Présentation des packages

Étude de nouveaux dépôts

Guides de mise à jour

Authentification

Frontend

Configuration de l'environnement

Les agents IA Laravel prennent en charge les serveurs MCP

Aperçu

Pourquoi implémenter cela dans Laravel MCP plutôt que dans l’AI SDK ?

Se connecter à un serveur MCP

Authentification

Jeton Bearer

OAuth

Intégration à un agent

Mettre en cache la liste des outils

Tests

Périmètre actuel

Pages associées

Créer un provider personnalisé pour l'AI SDK

Introduction à Laravel Nightwatch

​Aperçu

​Pourquoi implémenter cela dans Laravel MCP plutôt que dans l’AI SDK ?

​Se connecter à un serveur MCP

​Authentification

​Jeton Bearer

​OAuth

​Intégration à un agent

​Mettre en cache la liste des outils

​Tests

​Périmètre actuel

​Pages associées

Créer un provider personnalisé pour l'AI SDK

Introduction à Laravel Nightwatch

Aperçu

Pourquoi implémenter cela dans Laravel MCP plutôt que dans l’AI SDK ?

Se connecter à un serveur MCP

Authentification

Jeton Bearer

OAuth

Intégration à un agent

Mettre en cache la liste des outils

Tests

Périmètre actuel

Pages associées