Gli agenti AI di Laravel supportano i server MCP

Panoramica

Nel giugno 2026, sul blog ufficiale di Laravel è stato annunciato che gli agenti AI costruiti con Laravel AI SDK possono ora connettersi a server MCP (Model Context Protocol). Fino ad ora Laravel MCP offriva la possibilità di “esporre un’app Laravel come server MCP”; ciò che è stato aggiunto è la direzione opposta, cioè “un’app Laravel che si connette ad altri server MCP come client”.

Per il funzionamento di MCP nel dettaglio consulta la documentazione di Laravel MCP. In questa pagina ci concentriamo sulla funzionalità di client.

Perché non è stato implementato direttamente nell’AI SDK, ma in Laravel MCP

MCP è un protocollo che copre parecchio: negoziazione del trasporto, handshake, flussi di autenticazione. Implementarlo direttamente dentro l’AI SDK avrebbe impedito il riuso nei casi in cui vuoi parlare con un server MCP senza un agente (ad esempio da un job in coda o da un comando console). Per questo il team di Laravel ha diviso la funzionalità in due parti.

laravel/mcp: il client MCP vero e proprio, che gestisce connessione, negoziazione, autenticazione e chiamata dei tool.
laravel/ai: un sottile layer di integrazione che permette all’agente di usare quel client dal metodo tools() senza attriti.

Ciascuno funziona anche da solo; combinati, ti permettono di trattare i tool di un server MCP allo stesso modo di quelli scritti a mano.

Connessione a un server MCP

Sono supportati sia server STDIO avviati come processo locale sia server remoti via HTTP.

use Laravel\Mcp\Client;

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

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

Connessione, handshake e negoziazione della versione di protocollo sono gestiti tutti dal client, quindi dal lato applicativo devi solo chiamare tools().

Autenticazione

Bearer token

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

OAuth

Molti server MCP ospitati (come Nightwatch) richiedono OAuth. Registra un client con nome nel service provider.

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

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

Collega le route OAuth e la gestione della 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');

Vengono così generati mcp.oauth.nightwatch.connect e la corrispondente route di callback. Nella view Blade basta un pulsante di connessione.

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

Quando l’utente effettua il login e approva, la closure di callback riceve il token. Non devi gestire manualmente URL di redirect o dettagli PKCE. Per elaborazioni in background senza intervento dell’utente è disponibile anche il grant client credentials.

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

Integrazione nell’agente

Il punto più interessante è che puoi mescolare tool MCP nel metodo tools() dell’agente senza modificarne la struttura.

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 rileva che dentro l’array tools() ci sono tool MCP e li avvolge in modo che rispettino il contract dei tool dell’agente. Converte lo schema di input MCP nello schema JSON di Laravel, effettua la chiamata remota quando il modello invoca il tool e normalizza il risultato. Errori, dati strutturati, testo semplice e aggiornamenti streaming vengono gestiti automaticamente, così i dettagli di MCP non trapelano nel codice dell’agente. Puoi anche mescolare più trasporti in un unico agente.

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

Inoltre, le classi tool scritte per il tuo server Laravel MCP possono essere passate direttamente all’agente senza connessione client. Puoi riutilizzare lo stesso tool sia per l’esposizione esterna sia per l’agente.

use App\Mcp\Tools\CurrentWeatherTool;

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

Cache della lista dei tool

Ottenere la lista dei tool implica un round trip al server. Con i server remoti via OAuth in particolare, richiamarla ad ogni prompt è uno spreco. Poiché la lista dei tool non cambia spesso, si presta bene al caching.

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

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

I tool MCP tornano come dato semplice, quindi funzionano anche quando vengono ripristinati dalla cache.

Test

Anche senza un server MCP realmente in esecuzione, puoi testare l’agente con le funzionalità di fake di Laravel AI. I nomi dei tool MCP seguono la convenzione mcp_tools_<nome>, quindi un tool chiamato search appare come 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');

Il normale ciclo dell’agente continua a funzionare e solo le “battute” del modello sono decise dalla fake. Le chiamate dei tool passano davvero attraverso il layer MCP, così puoi testare lo stesso percorso di produzione senza rete.

Ambito supportato al momento

Con questa prima release sono supportati tool e prompt su entrambi i trasporti STDIO e Streamable HTTP. Per l’autenticazione sono supportati Bearer token e OAuth. Con l’evoluzione di MCP, la copertura è destinata ad ampliarsi.

Pagine correlate

Creare un provider personalizzato per l'AI SDK

Come implementare un provider personalizzato per servizi AI non supportati di serie

Introduzione a Laravel Nightwatch

Approfondimento sul servizio di monitoring ospitato Nightwatch usato come esempio in questo articolo

Changelog

Laravel 13

Prodotti

Presentazione dei pacchetti

Analisi di nuovi repository

Guide di aggiornamento

Autenticazione

Frontend

Configurazione dell'ambiente

Gli agenti AI di Laravel supportano i server MCP

Panoramica

Perché non è stato implementato direttamente nell’AI SDK, ma in Laravel MCP

Connessione a un server MCP

Autenticazione

Bearer token

OAuth

Integrazione nell’agente

Cache della lista dei tool

Test

Ambito supportato al momento

Pagine correlate

Creare un provider personalizzato per l'AI SDK

Introduzione a Laravel Nightwatch

​Panoramica

​Perché non è stato implementato direttamente nell’AI SDK, ma in Laravel MCP

​Connessione a un server MCP

​Autenticazione

​Bearer token

​OAuth

​Integrazione nell’agente

​Cache della lista dei tool

​Test

​Ambito supportato al momento

​Pagine correlate

Creare un provider personalizzato per l'AI SDK

Introduzione a Laravel Nightwatch

Panoramica

Perché non è stato implementato direttamente nell’AI SDK, ma in Laravel MCP

Connessione a un server MCP

Autenticazione

Bearer token

OAuth

Integrazione nell’agente

Cache della lista dei tool

Test

Ambito supportato al momento

Pagine correlate