Laravel MCP server: connect your app to AI agents
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.
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, 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-tooland register inroutes/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 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.
composer require laravel/mcp
php artisan vendor:publish --tag=ai-routes
Then generate a server and a tool:
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.
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.
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, useResponse::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.
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 describes three options:
- OAuth 2.1 through Laravel Passport. With
Mcp::oauthRoutes()and theauth:apimiddleware, a user signs in and grants the AI client access. This is the recommended route when customers connect their own accounts. - Laravel Sanctum. With
auth:sanctumthe client sends a token in anAuthorization: Bearerheader. - 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:
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
initializehandshake and theMcp-Session-Idheader are gone. Every request stands on its own, so any server behind a load balancer can handle it. - Header-based routing: requests carry
Mcp-MethodandMcp-Nameheaders, 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, MVP development or technical advice, or get in touch for a no-obligation conversation.