Back to Blog
Laravel MCP 1.0: Build MCP Servers and Clients for AI Agents
Laravel MCP 1.0 lets you expose your app's domain logic to AI agents via Model Context Protocol. Here's what the package actually ships, how it differs from Laravel Boost, and what changed in the 1.0 release.
Back
Engineering
Table of contents
Laravel MCP 1.0: Build MCP Servers and Clients for AI Agents
If you've been watching Laravel's AI story, you've seen Laravel Boost (the MCP server that helps agents understand Laravel apps). That's tooling FOR your app.
Laravel MCP 1.0 is different. It's a package to BUILD MCP servers and clients that expose YOUR domain tools and data to AI agents.
Version 1.0.0 shipped on 14 Sep 2026 (Packagist), with a Laravel News writeup the next day. The protocol itself got a major revision on 28 Jul 2026, and 1.0 tracks that spec.
This post covers what the package does, how to use it, and what broke between 0.9 and 1.0 so you don't hit the upgrade blind.
What Laravel MCP Actually Is
Laravel MCP is a first-party package that lets you build MCP servers (and a client) so AI coding tools can interact with your Laravel app via the Model Context Protocol.
Install it:
bash
composer require laravel/mcp:^1.2As of 20 Nov 2026 the current release is laravel/mcp v1.2.1 (17 Nov 2026). Version 1.2.0 added Origin header validation on web MCP routes, and the 1.1.x line tightened OAuth redirect URIs in dynamic client registration.
Publish the routes:
bash
php artisan vendor:publish --tag=ai-routesThat creates routes/ai.php, where you register MCP servers.
The docs distinguish two server types:
- Web servers (HTTP POST endpoints for remote agents)
- Local servers (stdio for local agents like Cursor or Claude Desktop)
Both use the same server classes. The transport layer changes, not your tool code.
Quick Answer: Laravel Boost vs Laravel MCP
I keep seeing this confusion, so here's the split:
- Laravel Boost: an MCP server that exposes Laravel-ecosystem knowledge, your schema, routes, models, and logs so agents can navigate your app intelligently. You install it as a dev dependency and point Cursor at it. See Laravel Boost MCP for AI coding.
- laravel/mcp: the package to BUILD your own MCP servers (or clients) that expose domain-specific tools. Want agents to query your order API, schedule deliveries, or pull analytics? You build that server with laravel/mcp.
- NativePHP Super Stack: ships a sample Laravel MCP endpoint as part of its starter kit. That endpoint has no auth wired yet, per the docs.
Three pieces, different jobs. This post is about the second one.
Building Your First MCP Server
Generate a server class:
bash
php artisan make:mcp-server WeatherServerRegister it in routes/ai.php:
php
use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;
Mcp::web('/mcp/weather', WeatherServer::class);Or for local agents:
php
Mcp::local('weather', WeatherServer::class);Web servers respond to POST requests at that path. Local servers run via php artisan mcp:start weather.
Tools, Prompts, Resources
MCP has three primitives:
- Tools: callable functions the agent can invoke (e.g.
get_weather,query_orders) - Prompts: reusable templates or instructions (e.g. "how to handle Laravel model scoping")
- Resources: readable data URIs (e.g.
resource://logs/latest,resource://orders/1234)
Generate them:
bash
php artisan make:mcp-tool GetWeatherTool
php artisan make:mcp-prompt OrderWorkflowPrompt
php artisan make:mcp-resource OrderResourceThen register them in your server's $tools, $prompts, and $resources arrays.
The docs use a WeatherServer example throughout. I'm not going to paste the full skeleton here because the official docs already do that better than I can paraphrase. Point is: you write small, focused classes for each tool/prompt/resource, and the framework handles JSON-RPC, parameter validation, and error responses.
Searchable Tool Catalogs
Here's a feature I did not expect but makes sense once you think about it: searchable tool catalogs.
If your MCP server has 50+ tools, loading them all into the agent's context is wasteful. Instead, you can include ToolSearch::class in your $tools array:
php
use Laravel\Mcp\Server\Tools\ToolSearch;
protected array $tools = [
CurrentWeatherTool::class,
ToolSearch::class => [
HistoricalWeatherTool::class,
WeatherAlertsTool::class,
],
];This exposes two meta-tools to the agent:
search_tools: query available tools by keywordsexecute_tools: call one of the discovered tools
The agent searches first, then executes only what it needs. Docs say this keeps context lean when you have a large tool surface.
I would test this carefully with real agent behavior. In theory it's clever. In practice, agents sometimes ignore search and try to call everything anyway, or they search once and cache stale results. But the option is there.
Cache Hints for Prompt Caching
MCP supports prompt caching so repeated tool calls or resource reads don't burn tokens re-sending the same data.
Put the #[Cacheable] attribute on the server or on a resource class, not on individual tools. Per-method hints belong in the server's cacheHints() method:
php
use Laravel\Mcp\Enums\CacheScope;
use Laravel\Mcp\Server\Attributes\Cacheable;
#[Cacheable(ttlMs: 60_000, scope: CacheScope::Public)]
class WeatherServer extends Server
{
/**
* @return array<string, \Laravel\Mcp\Server\Attributes\Cacheable>
*/
protected function cacheHints(): array
{
return [
'tools/list' => new Cacheable(ttlMs: 30_000, scope: CacheScope::Public),
];
}
}You can also apply #[Cacheable] directly to a resource when you need a longer TTL than the server default.
The hints are advisory. The client decides whether to honor them. Tool CALLS are not cacheable per the MCP spec, but tool schemas and resource content are.
On the client side, you opt in:
php
$client->withCache()->callTool('get_weather', ['city' => 'Jakarta']);This is one of those features that's invisible until you're debugging token costs or slow agent loops. Then it matters.
Authentication: Sanctum or Passport
MCP servers exposed over HTTP need auth unless you're only running them on localhost.
Laravel MCP supports two patterns:
- Sanctum bearer tokens:
Authorization: Bearer <token>headers, using Laravel's built-inauth:sanctummiddleware - OAuth 2.1 via Passport: register OAuth routes with
Mcp::oauthRoutes(), protect the server withauth:api, and let agents authenticate via standard OAuth flows
The docs recommend Passport when possible because it's the standard OAuth flow and works better with multi-user/multi-tenant agent scenarios. But if your app already uses Sanctum, that works fine too.
What matters: the default starter examples in the docs have NO auth. You add it yourself via middleware. Don't expose an MCP endpoint to the internet without it.
NativePHP Super Stack ships with an MCP server at /mcp/superstack, and the README explicitly says it has no auth yet. That's fine for local exploration. It's not fine for production.
MCP Apps: Interactive HTML in Sandboxed Iframes
This one surprised me.
MCP can return not just data but also HTML apps that render in the agent's UI, sandboxed in an iframe.
Create the app resource with Artisan:
bash
php artisan make:mcp-app-resource WeatherDashboardAppThe generated class extends AppResource and carries #[AppMeta]:
php
use Laravel\Mcp\Server\AppResource;
use Laravel\Mcp\Server\Attributes\AppMeta;
#[AppMeta]
class WeatherDashboardApp extends AppResource
{
// ...
}Link a tool to that resource with #[RendersApp] so the host renders the UI when the tool runs:
php
use App\Mcp\Resources\WeatherDashboardApp;
use Laravel\Mcp\Server\Attributes\RendersApp;
#[RendersApp(resource: WeatherDashboardApp::class)]
class ShowWeatherDashboard extends Tool
{
// ...
}Return HTML (or a Blade view) from the resource. The agent renders it.
The docs mention a Boost skill called mcp-development that shows how to build MCP apps. I have not tried this yet, so I can't say how well it works in practice. But the concept is interesting: instead of returning JSON for the agent to narrate, you return an interactive UI that the user sees directly.
Use cases might include:
- Order dashboards
- Log viewers
- Quick analytics panels
- Approval workflows
Again, I'm cautious until I see this in the wild. But it's in the official docs, so it's not vaporware.
Client Side: Calling Other MCP Servers
Laravel MCP also includes a client for calling OTHER MCP servers from your Laravel app.
php
use Laravel\Mcp\Client;
$client = Client::local('php', ['artisan', 'mcp:start']);
$response = Client::web('https://external-mcp-server.com')
->callTool('get_forecast', ['city' => 'Jakarta']);Register named clients in your service provider:
php
use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;
Mcp::registerClient('weather', fn () => Client::web('https://weather-mcp.example.com'));Then resolve them:
php
$response = Mcp::client('weather')->callTool('get_forecast', ['city' => 'Jakarta']);This is useful if you're building agents that need to orchestrate multiple MCP servers or pull data from third-party MCP endpoints.
I have not used this in production yet, but the docs are clear, and the API looks reasonable.
Testing Your MCP Server
Laravel MCP includes an inspector for manual testing:
bash
php artisan mcp:inspector mcp/weatherThis launches the MCP Inspector, where you can call tools, get prompts, and read resources interactively.
For unit tests, call tools through the server's test helper:
php
use App\Mcp\Servers\WeatherServer;
use App\Mcp\Tools\GetWeatherTool;
$response = WeatherServer::tool(GetWeatherTool::class, ['city' => 'Jakarta']);
$response->assertOk();I would still add feature tests that POST to the MCP endpoint and assert the JSON-RPC response shape when the route stack matters.
What Changed in 1.0: Protocol 2026-07-28
The MCP protocol got a major revision on 28 Jul 2026. Laravel MCP 1.0 tracks that spec.
Key changes (from Laravel News and GitHub release notes):
server/discover replaces initialize
Modern MCP clients now call server/discover instead of the old initialize handshake.
Legacy clients that still send initialize will work. The server responds with an older protocol version (2025-11-25 or 2025-06-18) so they don't break.
But new clients should use server/discover. The docs don't say you have to change anything in your server code. The framework handles it.
Stateless Servers
The old protocol had MCP-Session-Id headers and SessionInitialized events. Those are gone.
MCP servers are now stateless by default. If you need session state, pass your own session ID in tool arguments or in a _meta field.
OAuth Changes
OAuth 2.1 now requires PKCE (Proof Key for Code Exchange). The old Dynamic Client Registration (DCR) is deprecated.
If you're using Mcp::oauthRoutes(), Laravel MCP handles PKCE for you. Just make sure your OAuth flow is up to date.
The protocol also adds Client ID Metadata Documents. I'm not clear on the details because the docs don't spell it out fully, but the point is: if you're using OAuth, you're on a newer spec now.
Upgrade from 0.9: MCP headers and route middleware
If you're upgrading from laravel/mcp 0.9, web clients must send MCP headers that match the JSON-RPC body (MCP-Protocol-Version, Mcp-Method, and for method-specific calls, Mcp-Name). Mismatches return HTTP 400 with JSON-RPC error code -32020.
Laravel MCP registers ValidateMcpHeaders on Mcp::web() routes automatically, so you do not add validate-mcp-headers yourself. Legacy initialize clients stay exempt from strict header matching.
From 1.2.0 onward, web MCP routes also validate the Origin header. If you proxy MCP behind a browser client, plan for that when you upgrade past 1.1.x.
Other breaking changes: see the UPGRADE guide and v1.0.0 release notes. For recent security fixes across Laravel MCP and related packages, see Laravel AI and MCP security advisories.
My Take
Laravel MCP 1.0 is solid tooling for a protocol that's still early.
If you're building internal tools, APIs for agents, or domain-specific automation that you want AI coding assistants to access, this is the Laravel way to do it.
The docs are clear. The package handles JSON-RPC plumbing, parameter validation, and protocol upgrades. You write focused tool/prompt/resource classes, and the framework wires them up.
The parts I'm still cautious about:
- Searchable tool catalogs: clever in theory, but I'd test agent behavior carefully. Agents don't always search when you think they will.
- MCP Apps: interesting, but I have not seen this in the wild yet. Sandboxed iframes in agent UIs are not common.
- OAuth complexity: PKCE is the right move, but OAuth setup is still OAuth setup. If you're building for one team and already use Sanctum, start there.
- Auth is your job: the package does not ship with auth wired. You add it via middleware. Don't skip that step.
The protocol is stateless now, which is good for scale and bad for nostalgia. If you built something on 0.9 that assumed sessions, you'll refactor.
Overall, this is Laravel doing what Laravel does: making a spec practical, giving you Artisan commands for boilerplate, and letting you focus on your domain logic instead of JSON-RPC wiring.
I'll be using this the next time I want an agent to query an order API or schedule a delivery. Not for a demo, but for the boring win of not writing a custom CLI wrapper or parsing CSV exports.
Who Should Try It This Week
Try Laravel MCP 1.0 if:
- You want AI agents to interact with your Laravel app's domain logic
- You already use MCP-capable agents (Cursor, Claude Code, etc.)
- You're comfortable with middleware, authentication, and JSON-RPC concepts
- You'd rather build on a Laravel package than roll your own protocol layer
Wait (or sandbox carefully) if:
- You're still learning Laravel or MCP fundamentals
- You need production OAuth but have never set up Passport before
- You're looking for a turnkey solution with auth pre-wired
Sources (checked 20 Nov 2026)
- Laravel MCP documentation (13.x): install, server/client APIs, tools/prompts/resources, searchable catalogs, cache hints, auth, MCP apps, testing
- Laravel Boost MCP for AI coding: how Boost relates to this package
- Laravel AI and MCP security advisories: recent security fixes in the ecosystem
- Laravel News: Laravel MCP 1.0 (published 2026-09-15): protocol 2026-07-28 changes, server/discover, stateless servers, OAuth 2.1 PKCE
- laravel/mcp on Packagist: v1.2.1 published 2026-11-17; requires PHP ^8.2 and illuminate/* ^12.41.1|^13.0 (Laravel 11 support dropped in 1.2.0)
- laravel/mcp v1.2.1 release on GitHub: current stable release
- laravel/mcp v1.0.0 release on GitHub: initial 1.0 breaking changes
Comments
No comments yet
Loading comments...