Laravel MCP - Knowledge of Laravel

Wat is MCP

Het Model Context Protocol (MCP) is een specificatie waarmee AI-clients (Claude, Cursor, GitHub Copilot enz.) en applicaties via een gestandaardiseerd protocol communiceren. Door een MCP-server te implementeren kunnen AI-agents toegang krijgen tot de data van je Laravel-applicatie en acties uitvoeren.

Laravel MCP is een officieel pakket dat is toegevoegd in Laravel 13. Het wordt geleverd als laravel/mcp en biedt alle functionaliteit die nodig is om MCP-servers te bouwen.

Een MCP-server kan hoofdzakelijk drie soorten functionaliteit aanbieden.

Functionaliteit	Beschrijving
Tools	Functies die een AI-client kan aanroepen. Zoeken, bijwerken, integratie met externe API’s enz.
Resources	Data en contextinformatie die een AI-client kan inlezen
Prompts	Herbruikbare prompttemplates

Installatie

Installeer het pakket met Composer.

composer require laravel/mcp

Voer na de installatie het Artisan-commando vendor:publish uit om het bestand routes/ai.php te genereren.

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

Dit commando maakt het bestand routes/ai.php aan. Hier registreer je je MCP-servers.

Een server maken

Genereer een serverklasse met het Artisan-commando make:mcp-server.

php artisan make:mcp-server WeatherServer

De serverklasse wordt gegenereerd in de directory 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,
    ];
}

De server registreren

Heb je een server gemaakt, dan registreer je die in routes/ai.php. Er zijn twee manieren van registreren: als webserver en als lokale server.

Webserver

Een webserver is bereikbaar via HTTP POST-requests. Ideaal voor externe AI-clients en webgebaseerde integraties.

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

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

Net als bij gewone routes kun je middleware toepassen.

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

Lokale server

Een lokale server draait als Artisan-commando. Je gebruikt dit voor integratie met lokale AI-clients zoals Claude Desktop.

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

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

Een lokale server wordt normaal gesproken automatisch gestart door de MCP-client. Je hoeft het Artisan-commando mcp:start niet handmatig uit te voeren.

Tools

Tools zijn functies die een AI-client kan aanroepen. Je kunt er onder meer het ophalen van data, integratie met externe API’s en databasebewerkingen mee implementeren.

Een tool maken

Genereer een toolklasse met het Artisan-commando make:mcp-tool.

php artisan make:mcp-tool CurrentWeatherTool

Registreer de gemaakte tool in de property $tools van de server.

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

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

Een implementatievoorbeeld van een eenvoudige toolklasse:

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

        // Weerdata ophalen...

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

Naam en beschrijving van de tool

Uit de klassenaam worden automatisch een standaardnaam en -titel gegenereerd. Bij CurrentWeatherTool is de naam current-weather en de titel Current Weather Tool. Met de attributen Name en Title pas je die aan.

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

De beschrijving van een tool (Description) wordt niet automatisch gegenereerd. Die is essentieel zodat het AI-model begrijpt hoe de tool moet worden gebruikt; stel dus altijd een betekenisvolle beschrijving in.

Invoerschema

Met de methode schema definieer je het schema van de invoerparameters. Via de JSON-schemabuilder van Laravel geef je types en beperkingen op.

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

Uitvoerschema

Met de methode outputSchema definieer je de structuur van de response. Dat maakt het voor AI-clients makkelijker om de response te parsen.

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

Validatie

Binnen de handle-methode kun je de standaard validatiefunctionaliteit van Laravel gebruiken.

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

    // Verder werken met de gevalideerde data...
}

Bij een validatiefout gebruikt de AI-client de foutmelding als leidraad voor een nieuwe poging. Zorg dus voor concrete en uitvoerbare foutmeldingen.

Dependency injection

Omdat tools worden geresolved via de servicecontainer van Laravel, kun je afhankelijkheden type-hinten in de constructor of de handle-methode.

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

Annotaties

Door annotaties aan een tool toe te voegen geef je AI-clients extra informatie over het gedrag van de tool.

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

De beschikbare annotaties zijn als volgt.

Annotatie	Beschrijving
`#[IsReadOnly]`	Geeft aan dat de tool de omgeving niet wijzigt
`#[IsDestructive]`	Geeft aan dat de tool mogelijk destructieve wijzigingen uitvoert
`#[IsIdempotent]`	Geeft aan dat herhaald aanroepen met dezelfde argumenten geen bijwerkingen heeft
`#[IsOpenWorld]`	Geeft aan dat de tool mogelijk met externe entiteiten communiceert

Voorwaardelijke registratie

Door de methode shouldRegister te implementeren registreer je tools voorwaardelijk tijdens runtime.

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

Geef je false terug, dan is de tool onzichtbaar voor de AI-client.

Responses

Tools moeten een instantie van Laravel\Mcp\Response teruggeven.

Tekstresponse

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

Foutresponse

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

Afbeeldings- en audioresponse

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

// Direct uit storage lezen (het MIME-type wordt automatisch gedetecteerd)
return Response::fromStorage('weather/radar.png');

Response met meerdere inhoudsdelen

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

Gestructureerde response

Geeft gestructureerde data terug die een AI-client makkelijk kan parsen.

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

Streamingresponse

Verstuurt bij langdurige verwerking de voortgang in realtime.

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

Prompts

Prompts zijn herbruikbare prompttemplates. Je kunt gestandaardiseerde varianten aanbieden van de terugkerende query’s die AI-clients gebruiken in hun interactie met taalmodellen.

Een prompt maken

php artisan make:mcp-prompt DescribeWeatherPrompt

Registreer de prompt in de property $prompts van de server.

use App\Mcp\Prompts\DescribeWeatherPrompt;

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

Promptargumenten

Met de methode arguments definieer je de parameters van de prompt.

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

Validatie

Promptargumenten worden automatisch gevalideerd op basis van hun definitie, maar je kunt ook complexere validatieregels toepassen. Laravel MCP werkt naadloos samen met de validatiefunctionaliteit van Laravel. Je valideert de argumenten binnen de handle-methode van de prompt.

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

        // De prompt genereren met de opgegeven tone...
    }
}

Bij een validatiefout gebruikt de AI-client de foutmelding als leidraad voor een nieuwe poging. Zorg voor concrete en uitvoerbare meldingen.

$validated = $request->validate([
    'tone' => ['required', 'string', 'max:50'],
], [
    'tone.*' => 'Geef een tone op. Bijvoorbeeld: "formal", "casual" of "humorous".',
]);

Dependency injection

Omdat prompts worden geresolved via de servicecontainer van Laravel, kun je afhankelijkheden type-hinten in de constructor of de handle-methode.

<?php

namespace App\Mcp\Prompts;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Prompt;

class DescribeWeatherPrompt extends Prompt
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}
}

Ook in de handle-methode kun je type-hinten; de servicecontainer resolvet en injecteert automatisch.

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

    // ...
}

Voorwaardelijke registratie

Door de methode shouldRegister te implementeren registreer je prompts voorwaardelijk tijdens 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;
    }
}

Geef je false terug, dan is de prompt onzichtbaar voor de AI-client en kan hij ook niet worden aangeroepen.

Promptresponses

De handle-methode van een prompt kan gebruikers- en assistentberichten teruggeven. Met asAssistant() behandel je een bericht als afkomstig van de assistent.

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

Resources

Resources zijn data en informatie die een AI-client als context kan inlezen. Je kunt er informatie mee aanbieden die de kwaliteit van AI-antwoorden verbetert, zoals documentatie, configuratie-informatie en dynamische data.

Een resource maken

php artisan make:mcp-resource WeatherGuidelinesResource

Registreer de resource in de property $resources van de 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 en MIME-type

Standaard wordt de URI automatisch gegenereerd uit de klassenaam (bijv. weather://resources/weather-guidelines). Met de attributen Uri en MimeType pas je die aan.

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

Resourcetemplates

Om een dynamische resource met URI-variabelen te definiëren implementeer je de interface 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');

        // De bestandsinhoud ophalen en teruggeven...

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

Variabelen uit de URI worden automatisch in het request opgenomen en zijn op te halen met de get-methode.

Resourcerequests

Anders dan bij tools en prompts kun je bij resources geen invoerschema of argumenten definiëren. Binnen de handle-methode heb je echter via het requestobject wel toegang tot requestinformatie.

<?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
    {
        // Toegang tot de requestinformatie...
    }
}

Dependency injection bij resources

Omdat resources worden geresolved via de servicecontainer van Laravel, kun je afhankelijkheden type-hinten in de constructor of de handle-methode.

<?php

namespace App\Mcp\Resources;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}
}

Ook in de handle-methode kun je type-hinten; de servicecontainer resolvet en injecteert automatisch.

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

Resource-annotaties

Aan resources kun je annotaties toevoegen voor onder meer doelgroep, prioriteit en laatste wijzigingsdatum.

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

Annotatie	Type	Beschrijving
`#[Audience]`	Role of array	De doelgroep (`Role::User`, `Role::Assistant` of beide)
`#[Priority]`	float	Belangrijkheidsscore (0.0-1.0)
`#[LastModified]`	string	Laatste wijzigingsdatum in ISO 8601-formaat

Voorwaardelijke registratie van resources

Door de methode shouldRegister te implementeren registreer je resources voorwaardelijk tijdens 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;
    }
}

Geef je false terug, dan is de resource onzichtbaar voor de AI-client en ook niet toegankelijk.

Resourceresponses

Resources moeten een instantie van Laravel\Mcp\Response teruggeven. Voor tekstuele inhoud gebruik je de methode text.

return Response::text($weatherData);

Resourcelink-responses

Met de methode resourceLink geef je een resourcelink terug. Anders dan een ingebedde resource geef je hiermee een URI-pointer terug die de AI-client zelfstandig ophaalt.

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

Je kunt ook een geregistreerde resourceklasse of -instantie doorgeven. De URI, naam, titel, beschrijving en het MIME-type worden dan automatisch overgenomen.

return Response::resourceLink(new WeatherForecastResource);

Blob-responses

Om binaire inhoud terug te geven gebruik je de methode blob. Het MIME-type stel je in via het #[MimeType]-attribuut van de resource.

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

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

Foutresponses

Om een fout aan te geven gebruik je de methode error.

return Response::error('Kon de weerdata voor de opgegeven locatie niet ophalen.');

Apps

Laravel MCP ondersteunt MCP Apps. Dit is een uitbreiding van het Model Context Protocol waarmee tools interactieve HTML-applicaties kunnen renderen in een sandbox-iframe binnen ondersteunende hosts. Zo bouw je dashboards, formulieren, visualisaties en andere rijke ervaringen die verder gaan dan platte-tekstresponses. Een MCP-app bestaat uit twee samenwerkende onderdelen:

App-resource — geeft de zelfstandige HTML van de applicatie terug.
Tool — wordt via het attribuut #[RendersApp] gekoppeld aan de app-resource. Wanneer de tool wordt aangeroepen, haalt de host de gekoppelde resource op en rendert die.

Een app-resource maken

Met het Artisan-commando make:mcp-app-resource maak je een app-resource aan.

php artisan make:mcp-app-resource WeatherDashboardApp

Dit commando maakt twee bestanden aan: een PHP-klasse in app/Mcp/Resources en een Blade-view in resources/views/mcp. De viewnaam wordt automatisch afgeleid uit de klassenaam. WeatherDashboardApp wordt bijvoorbeeld gemapt naar 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 erft over van de basisklasse Resource en stelt automatisch het ui://-URI-schema en het MIME-type text/html;profile=mcp-app in die de MCP Apps-specificatie vereist. Net als andere resources moet je de klasse registreren in de $resources-array van de server. De gegenereerde Blade-view gebruikt de component <x-mcp::app>. Deze component rendert een compleet HTML-document met de client-side MCP SDK gebundeld.

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

De globale functie createMcpApp wordt geleverd door de gebundelde SDK. Die regelt het verbinden van het iframe met de server, het toepassen van het host-thema en het beschikbaar stellen van helpers zoals callServerTool, sendMessage en openLink, plus eventcallbacks. Zie de MCP Apps-specificatie voor de volledige client-side API.

Een app renderen vanuit een tool

Om een app-resource weer te geven koppel je die met het attribuut #[RendersApp] aan een tool. Wanneer de tool wordt aangeroepen, neemt Laravel MCP de URI van de resource op in de metadata van de tool, zodat de host de app in een sandbox-iframe kan renderen.

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

Wanneer een AppResource is geregistreerd, adverteert Laravel MCP automatisch de capability io.modelcontextprotocol/ui. Extra serverconfiguratie is niet nodig.

Zichtbaarheid van app-tools

Elke #[RendersApp]-tool kan met het argument visibility beperken door wie hij kan worden aangeroepen. Dit is handig voor private, app-specifieke tools die de UI aanroept om data te laden of bij te werken, en die je voor het model verborgen wilt houden.

use Laravel\Mcp\Server\Attributes\RendersApp;
use Laravel\Mcp\Server\Ui\Enums\Visibility;

#[RendersApp(resource: WeatherDashboardApp::class, visibility: [Visibility::App])]
class GetWeatherData extends Tool
{
    // ...
}

De Visibility-enum heeft twee cases, Model en App; standaard gelden beide. Gebruik [Visibility::App] voor backend-acties die de UI direct aanroept, en [Visibility::Model] om de tool onbereikbaar te maken vanuit de UI.

App-configuratie

Met het #[AppMeta]-attribuut van een app-resource stel je de Content Security Policy van het iframe, de browserrechten en de libraryscripts voor de <head> van de view in.

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

De Library-enum bevat vooraf geconfigureerde CDN-scripts voor gangbare frontend-libraries zoals Library::Tailwind en Library::Alpine; de CDN-origins worden automatisch samengevoegd met de CSP. De Permission-enum dekt browserrechten zoals Camera, Microphone, Geolocation en ClipboardWrite.

Heb je dynamische configuratie nodig, override dan de appMeta-methode van de resource met de fluente builders AppMeta, Csp en Permissions uit de namespace Laravel\Mcp\Server\Ui.

App-ontwikkeling met Boost

Laravel MCP bevat een speciale Boost-skillreferentie voor het bouwen van MCP Apps. Is Laravel Boost geïnstalleerd, dan kan een AI-codeeragent de skill mcp-development aanroepen en automatisch app-resources, Blade-views en gekoppelde tools genereren. Voor de volledige protocolreferentie (inclusief details over de client-side API en schema’s) raadpleeg je de officiële MCP Apps-documentatie.

Metadata

Je kunt het _meta-veld uit de MCP-specificatie toevoegen aan responses van tools, resources en prompts.

// Metadata op de responseinhoud
return Response::text('The weather is sunny.')
    ->withMeta(['source' => 'weather-api', 'cached' => true]);

Wil je metadata toevoegen aan de hele response-envelope, gebruik dan Response::make.

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

Om metadata toe te voegen aan de tool-, resource- of promptklasse zelf, definieer je de property $meta.

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

Iconen

MCP-clients kunnen iconen tonen voor de server en zijn primitieven. Met het Icon-attribuut declareer je iconen op servers, tools, resources en prompts.

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

Het Icon-attribuut is herhaalbaar, zodat je meerdere iconen kunt declareren voor verschillende formaten en licht/donker-themavarianten. Als alternatief kun je de icons-methode overriden om iconen programmatisch te definiëren. Dat is handig wanneer de iconen afhangen van runtime-omstandigheden.

use Laravel\Mcp\Schema\Icon;

class CurrentWeatherTool extends Tool
{
    /**
     * De iconen van de tool ophalen.
     *
     * @return array<int, Icon>
     */
    public function icons(): array
    {
        return [
            Icon::from('mcp/tool.png', mimeType: 'image/png'),
        ];
    }
}

Iconen gedefinieerd via attributen en via de icons-methode worden automatisch samengevoegd. Iconpaden worden als volgt opgelost:

Paden met een URI-schema zoals https: of data: worden ongewijzigd gebruikt.
Relatieve paden worden met de asset-helper van Laravel omgezet naar een URL.

Authenticatie

Webservers kun je authenticeren met de standaard middleware van Laravel.

Sanctum

Tokenauthenticatie met Laravel Sanctum. De MCP-client stuurt de 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

OAuth-authenticatie met Laravel Passport. Geschikt wanneer je robuustere beveiliging nodig hebt.

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

Mcp::oauthRoutes();

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

Gebruik je OAuth-authenticatie, publiceer dan de autorisatieviews van Passport en configureer ze in een serviceprovider.

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

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

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

Autorisatie

Met $request->user() haal je de geauthenticeerde gebruiker op en voer je autorisatiechecks uit binnen tools en resources.

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

    // Verwerking voortzetten...
}

MCP-client

Laravel MCP biedt niet alleen het bouwen van servers, maar ook een client om verbinding te maken met andere MCP-servers. Met de client kun je tools ontdekken en aanroepen die externe MCP-servers publiceren. Dit is vooral nuttig om de functionaliteit van externe MCP-servers beschikbaar te stellen aan AI-agents.

Verbinden met een server

Voor MCP-servers die via HTTP bereikbaar zijn gebruik je de methode Client::web met de URL van de server.

use Laravel\Mcp\Client;

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

Voor lokale MCP-servers die als commando starten gebruik je de methode Client::local met het commando en de argumenten.

use Laravel\Mcp\Client;

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

De client maakt lazy verbinding: de verbinding wordt automatisch opgezet wanneer voor het eerst tools worden opgesomd of aangeroepen. Wil je de verbinding handmatig beheren, gebruik dan de methoden connect, connected, ping en disconnect.

$client->connect();

$client->ping();

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

$client->disconnect();

Met de methode withTimeout pas je de requesttime-out aan.

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

Benoemde clients

In plaats van elke keer een client op te bouwen, kun je herbruikbare benoemde clients registreren. Meestal doe je dat via de Mcp-facade in de boot-methode van een serviceprovider.

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

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

Na registratie resolve je de client op naam.

use Laravel\Mcp\Facades\Mcp;

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

Benoemde clients worden per request slechts één keer geresolved en aan het einde van de requestlifecycle automatisch verbroken.

Clientauthenticatie

Om verbinding te maken met een web-MCP-server die met een Bearer-token is beschermd, gebruik je de methode withToken. Je kunt een tokenstring doorgeven of een closure die het token lazy resolvet.

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

Voor servers die zijn beschermd met OAuth 2.1 gebruik je de methode 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'),
));

Ondersteunt de MCP-server dynamische clientregistratie, dan kun je clientId en clientSecret weglaten. De client registreert zich dan automatisch.

Registreer vervolgens in het bestand routes/ai.php de OAuth-routes voor de benoemde client met de methode oAuthRoutesFor. De doorgegeven closure ontvangt de clientnaam en een TokenSet nadat de autorisatiecode is ingewisseld voor een 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');
});

Hiermee worden twee benoemde routes geregistreerd: een connect-route (mcp.oauth.{client}.connect) die de gebruiker naar de autorisatieserver redirect, en een callback-route (mcp.oauth.{client}.callback) die de autorisatiecode inwisselt en de handler aanroept. Beide gebruiken de web-middlewaregroep (te overschrijven via het argument middleware). Om de autorisatieflow te starten redirect je de gebruiker naar de connect-route.

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

Tools

Met de methode tools haal je de tools op die de MCP-server publiceert. Ze worden teruggegeven als een collection met de naam als sleutel.

use Laravel\Mcp\Facades\Mcp;

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

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

De client handelt paginatie automatisch af en haalt alle tools op. Met het argument limit beperk je het aantal.

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

Om een tool aan te roepen gebruik je de methode callTool met de toolnaam en een array met argumenten. Via de teruggegeven ToolResult-instantie haal je de response op.

use Laravel\Mcp\Facades\Mcp;

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

$result->text();             // De tekstinhoud van de response
(string) $result;            // Gelijk aan text()
$result->isError;            // Of de tool een fout heeft gemeld
$result->structuredContent;  // Gestructureerde inhoud (indien aanwezig)

Je kunt ook direct aanroepen vanaf een opgesomde toolinstantie.

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

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

Bouw je agents met de Laravel AI SDK, dan kun je de tools van de MCP-client direct aan een agent doorgeven, zodat het model ze kan aanroepen tijdens het beantwoorden van een prompt. Zie de sectie MCP-tools van de AI SDK voor details.

Prompts

Met de methode prompts haal je de prompts op die de MCP-server publiceert. Ze worden teruggegeven als een collection met de naam als sleutel.

use Laravel\Mcp\Facades\Mcp;

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

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

De client handelt paginatie automatisch af en haalt alle prompts op. Met het argument limit beperk je het aantal.

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

Om een prompt op te halen gebruik je de methode getPrompt met de promptnaam en een array met argumenten. Via de teruggegeven PromptResult-instantie haal je de gegenereerde berichten op.

use Laravel\Mcp\Facades\Mcp;

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

$result->text();        // De tekstinhoud van de berichten
(string) $result;       // Gelijk aan text()
$result->messages;      // De berichten die de prompt heeft teruggegeven (ruwe data)
$result->description;   // De beschrijving van de prompt (indien aanwezig)

Resources

Met de methode resources haal je de resources op die de MCP-server publiceert. Ze worden teruggegeven als een collection met de URI als sleutel.

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

De client handelt paginatie automatisch af en haalt alle resources op. Met het argument limit beperk je het aantal.

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

Om een resource in te lezen gebruik je de methode readResource met de URI van de resource. Via de teruggegeven ResourceReadResult-instantie haal je de inhoud op.

use Laravel\Mcp\Facades\Mcp;

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

$result->content();   // De inhoud van de resource (base64-blobs worden automatisch gedecodeerd)
(string) $result;     // Gelijk aan content()
$result->mimeType();  // Het MIME-type van de resource (indien aanwezig)
$result->contents;    // De inhoud die de resource heeft teruggegeven (ruwe data)

Testen

MCP Inspector

Om de werking van je MCP-server te controleren gebruik je de interactieve debugtool “MCP Inspector”.

# Webserver
php artisan mcp:inspector mcp/weather

# Lokale server (met de naam "weather")
php artisan mcp:inspector weather

Als je het commando uitvoert start de MCP Inspector en kun je de clientconfiguratie kopiëren. Heb je authenticatiemiddleware ingesteld, verbind dan inclusief de Authorization-header.

Unit tests

Je kunt unit tests schrijven voor tools, resources en prompts.

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

Prompts en resources test je op dezelfde manier.

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

Om als geauthenticeerde gebruiker te draaien gebruik je actingAs.

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

De belangrijkste assertion-methoden zijn als volgt.

$response->assertOk();           // Controleren dat er geen fouten zijn
$response->assertSee('...');     // Controleren dat een specifieke tekst voorkomt

Om te verifiëren of er fouten zijn gebruik je assertHasErrors / assertHasNoErrors.

$response->assertHasErrors();

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

$response->assertHasNoErrors();

Je kunt de naam, titel en beschrijving van tools, resources en prompts verifiëren.

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

Om de notificaties van een streamingresponse te verifiëren gebruik je assertSentNotification en assertNotificationCount.

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

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

$response->assertNotificationCount(5);

Om de inhoud van een response te debuggen gebruik je de methoden dd of dump.

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

​Wat is MCP

​Installatie

​Een server maken

​De server registreren

​Webserver

​Lokale server

​Tools

​Een tool maken

​Naam en beschrijving van de tool

​Invoerschema

​Uitvoerschema

​Validatie

​Dependency injection

​Annotaties

​Voorwaardelijke registratie

​Responses

​Prompts

​Een prompt maken

​Promptargumenten

​Validatie

​Dependency injection

​Voorwaardelijke registratie

​Promptresponses

​Resources

​Een resource maken

​URI en MIME-type

​Resourcetemplates

​Resourcerequests

​Dependency injection bij resources

​Resource-annotaties

​Voorwaardelijke registratie van resources

​Resourceresponses

​Resourcelink-responses

​Blob-responses

​Foutresponses

​Apps

​Een app-resource maken

​Een app renderen vanuit een tool

​Zichtbaarheid van app-tools

​App-configuratie

​App-ontwikkeling met Boost

​Metadata

​Iconen

​Authenticatie

​Sanctum

​OAuth 2.1

​Autorisatie

​MCP-client

​Verbinden met een server

​Benoemde clients

​Clientauthenticatie

​Tools

​Prompts

​Resources

​Testen

​MCP Inspector

​Unit tests

Wat is MCP

Installatie

Een server maken

De server registreren

Webserver

Lokale server

Tools

Een tool maken

Naam en beschrijving van de tool

Invoerschema

Uitvoerschema

Validatie

Dependency injection

Annotaties

Voorwaardelijke registratie

Responses

Prompts

Een prompt maken

Promptargumenten

Validatie

Dependency injection

Voorwaardelijke registratie

Promptresponses

Resources

Een resource maken

URI en MIME-type

Resourcetemplates

Resourcerequests

Dependency injection bij resources

Resource-annotaties

Voorwaardelijke registratie van resources

Resourceresponses

Resourcelink-responses

Blob-responses

Foutresponses

Apps

Een app-resource maken

Een app renderen vanuit een tool

Zichtbaarheid van app-tools

App-configuratie

App-ontwikkeling met Boost

Metadata

Iconen

Authenticatie

Sanctum

OAuth 2.1

Autorisatie

MCP-client

Verbinden met een server

Benoemde clients

Clientauthenticatie

Tools

Prompts

Resources

Testen

MCP Inspector

Unit tests