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

# Gli agenti AI di Laravel supportano i server MCP

> Approfondiamo la funzionalità di client MCP aggiunta a Laravel AI SDK e Laravel MCP. Ora puoi integrare direttamente nei tools() dell'agente i tool esposti da un server MCP.

## Panoramica

Nel giugno 2026, sul [blog ufficiale di Laravel](https://laravel.com/blog/laravel-ai-agents-now-support-mcp-servers) è 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**".

<Info>
  Per il funzionamento di MCP nel dettaglio consulta la [documentazione di Laravel MCP](https://laravel.com/docs/mcp). In questa pagina ci concentriamo sulla funzionalità di client.
</Info>

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

```mermaid theme={null}
graph LR
    A["laravel/mcp<br>client MCP"] --> B["connessione, autenticazione, handshake"]
    C["laravel/ai<br>sottile layer di integrazione"] --> D["Aggiungi i tool MCP<br>direttamente in tools() dell'agente"]
    A --> C
```

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

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

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

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

```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');
```

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

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

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

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

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

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

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

```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');
```

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

<CardGroup cols={2}>
  <Card title="Creare un provider personalizzato per l'AI SDK" href="/it/advanced/ai-sdk-custom-provider" icon="plug">
    Come implementare un provider personalizzato per servizi AI non supportati di serie
  </Card>

  <Card title="Introduzione a Laravel Nightwatch" href="/it/blog/nightwatch-introduction" icon="binoculars">
    Approfondimento sul servizio di monitoring ospitato Nightwatch usato come esempio in questo articolo
  </Card>
</CardGroup>


## Related topics

- [Gli agenti AI passano dal codice "corretto" al codice "idiomatico Laravel" — la prossima mossa di Boost Benchmarks](/it/blog/boost-benchmarks-idiomatic-laravel.md)
- [Laravel MCP](/it/mcp.md)
- [Aggiornamenti Laravel di giugno 2026](/it/blog/changelog/202606.md)
- [Laravel e lo sviluppo con AI](/it/ai.md)
- [Blog](/it/blog/index.md)