Laravel MCP - Knowledge of Laravel

Cos’è MCP

Model Context Protocol (MCP) è la specifica che permette ai client AI (Claude, Cursor, GitHub Copilot ecc.) e alle applicazioni di comunicare tramite un protocollo standardizzato. Implementando un server MCP, gli agenti AI possono accedere ai dati della tua applicazione Laravel ed eseguire azioni.

Laravel MCP è il pacchetto ufficiale aggiunto in Laravel 13. È distribuito come laravel/mcp e fornisce tutto ciò che serve per costruire un server MCP.

Un server MCP può offrire principalmente tre tipi di funzionalità.

Funzionalità	Descrizione
Tool	Funzioni che il client AI può invocare: ricerca, aggiornamento, integrazione con API esterne ecc.
Risorse	Dati e informazioni di contesto che il client AI può leggere
Prompt	Template di prompt riutilizzabili

Installazione

Installa il pacchetto tramite Composer.

composer require laravel/mcp

Dopo l’installazione, esegui il comando Artisan vendor:publish per generare il file routes/ai.php.

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

Il comando crea routes/ai.php, dove registrerai i server MCP.

Creare un server

Genera la classe server con il comando Artisan make:mcp-server.

php artisan make:mcp-server WeatherServer

La classe viene generata in 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,
    ];
}

Registrare il server

Dopo aver creato il server, registralo in routes/ai.php. Ci sono due modalità: server Web e server locale.

Server Web

Il server Web è accessibile tramite richieste HTTP POST. Ideale per client AI remoti o integrazioni web-based.

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

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

Puoi applicare middleware come per le route normali.

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

Server locale

Il server locale funziona come comando Artisan. Si usa per integrarsi con client AI locali come Claude Desktop.

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

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

Il server locale viene di solito avviato automaticamente dal client MCP. Non devi eseguire manualmente il comando Artisan mcp:start.

Tool

I tool sono funzioni invocabili dal client AI. Puoi implementare recupero dati, integrazione con API esterne, operazioni sul database ecc.

Creare un tool

Genera la classe tool con il comando Artisan make:mcp-tool.

php artisan make:mcp-tool CurrentWeatherTool

Registra il tool creato nella proprietà $tools del server.

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

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

Esempio di implementazione di base.

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

        // ottieni i dati meteo...

        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(),
        ];
    }
}

Nome e descrizione del tool

Dal nome della classe vengono ricavati automaticamente nome e titolo di default. CurrentWeatherTool diventa current-weather come nome e Current Weather Tool come titolo. Puoi personalizzarli con gli attributi Name e 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 descrizione (Description) del tool non viene generata automaticamente. È indispensabile affinché il modello capisca come usare il tool: forniscine sempre una significativa.

Schema di input

Definisci lo schema dei parametri di input nel metodo schema. Con il JSON schema builder di Laravel puoi indicare tipi e vincoli.

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'),
    ];
}

Schema di output

Con outputSchema puoi definire la struttura della risposta, rendendola più facile da analizzare per il client AI.

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(),
    ];
}

Validazione

All’interno di handle puoi usare la validazione standard di Laravel.

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

    // usa i dati validati...
}

In caso di errore di validazione, il client AI riproverà usando il messaggio di errore come indicazione. Fornisci messaggi specifici e azionabili.

Dependency injection

I tool sono risolti attraverso il service container di Laravel, quindi puoi usare hint di tipo nel costruttore o in 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}");
    }
}

Annotazioni

Aggiungendo annotazioni al tool, comunichi al client AI informazioni supplementari sul suo comportamento.

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
{
    // ...
}

Le annotazioni disponibili sono:

Annotazione	Descrizione
`#[IsReadOnly]`	Indica che il tool non modifica lo stato
`#[IsDestructive]`	Indica che il tool potrebbe fare update distruttivi
`#[IsIdempotent]`	Indica che chiamate ripetute con gli stessi argomenti non producono effetti collaterali
`#[IsOpenWorld]`	Indica che il tool potrebbe interagire con entità esterne

Registrazione condizionale

Implementando shouldRegister puoi registrare condizionalmente il tool a runtime.

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

Restituendo false, il tool non sarà visibile al client AI.

Risposta

Un tool deve restituire un’istanza di Laravel\Mcp\Response.

Risposta testuale

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

Risposta di errore

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

Risposta immagine / 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');

// legge direttamente dallo storage (MIME type auto-rilevato)
return Response::fromStorage('weather/radar.png');

Più contenuti nella risposta

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"),
    ];
}

Risposta strutturata

Restituisce dati strutturati facili da analizzare per il client AI.

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

Risposta in streaming

Per elaborazioni lunghe, invia aggiornamenti in tempo reale.

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));
    }
}

Prompt

I prompt sono template riutilizzabili. Ti permettono di offrire in forma standardizzata query “boilerplate” che il client AI usa quando dialoga con il language model.

Creare un prompt

php artisan make:mcp-prompt DescribeWeatherPrompt

Registralo nella proprietà $prompts del server.

use App\Mcp\Prompts\DescribeWeatherPrompt;

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

Argomenti del prompt

Definisci i parametri nel metodo 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,
            ),
        ];
    }
}

Validazione

Gli argomenti del prompt vengono validati automaticamente in base alla definizione, ma puoi applicare regole più complesse. Laravel MCP si integra pienamente con la validazione di Laravel. Puoi validare gli argomenti dentro handle.

<?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'];

        // genera il prompt con il tono indicato...
    }
}

In caso di errore di validazione, il client AI riprova usando il messaggio. Fornisci messaggi specifici e azionabili.

$validated = $request->validate([
    'tone' => ['required', 'string', 'max:50'],
], [
    'tone.*' => 'Specifica il tono. Es.: "formal", "casual", "humorous".',
]);

Dependency injection

I prompt sono risolti dal service container di Laravel, quindi puoi usare hint di tipo nel costruttore o in 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,
    ) {}
}

Anche handle accetta type hint, risolti automaticamente dal service container.

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

    // ...
}

Registrazione condizionale

Implementa shouldRegister per registrare il prompt condizionalmente a runtime.

<?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;
    }
}

Restituendo false, il prompt non è più visibile né invocabile dal client AI.

Risposta del prompt

In handle puoi restituire messaggi utente e messaggi assistente. Con asAssistant() marchi il messaggio come proveniente dall’assistente.

<?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),
        ];
    }
}

Risorse

Le risorse sono dati e informazioni che il client AI può leggere come contesto. Documentazione, dati di configurazione, dati dinamici: informazioni che migliorano la qualità delle risposte dell’AI.

Creare una risorsa

php artisan make:mcp-resource WeatherGuidelinesResource

Registrala nella proprietà $resources del server.

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 e MIME type

Per default l’URI viene generato dal nome della classe (es. weather://resources/weather-guidelines). Puoi personalizzarlo con gli attributi Uri e 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
{
    // ...
}

Template di risorse

Per definire risorse dinamiche con variabili nell’URI, implementa l’interfaccia 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');

        // recupera e restituisci il contenuto del file...

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

Le variabili dall’URI vengono passate automaticamente nella richiesta e le recuperi con get.

Richiesta della risorsa

A differenza di tool e prompt, le risorse non definiscono schema o argomenti di input. Tuttavia, in handle puoi accedere alle informazioni della richiesta tramite l’oggetto request.

<?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
    {
        // accedi alle informazioni della richiesta...
    }
}

Dependency injection nelle risorse

Anche le risorse sono risolte dal service container, quindi puoi usare hint di tipo in costruttore o 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,
    ) {}
}

Anche handle accetta type hint, risolti automaticamente.

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

Annotazioni delle risorse

Le risorse possono avere annotazioni come audience, priorità e data di ultima modifica.

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
{
    // ...
}

Annotazione	Tipo	Descrizione
`#[Audience]`	Role o array	Audience target (`Role::User`, `Role::Assistant` o entrambi)
`#[Priority]`	float	Punteggio di importanza (0.0-1.0)
`#[LastModified]`	string	Data e ora di ultima modifica in formato ISO 8601

Registrazione condizionale delle risorse

Implementa shouldRegister per registrare condizionalmente la risorsa a runtime.

<?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;
    }
}

Restituendo false, la risorsa non è visibile né accessibile dal client AI.

Risposta della risorsa

La risorsa deve restituire un’istanza di Laravel\Mcp\Response. Per contenuti testuali usa text.

return Response::text($weatherData);

Risposta con link a risorsa

Con resourceLink restituisci un puntatore URI a una risorsa; a differenza della risorsa embedded, il client la recupera autonomamente.

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

Puoi passare anche una classe o istanza di risorsa già registrata; URI, nome, titolo, descrizione e MIME type vengono ereditati automaticamente.

return Response::resourceLink(new WeatherForecastResource);

Risposta blob

Per contenuti binari usa blob. Il MIME type si imposta con l’attributo #[MimeType] della risorsa.

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

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

Risposta di errore

Per segnalare un errore usa error.

return Response::error('Impossibile recuperare i dati meteo per la posizione indicata.');

App

Laravel MCP supporta le MCP Apps. È un’estensione del Model Context Protocol che permette a un tool di far renderizzare un’applicazione HTML interattiva dentro un iframe sandbox nel client host che la supporta. Così puoi costruire dashboard, form, visualizzazioni ed esperienze ricche che vanno oltre la semplice risposta testuale. Una MCP App si compone di due parti che lavorano insieme.

App resource — restituisce l’HTML autosufficiente dell’applicazione.
Tool — con l’attributo #[RendersApp] viene collegato all’app resource. Quando il tool viene invocato, l’host recupera e renderizza la risorsa collegata.

Creare un’app resource

Puoi generare un’app resource con il comando Artisan make:mcp-app-resource.

php artisan make:mcp-app-resource WeatherDashboardApp

Il comando crea due file: la classe PHP in app/Mcp/Resources e la view Blade in resources/views/mcp. Il nome della view è dedotto dal nome della classe; ad esempio WeatherDashboardApp è mappato a 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 estende Resource e imposta automaticamente lo schema URI ui:// e il MIME type text/html;profile=mcp-app richiesti dalla specifica MCP Apps. Come le altre risorse, va registrata nell’array $resources del server. La view Blade generata usa il componente <x-mcp::app>. Il componente renderizza un documento HTML completo con l’SDK MCP lato client incluso.

<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 funzione globale createMcpApp è fornita dall’SDK bundled. Gestisce la connessione dell’iframe al server, l’applicazione del tema host, ed espone helper come callServerTool, sendMessage, openLink e le callback degli eventi. Per l’API client completa consulta la specifica MCP Apps.

Renderizzare un’app da un tool

Per mostrare un’app resource, colleghi il tool con l’attributo #[RendersApp]. Quando il tool viene invocato, Laravel MCP include l’URI della risorsa nei metadati del tool, in modo che l’host possa renderizzarla nell’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.');
    }
}

Quando registri un AppResource, Laravel MCP annuncia automaticamente la capability io.modelcontextprotocol/ui. Non serve altra configurazione del server.

Visibilità dei tool app

Ogni tool #[RendersApp] può limitare i propri invocatori con l’argomento visibility. È utile per rendere invisibili al modello i tool privati usati dalla UI per caricare/aggiornare dati.

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 ha due casi, Model e App; il default è entrambi. Usa [Visibility::App] per azioni di backend chiamate direttamente dalla UI e [Visibility::Model] per rendere il tool inaccessibile alla UI.

Configurazione dell’app

Con l’attributo #[AppMeta] sulla risorsa configuri la Content Security Policy dell’iframe, i permessi del browser e gli script delle librerie inclusi nel <head> della view.

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 include preconfigurati gli script CDN delle librerie frontend comuni come Library::Tailwind e Library::Alpine; le origini CDN vengono unite automaticamente al CSP. L’enum Permission copre permessi del browser come Camera, Microphone, Geolocation, ClipboardWrite.

Se serve una configurazione dinamica, usa i fluent builder AppMeta, Csp e Permissions nel namespace Laravel\Mcp\Server\Ui sovrascrivendo il metodo appMeta della risorsa.

Sviluppo di app con Boost

Laravel MCP include una skill reference Boost dedicata alla costruzione di MCP Apps. Se hai installato Laravel Boost, l’agente di coding AI può richiamare la skill mcp-development per generare automaticamente app resource, view Blade e tool collegati. Per il reference completo del protocollo (API client, schemi ecc.) consulta la documentazione ufficiale MCP Apps.

Metadata

Puoi allegare il campo _meta della specifica MCP alle risposte di tool, risorse e prompt.

// metadata sul contenuto della risposta
return Response::text('The weather is sunny.')
    ->withMeta(['source' => 'weather-api', 'cached' => true]);

Per allegare metadata all’intero envelope della risposta usa Response::make.

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

Per associare metadata alle classi stesse (tool/risorse/prompt), definisci la proprietà $meta.

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

Icone

I client MCP possono mostrare le icone del server e delle sue primitive. Con l’attributo Icon puoi dichiarare icone su server, tool, risorse e 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’attributo Icon è ripetibile, quindi puoi dichiarare più icone per fornire varianti in dimensione o per tema chiaro/scuro. In alternativa, puoi definire le icone programmaticamente sovrascrivendo il metodo icons. Utile quando l’icona dipende da condizioni a runtime.

use Laravel\Mcp\Schema\Icon;

class CurrentWeatherTool extends Tool
{
    /**
     * Restituisce le icone del tool.
     *
     * @return array<int, Icon>
     */
    public function icons(): array
    {
        return [
            Icon::from('mcp/tool.png', mimeType: 'image/png'),
        ];
    }
}

Le icone definite dagli attributi e dal metodo icons vengono unite automaticamente. I path vengono risolti così:

Path con schemi URI come https: o data: vengono usati così come sono.
I path relativi vengono risolti in URL tramite l’helper asset di Laravel.

Autenticazione

I server Web possono essere autenticati con i normali middleware di Laravel.

Sanctum

Autenticazione a token con Laravel Sanctum. Il client MCP invia l’header 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

Autenticazione OAuth con Laravel Passport. Adatta quando serve maggiore robustezza di sicurezza.

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

Mcp::oauthRoutes();

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

Se usi OAuth, pubblica la view di autorizzazione di Passport e configurala nel service provider.

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

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

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

Autorizzazione

Con $request->user() ottieni l’utente autenticato ed effettui i controlli di autorizzazione dentro tool o risorse.

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

    // prosegui...
}

Client MCP

Laravel MCP non offre solo la costruzione di server, ma anche un client per connettersi ad altri server MCP. Con il client puoi scoprire e invocare i tool esposti da server MCP esterni. È particolarmente utile per fornire ad agenti AI le funzionalità di un server MCP esterno.

Connessione a un server

Per server MCP accessibili via HTTP usa Client::web passando l’URL del server.

use Laravel\Mcp\Client;

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

Per un server MCP locale avviato come comando, usa Client::local con comando e argomenti.

use Laravel\Mcp\Client;

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

Il client fa lazy connect: apre effettivamente la connessione quando fai la prima chiamata (list o call di tool). Per gestire manualmente la connessione ci sono connect, connected, ping, disconnect.

$client->connect();

$client->ping();

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

$client->disconnect();

Con withTimeout personalizzi il timeout delle richieste.

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

Client con nome

Invece di costruire il client ogni volta, puoi registrare client con nome riutilizzabili. Di solito nel metodo boot di un service provider, tramite la facade Mcp.

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

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

Dopo la registrazione risolvi il client per nome.

use Laravel\Mcp\Facades\Mcp;

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

Un client con nome è risolto una sola volta per richiesta e viene disconnesso automaticamente a fine ciclo.

Autenticazione del client

Per connetterti a un server Web MCP protetto da Bearer token usa withToken. Puoi passare una stringa o una closure per la risoluzione lazy.

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(),
);

Per server protetti con OAuth 2.1 usa 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'),
));

Se il server MCP supporta la registrazione dinamica del client, puoi omettere clientId e clientSecret: il client si registra da solo.

Poi nel file routes/ai.php registri le route OAuth del client con nome tramite oAuthRoutesFor. La closure passata riceve nome del client e TokenSet dopo lo scambio del codice di autorizzazione con 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');
});

Vengono così registrate due route con nome: la route di connect (mcp.oauth.{client}.connect) che reindirizza l’utente al server di autorizzazione, e la route di callback (mcp.oauth.{client}.callback) che scambia il codice e chiama l’handler. Entrambe usano il gruppo di middleware web (sovrascrivibile con l’argomento middleware). Per avviare il flusso di autorizzazione, reindirizza l’utente alla route di connect.

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

Tool

Con tools ottieni i tool esposti dal server MCP, come collection con il nome come chiave.

use Laravel\Mcp\Facades\Mcp;

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

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

Il client gestisce automaticamente la paginazione recuperando tutti i tool. Con l’argomento limit limiti il numero.

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

Per invocare un tool usa callTool con nome e array di argomenti. Ottieni la risposta dall’istanza ToolResult.

use Laravel\Mcp\Facades\Mcp;

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

$result->text();             // contenuto testuale della risposta
(string) $result;            // equivalente a text()
$result->isError;            // il tool ha segnalato un errore?
$result->structuredContent;  // contenuto strutturato (se presente)

Puoi anche invocare direttamente dall’istanza tool ottenuta dall’elenco.

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

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

Se stai costruendo agenti con Laravel AI SDK, puoi passare i tool del client MCP direttamente all’agente, così il modello può invocarli mentre risponde al prompt. Per i dettagli vedi la sezione tool MCP dell’AI SDK.

Prompt

Con prompts ottieni i prompt esposti dal server, come collection con il nome come chiave.

use Laravel\Mcp\Facades\Mcp;

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

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

Il client gestisce la paginazione automaticamente; con limit puoi limitare.

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

Per ottenere un prompt usa getPrompt con nome e array di argomenti. Il PromptResult restituito contiene i messaggi generati.

use Laravel\Mcp\Facades\Mcp;

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

$result->text();        // contenuto testuale del messaggio
(string) $result;       // equivalente a text()
$result->messages;      // messaggi restituiti dal prompt (raw)
$result->description;   // descrizione del prompt (se presente)

Risorse

Con resources ottieni le risorse esposte dal server, come collection con l’URI come chiave.

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;
}

Il client gestisce la paginazione automaticamente; con limit puoi limitare.

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

Per leggere una risorsa usa readResource con l’URI. Il ResourceReadResult restituito espone il contenuto.

use Laravel\Mcp\Facades\Mcp;

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

$result->content();   // contenuto della risorsa (i blob base64 vengono decodificati)
(string) $result;     // equivalente a content()
$result->mimeType();  // MIME type della risorsa (se presente)
$result->contents;    // contenuti restituiti dalla risorsa (raw)

Test

MCP Inspector

Per verificare il comportamento del server MCP usa il tool interattivo di debug “MCP Inspector”.

# server Web
php artisan mcp:inspector mcp/weather

# server locale (se il nome è "weather")
php artisan mcp:inspector weather

L’esecuzione avvia MCP Inspector e ti permette di copiare la configurazione client. Se hai configurato middleware di autenticazione, connettiti includendo l’header Authorization.

Unit test

Puoi scrivere unit test per tool, risorse e prompt.

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.');
}

Prompt e risorse si testano allo stesso modo.

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

Per eseguire come utente autenticato usa actingAs.

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

Le principali asserzioni:

$response->assertOk();           // verifica assenza di errori
$response->assertSee('...');     // verifica presenza di un certo testo

Per verificare presenza/assenza di errori usa assertHasErrors / assertHasNoErrors.

$response->assertHasErrors();

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

$response->assertHasNoErrors();

Puoi verificare nome, titolo e descrizione di tool, risorse e prompt.

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

Per verificare le notification di una risposta streaming usa assertSentNotification e assertNotificationCount.

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

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

$response->assertNotificationCount(5);

Per fare debug del contenuto della risposta usa dd o dump.

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

​Cos’è MCP

​Installazione

​Creare un server

​Registrare il server

​Server Web

​Server locale

​Tool

​Creare un tool

​Nome e descrizione del tool

​Schema di input

​Schema di output

​Validazione

​Dependency injection

​Annotazioni

​Registrazione condizionale

​Risposta

​Prompt

​Creare un prompt

​Argomenti del prompt

​Validazione

​Dependency injection

​Registrazione condizionale

​Risposta del prompt

​Risorse

​Creare una risorsa

​URI e MIME type

​Template di risorse

​Richiesta della risorsa

​Dependency injection nelle risorse

​Annotazioni delle risorse

​Registrazione condizionale delle risorse

​Risposta della risorsa

​Risposta con link a risorsa

​Risposta blob

​Risposta di errore

​App

​Creare un’app resource

​Renderizzare un’app da un tool

​Visibilità dei tool app

​Configurazione dell’app

​Sviluppo di app con Boost

​Metadata

​Icone

​Autenticazione

​Sanctum

​OAuth 2.1

​Autorizzazione

​Client MCP

​Connessione a un server

​Client con nome

​Autenticazione del client

​Tool

​Prompt

​Risorse

​Test

​MCP Inspector

​Unit test

Cos’è MCP

Installazione

Creare un server

Registrare il server

Server Web

Server locale

Tool

Creare un tool

Nome e descrizione del tool

Schema di input

Schema di output

Validazione

Dependency injection

Annotazioni

Registrazione condizionale

Risposta

Prompt

Creare un prompt

Argomenti del prompt

Validazione

Dependency injection

Registrazione condizionale

Risposta del prompt

Risorse

Creare una risorsa

URI e MIME type

Template di risorse

Richiesta della risorsa

Dependency injection nelle risorse

Annotazioni delle risorse

Registrazione condizionale delle risorse

Risposta della risorsa

Risposta con link a risorsa

Risposta blob

Risposta di errore

App

Creare un’app resource

Renderizzare un’app da un tool

Visibilità dei tool app

Configurazione dell’app

Sviluppo di app con Boost

Metadata

Icone

Autenticazione

Sanctum

OAuth 2.1

Autorizzazione

Client MCP

Connessione a un server

Client con nome

Autenticazione del client

Tool

Prompt

Risorse

Test

MCP Inspector

Unit test