> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Les agents IA Laravel prennent en charge les serveurs MCP

> Découvrez la fonctionnalité client MCP ajoutée au Laravel AI SDK et à Laravel MCP. Vous pouvez désormais intégrer directement les outils d'un serveur MCP dans la méthode tools() de vos agents.

## Aperçu

En juin 2026, le [blog officiel Laravel](https://laravel.com/blog/laravel-ai-agents-now-support-mcp-servers) 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.

<Info>
  Pour les détails sur le protocole MCP lui-même, consultez la [documentation de Laravel MCP](https://laravel.com/docs/mcp). Cette page se concentre sur la fonctionnalité client.
</Info>

## 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.

```mermaid theme={null}
graph LR
    A["laravel/mcp<br>Client MCP"] --> B["Connexion, authentification, handshake"]
    C["laravel/ai<br>Fine couche d'intégration"] --> D["Ajout direct des outils MCP<br>à tools() de l'agent"]
    A --> C
```

* **`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.

```php theme={null}
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

```php theme={null}
$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.

```php theme={null}
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.

```php theme={null}
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.

```blade theme={null}
<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.

```php theme={null}
$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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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`.

```php theme={null}
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

<CardGroup cols={2}>
  <Card title="Créer un provider personnalisé pour l'AI SDK" href="/fr/advanced/ai-sdk-custom-provider" icon="plug">
    Comment implémenter un provider personnalisé pour un service d'IA non pris en charge nativement.
  </Card>

  <Card title="Introduction à Laravel Nightwatch" href="/fr/blog/nightwatch-introduction" icon="binoculars">
    Présentation du service de monitoring hébergé Nightwatch utilisé en exemple dans cet article.
  </Card>
</CardGroup>


## Related topics

- [Créer un agent personnalisé pour Boost](/fr/advanced/boost-custom-agent.md)
- [Mises à jour Laravel — juin 2026](/fr/blog/changelog/202606.md)
- [Guide de mise à niveau de Laravel 12 vers 13](/fr/blog/upgrade-12-to-13.md)
- [Blog](/fr/blog/index.md)
- [Laravel MCP](/fr/mcp.md)