# Laravel MCP server: connect your app to AI agents

> How to build an MCP server in Laravel with laravel/mcp: tools, validation, security and Pest tests, with a real example from Speelgoedruilen.nl.

- URL: https://snoerendevelopment.nl/en/blog/laravel-mcp-server-tutorial
- Language: en-US
- Author: Michael Snoeren (Snoeren Development)
- Published: 2026-11-15

The official `laravel/mcp` package lets you add an MCP server to a Laravel application: a single, well-defined entry point that AI assistants such as Claude and ChatGPT use to read data from your app or perform actions in it. You write plain PHP classes for tools, validate input just like you would in a controller, and protect the route with middleware. In this article I show how it works, using a real MCP server I built for [Speelgoedruilen.nl](/en/blog/building-speelgoedruilen-with-laravel).

**In short**

- **MCP** (Model Context Protocol) is an open standard that lets AI assistants talk to external software. The latest version of the specification is [2026-07-28](https://blog.modelcontextprotocol.io/posts/2026-07-28/), built around a stateless core.
- **Laravel MCP 1.0** was released on 15 September 2026 as the first stable version and supports that new specification.
- A server consists of **tools, resources and prompts**, which you generate with `php artisan make:mcp-tool` and register in `routes/ai.php`.
- **Security** is handled with OAuth through Passport, a Sanctum token or your own middleware.
- **Testing** needs no AI client: `Server::tool(...)->assertOk()` works right inside Pest.

## What is an MCP server and why would you build one?

An MCP server tells an AI assistant which functions your application offers, what input they expect and what they return. The assistant decides on its own which tool to call to answer a question. You decide exactly what is possible.

That is different from building a chatbot into your app. With MCP you bring your app to the AI assistant your team already uses. A few places where I find it useful:

- **Querying internal numbers** without a dashboard: "How many people signed up through the flyer last month?"
- **Supporting customer service**: a tool that looks up the status of an order or a ticket.
- **Making your SaaS product AI-ready**: customers connect their own assistant to your platform, with their own permissions.

There is also a local flavour aimed at developers. [Laravel Boost](https://github.com/laravel/boost) is itself an MCP server that gives AI coding assistants access to your database schema, your routes and the documentation for the exact package versions you have installed.

## How do you install Laravel MCP?

Installation takes two commands. The second one creates `routes/ai.php`, where you register your servers.

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

Then generate a server and a tool:

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

Servers live in `app/Mcp/Servers` and tools in `app/Mcp/Tools`. A server is a class with a name, a version, instructions for the AI and a list of tools, resources and prompts.

```php
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,
    ];
}
```

The instructions matter more than they seem. This is where you explain your domain to the AI: what the terms mean and where to start. The better that explanation, the less the assistant has to guess.

## What does an MCP tool in Laravel look like?

A tool has three parts: a description, a schema for its input and a `handle` method. Below is a simplified version of the tool that counts signups per period on Speelgoedruilen.nl.

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

        // ... count per period

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

A few things I have learned to care about:

- **The description is your documentation.** Laravel derives the name from the class name, but you always have to write the `#[Description]` yourself. The AI reads that text to decide which tool to use.
- **Annotations help the client.** `#[IsReadOnly]` and `#[IsIdempotent]` tell it the tool changes nothing. For tools that do modify data there is `#[IsDestructive]`, so the client can ask the user for confirmation first.
- **Return structured data.** `Response::structured()` returns JSON instead of free text. An AI reads that more reliably, and it is easier to test. For errors, use `Response::error()`.
- **Write helpful validation messages.** The AI reads the error and tries again. "Choose day, week or month" works better than "The selected period is invalid".

## How do you register the server in routes/ai.php?

In `routes/ai.php` you choose between two kinds of servers. `Mcp::web()` is reachable over HTTP, for AI assistants running in the browser or the cloud. `Mcp::local()` runs as an Artisan command, for tools that start the server as a process themselves, like a coding assistant on your laptop.

```php
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]);
```

I normally prefer middleware on the controller rather than in the route definition, but `Mcp::web()` has no controller, so this is the place for it.

## How do you secure an MCP server?

An MCP server is an API, so treat it like one. The [Laravel MCP documentation](https://laravel.com/docs/mcp) describes three options:

1. **OAuth 2.1 through Laravel Passport.** With `Mcp::oauthRoutes()` and the `auth:api` middleware, a user signs in and grants the AI client access. This is the recommended route when customers connect their own accounts.
2. **Laravel Sanctum.** With `auth:sanctum` the client sends a token in an `Authorization: Bearer` header.
3. **Custom middleware.** For an internal server with a single user, a secret token is enough.

For Speelgoedruilen.nl I went with option 3, because I am the only one using the statistics. The middleware compares the token with `hash_equals()`, so it cannot be guessed through timing differences. If no token is configured, the route returns a 404 and the server simply does not exist. On top of that there is a rate limit of 60 requests per minute.

What the tools return is just as important. The Speelgoedruilen.nl tools only read data and only return counts, never data about an individual person. That way no personal data leaves the platform, not even to an AI service, which makes GDPR compliance a lot simpler than with a tool that returns names or email addresses.

Inside a tool you can use regular authorization with `$request->user()->can(...)`. With `shouldRegister()` you can hide a tool entirely from users who are not allowed to use it, for example to offer it only to paying subscribers.

## How do you test an MCP server with Pest?

You do not need an AI client to test your tools. Laravel MCP calls a tool directly from a test, validation included. This is what a test for Speelgoedruilen.nl looks like:

```php
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());
});
```

Other useful helpers are `assertHasErrors()` for invalid input and `actingAs($user)` to test what a specific user may do. If you want to click around by hand, start the MCP Inspector with `php artisan mcp:inspector mcp/statistics`. It lists every tool in your browser and lets you call them with your own input.

## What changes with the 2026-07-28 MCP specification?

The specification of 28 July 2026 is the biggest change since MCP launched. The key points:

- **Stateless:** the `initialize` handshake and the `Mcp-Session-Id` header are gone. Every request stands on its own, so any server behind a load balancer can handle it.
- **Header-based routing:** requests carry `Mcp-Method` and `Mcp-Name` headers, so gateways and rate limiters can work without parsing the JSON body.
- **Cache hints** on the lists of tools, prompts and resources.
- **Stricter OAuth:** PKCE is required, and dynamic client registration is being replaced by Client ID Metadata Documents.

The good news for Laravel developers is that the package handles most of this for you. Stateless also fits the way Laravel already works: one request, one response. If you are coming from a 0.x release, read the Laravel MCP 1.0 upgrade guide because of the new header requirements.

## Frequently asked questions

### Which AI assistants work with a Laravel MCP server?

Any client that supports MCP, such as Claude, ChatGPT, Cursor and VS Code. A web server created with `Mcp::web()` is added as a connector using your server's URL. A local server created with `Mcp::local()` is started by the client itself as an Artisan command.

### Is an MCP server safe for customer data?

That depends on what you build. Protect the route with OAuth or Sanctum, check permissions per tool and return only the data that is really needed. Read-only tools that return no personal data are the safest place to start.

### What is the difference between Laravel MCP and Laravel Boost?

Laravel MCP is the package you use to build your own MCP servers for your application and its users. Laravel Boost is a ready-made local MCP server for developers that gives AI coding assistants context about your Laravel project. Boost itself is built on Laravel MCP.

## Want to connect your own platform to AI?

Would you like to make your SaaS platform or internal application available to AI assistants, securely and with proper tests? From Oosterhout in the Netherlands I build Laravel platforms for clients in the Netherlands and beyond. Have a look at [SaaS platform development](/en/services/saas-platform-development), [MVP development](/en/services/mvp-development) or [technical advice](/en/services/advice), or [get in touch](/en/contact) for a no-obligation conversation.