Met het officiële package laravel/mcp bouw je in een Laravel-applicatie een MCP-server: een vaste ingang waarlangs AI-assistenten zoals Claude en ChatGPT gegevens uit je app opvragen of acties uitvoeren. Je schrijft gewone PHP-klassen voor tools, valideert de invoer zoals je dat in een controller doet en beveiligt de route met middleware. In dit artikel laat ik zien hoe dat werkt, met een echte MCP-server die ik voor Speelgoedruilen.nl heb gebouwd.

Kort samengevat

  • MCP (Model Context Protocol) is een open standaard waarmee AI-assistenten met externe software praten. De nieuwste versie van de specificatie is 2026-07-28, met een stateless kern.
  • Laravel MCP 1.0 verscheen op 15 september 2026 als eerste stabiele versie en ondersteunt die nieuwe specificatie.
  • Een server bestaat uit tools, resources en prompts, die je maakt met php artisan make:mcp-tool en registreert in routes/ai.php.
  • Beveiliging regel je met OAuth via Passport, een Sanctum-token of eigen middleware.
  • Testen gaat zonder AI-client: Server::tool(...)->assertOk() werkt gewoon in Pest.

Wat is een MCP-server en waarom zou je er een bouwen?

Een MCP-server vertelt een AI-assistent welke functies je applicatie aanbiedt, welke invoer die verwachten en wat ze teruggeven. De assistent kiest zelf welke tool hij aanroept om een vraag te beantwoorden. Jij bepaalt precies wat er mogelijk is.

Dat is iets anders dan een chatbot in je app bouwen. Met MCP breng je je app naar de AI-assistent die je team al gebruikt. Een paar voorbeelden van waar ik het nuttig vind:

  • Interne cijfers opvragen zonder dashboard: "Hoeveel aanmeldingen kwamen er vorige maand via de flyer?"
  • Klantenservice ondersteunen: een tool die de status van een bestelling of ticket opzoekt.
  • Je SaaS-product AI-klaar maken: klanten koppelen hun eigen assistent aan jouw platform, met hun eigen rechten.

Voor ontwikkelaars bestaat er ook een lokale variant. Laravel Boost is zelf een MCP-server die AI-codeerassistenten toegang geeft tot je database-schema, routes en de documentatie van precies de packageversies die je gebruikt.

Hoe installeer je Laravel MCP?

Installeren kost twee commando's. Het tweede maakt het bestand routes/ai.php aan, waar je servers registreert.

composer require laravel/mcp
php artisan vendor:publish --tag=ai-routes

Daarna maak je een server en een tool:

php artisan make:mcp-server StatisticsServer
php artisan make:mcp-tool SignupStatisticsTool

Servers komen in app/Mcp/Servers en tools in app/Mcp/Tools. Een server is een klasse met een naam, een versie, instructies voor de AI en een lijst met tools, resources en prompts.

use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;

#[Name('Speelgoedruilen statistics')]
#[Version('1.0.0')]
#[Instructions('Read-only statistics of a Dutch toy swap platform. Start with `platform-overview`.')]
class StatisticsServer extends Server
{
    protected array $tools = [
        Tools\PlatformOverviewTool::class,
        Tools\SignupStatisticsTool::class,
    ];
}

De instructies zijn belangrijker dan ze lijken. Hier leg je de AI uit wat je domein is, wat begrippen betekenen en waar hij moet beginnen. Hoe beter die uitleg, hoe minder de assistent gaat gokken.

Hoe ziet een MCP-tool in Laravel eruit?

Een tool heeft drie onderdelen: een beschrijving, een schema voor de invoer en een handle-methode. Hieronder een vereenvoudigde versie van de tool die bij Speelgoedruilen.nl het aantal aanmeldingen per periode telt.

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\ResponseFactory;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Tool;
use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;

#[Name('signup-statistics')]
#[Description('The number of new accounts per day, week or month, and where people came from.')]
#[IsReadOnly]
#[IsIdempotent]
class SignupStatisticsTool extends Tool
{
    public function schema(JsonSchema $schema): array
    {
        return [
            'period' => $schema->string()->enum(['day', 'week', 'month'])
                ->description('Group the statistics per day, week or month. Defaults to week.'),
            'periods' => $schema->integer()->min(1)->max(60)
                ->description('The number of periods to show. Defaults to 12.'),
        ];
    }

    public function handle(Request $request): ResponseFactory
    {
        $validated = $request->validate([
            'period' => ['nullable', 'in:day,week,month'],
            'periods' => ['nullable', 'integer', 'min:1', 'max:60'],
        ]);

        // ... tellen per periode

        return Response::structured([
            'period' => $validated['period'] ?? 'week',
            'signups' => $rows,
        ]);
    }
}

Een paar dingen die ik in de praktijk belangrijk vind:

  • De beschrijving is je documentatie. Laravel genereert de naam uit de klassenaam, maar een #[Description] moet je altijd zelf schrijven. De AI leest die tekst om te kiezen welke tool hij gebruikt.
  • Annotaties helpen de client. Met #[IsReadOnly] en #[IsIdempotent] laat je weten dat de tool niets wijzigt. Voor tools die wel iets aanpassen bestaat #[IsDestructive], zodat de client de gebruiker eerst om bevestiging kan vragen.
  • Gestructureerde antwoorden. Response::structured() geeft JSON terug in plaats van vrije tekst. Dat leest betrouwbaarder voor een AI en is makkelijker te testen. Voor een foutmelding gebruik je Response::error().
  • Schrijf duidelijke validatiefouten. De AI leest de foutmelding en probeert het opnieuw. Een melding als "Kies day, week of month" werkt beter dan "The selected period is invalid".

Hoe registreer je de server in routes/ai.php?

In routes/ai.php kies je tussen twee soorten servers. Mcp::web() is bereikbaar via HTTP, voor AI-assistenten in de browser of de cloud. Mcp::local() draait als Artisan-commando, voor tools die de server zelf als proces starten, zoals een codeerassistent op je laptop.

use App\Http\Middleware\AuthenticateStatisticsToken;
use App\Mcp\Servers\StatisticsServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('mcp/statistics', StatisticsServer::class)
    ->middleware(['throttle:60,1', AuthenticateStatisticsToken::class]);

Normaal zet ik middleware liever op de controller dan in de routedefinitie, maar Mcp::web() heeft geen controller. Dit is dus de plek.

Hoe beveilig je een MCP-server?

Een MCP-server is een API. Behandel hem ook zo. De documentatie van Laravel MCP noemt drie opties:

  1. OAuth 2.1 via Laravel Passport. Met Mcp::oauthRoutes() en de middleware auth:api logt een gebruiker in en geeft hij de AI-client toestemming. Dit is de aanbevolen route als klanten hun eigen account koppelen.
  2. Laravel Sanctum. Met auth:sanctum stuurt de client een token mee als Authorization: Bearer-header.
  3. Eigen middleware. Voor een interne server met één gebruiker is een geheim token genoeg.

Bij Speelgoedruilen.nl koos ik voor optie 3, omdat alleen ik de statistieken gebruik. De middleware vergelijkt het token met hash_equals(), zodat de vergelijking niet via timing te raden is. Is er geen token ingesteld, dan geeft de route een 404 en bestaat de server simpelweg niet. Daarnaast staat er een rate limit van 60 verzoeken per minuut op.

Minstens zo belangrijk is wat de tools teruggeven. De tools van Speelgoedruilen.nl lezen alleen en geven alleen aantallen terug, nooit gegevens van één persoon. Zo verlaat er geen persoonlijke data het platform, ook niet richting een AI-dienst. Voor de AVG is dat een stuk eenvoudiger dan een tool die namen of e-mailadressen teruggeeft.

Binnen een tool kun je ook gewoon autorisatie gebruiken met $request->user()->can(...). Met shouldRegister() verberg je een tool helemaal voor gebruikers die er geen recht op hebben, bijvoorbeeld alleen voor betalende abonnees.

Hoe test je een MCP-server met Pest?

Je hebt geen AI-client nodig om je tools te testen. Laravel MCP roept een tool direct aan vanuit een test, inclusief validatie. Zo ziet een test bij Speelgoedruilen.nl eruit:

it('counts the signups per week and where they came from', function (): void {
    User::factory()->create(['signup_source' => 'flyer']);

    StatisticsServer::tool(SignupStatisticsTool::class, ['period' => 'week', 'periods' => 2])
        ->assertOk()
        ->assertStructuredContent(fn (AssertableJson $json) => $json
            ->where('period', 'week')
            ->etc());
});

Andere handige assertions zijn assertHasErrors() voor ongeldige invoer en actingAs($user) om te testen wat een specifieke gebruiker mag. Wil je handmatig klikken, start dan de MCP Inspector met php artisan mcp:inspector mcp/statistics. Die laat in de browser alle tools zien en je kunt ze met eigen invoer aanroepen.

Wat verandert er met MCP-specificatie 2026-07-28?

De specificatie van 28 juli 2026 is de grootste wijziging sinds de start van MCP. De belangrijkste punten:

  • Stateless: de initialize-handshake en de Mcp-Session-Id-header verdwijnen. Elk verzoek staat op zichzelf, dus elke server achter een load balancer kan het afhandelen.
  • Routering via headers: verzoeken bevatten Mcp-Method en Mcp-Name, zodat gateways en rate limiters kunnen werken zonder de JSON te lezen.
  • Cache-hints op lijsten van tools, prompts en resources.
  • Strengere OAuth: PKCE is verplicht en dynamische clientregistratie maakt plaats voor Client ID Metadata Documents.

Voor een Laravel-ontwikkelaar is het goede nieuws dat het package dit grotendeels afhandelt. Stateless past bovendien prima bij hoe Laravel al werkt: één verzoek, één antwoord. Kom je van een 0.x-versie, lees dan de upgrade-gids van Laravel MCP 1.0 vanwege de nieuwe header-eisen.

Veelgestelde vragen

Welke AI-assistenten werken met een Laravel MCP-server?

Elke client die MCP ondersteunt, zoals Claude, ChatGPT, Cursor en VS Code. Een webserver via Mcp::web() voeg je toe als connector met de URL van je server. Een lokale server via Mcp::local() start de client zelf als Artisan-commando.

Is een MCP-server veilig voor klantgegevens?

Dat hangt af van wat je bouwt. Beveilig de route met OAuth of Sanctum, controleer rechten per tool en geef alleen de gegevens terug die echt nodig zijn. Tools die alleen lezen en geen persoonsgegevens teruggeven, zijn het veiligste startpunt.

Wat is het verschil tussen Laravel MCP en Laravel Boost?

Laravel MCP is het package waarmee je zelf MCP-servers bouwt voor je applicatie en je gebruikers. Laravel Boost is een kant-en-klare lokale MCP-server voor ontwikkelaars, die AI-codeerassistenten context geeft over je Laravel-project. Boost is zelf gebouwd op Laravel MCP.

Je eigen platform koppelen aan AI?

Wil je je SaaS-platform of interne applicatie bereikbaar maken voor AI-assistenten, veilig en met goede tests? Vanuit Oosterhout bouw ik Laravel-platformen voor bedrijven in heel Nederland. Bekijk SaaS-platformen bouwen, een MVP laten bouwen of technisch advies, of neem contact op voor een vrijblijvend gesprek.