Laravel MCP 1.0 Released: Stateless Servers, Tool Search and Cache Hints

Laravel MCP reached 1.0 in mid-September 2026 (v1.0.0 was tagged on 14 September, followed quickly by v1.0.1). It is the first stable release of laravel/mcp, the first-party package for building Model Context Protocol servers in a Laravel application, so AI agents such as Claude, ChatGPT or Cursor can call your application's tools, read its resources and use its prompts.

The headline is a protocol upgrade to MCP 2026-07-28. Around it come stateless servers, searchable tool catalogs, cache hints and a stricter OAuth flow. It is also a breaking release for anyone on 0.x, so this post covers both what is new and how to upgrade. For more on this topic, see all my posts about MCP.

What is Laravel MCP?

Laravel MCP lets you describe an MCP server as ordinary Laravel classes: a server class that registers tools (actions the AI can run), resources (data it can read) and prompts (reusable instructions). You expose the server over HTTP for remote agents or as an Artisan command for local tools, and Laravel handles the protocol, validation and authentication.

I use it on this site: my blog workflow runs through an MCP server, and the same package powers Laravel Boost, which gives coding agents deep context about your Laravel app. If you want your app to *call* AI models rather than be called by them, that is the job of the Laravel AI SDK; MCP is the other direction.

Laravel MCP 1.0 requires PHP 8.2+ and supports Laravel 11, 12 and 13. If you are on a newer PHP, see what changed in PHP 8.4 and PHP 8.5.

What's new in Laravel MCP 1.0

MCP protocol 2026-07-28

Servers now speak protocol revision 2026-07-28. Instead of the old initialize handshake, clients discover the server with server/discover and send protocol metadata in _meta on every request.

Older clients are not left behind: a client that still sends initialize without protocol metadata is served on the previous protocol versions (2025-11-25 or 2025-06-18), so existing integrations keep working while agents catch up.

Stateless servers

Every request is now handled on its own. There is no session to create, track or expire, which makes MCP servers much easier to run behind load balancers, on serverless platforms and on queues of short-lived workers.

As part of this, the MCP-Session-Id header, Request::sessionId(), Request::setSessionId() and the SessionInitialized event are gone. If you relied on a session ID, pass the identifier you need through the tool arguments or _meta instead.

Searchable tool catalogs

Large MCP servers used to send every tool definition to the model up front, which wastes context and makes the model worse at picking the right tool. With ToolSearch, you keep the everyday tools visible and put the long tail behind a search:

use Laravel\Mcp\Server\Tools\ToolSearch;

protected array $tools = [
    CurrentWeatherTool::class,
    ToolSearch::class => [
        HistoricalWeatherTool::class,
        WeatherAlertsTool::class,
    ],
];

The agent now sees CurrentWeatherTool plus two helper tools, search_tools and execute_tools. It searches the catalog when it needs something specific and runs the matching tool by name. Limits are configurable through mcp.tool_search.max_tool_calls (25 by default) and mcp.tool_search.max_output_bytes (64 KB by default).

Cache hints

Servers can now tell clients which responses may be cached, for how long and whether the cache is private to the user or shared. Set a default on the server with the Cacheable attribute:

use Laravel\Mcp\Enums\CacheScope;
use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Attributes\Cacheable;

#[Cacheable(ttlMs: 60_000, scope: CacheScope::Public)]
class WeatherServer extends Server
{
    //
}

The TTL is in milliseconds and the scope defaults to CacheScope::Private. The Laravel MCP client honours these hints too, so repeated reads of data that rarely changes, like a product catalogue or documentation, no longer hit your application every time.

Stricter OAuth: PKCE and Client ID Metadata Documents

OAuth for MCP clients got two security upgrades:

• PKCE is required. The authorization server must advertise code_challenge_methods_supported; otherwise the redirect throws an OAuthException.
• Client ID Metadata Documents. Your client_id becomes an HTTPS URL pointing to a metadata document, served automatically at GET /mcp/oauth/{client}/client-metadata.json. In that mode there is no client secret, so $token->clientSecret is null.

Smaller improvements

• Nested input with dot notation in tool requests, the same way you read nested request data elsewhere in Laravel.
• New test assertions for checking which tools, prompts and resources are registered, including assertNotRegistered.
• OAuth challenges exposed on authenticated MCP routes, so clients get a proper challenge instead of a bare 401.
• Stricter JSON-RPC validation of notification parameters.
• An MCP conformance suite you can run locally against your server.

Getting started with Laravel MCP

Install the package and publish the routes/ai.php file:

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

Create a server and a tool:

php artisan make:mcp-server WeatherServer
php artisan make:mcp-tool CurrentWeatherTool

A tool has a handle() method and an input schema():

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

        // Get weather...

        return Response::text('The weather is...');
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('The location to get the weather for.')
                ->required(),
        ];
    }
}

Register the tool in the server's $tools array, then expose the server in routes/ai.php, either over HTTP or as a local Artisan command:

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

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

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

Try it with the built-in MCP Inspector before connecting a real agent:

php artisan mcp:inspector mcp/weather

For a real-world example of what you can build with this, read how I automated my blog workflow with Laravel MCP: drafting posts, uploading covers and filling in SEO metadata straight from an AI assistant.

Upgrading from Laravel MCP 0.x to 1.0

Most apps only need a few changes, but check each of these:

1. Update the constraint in composer.json to "laravel/mcp": "^1.0" and run composer update laravel/mcp.
2. New request headers. POST requests must send MCP-Protocol-Version and Mcp-Method, plus Mcp-Name for tool calls, prompt gets and resource reads. The values must match the JSON-RPC body; a mismatch returns HTTP 400 with error code -32020. The ValidateMcpHeaders middleware enforces this on every route registered with Mcp::web().
3. Update feature tests that call your endpoint with postJson(): add those headers and the _meta protocol fields to the request body.
4. Remove session code: calls to Request::sessionId() or Request::setSessionId(), the MCP-Session-Id header and listeners for SessionInitialized.
5. Error codes: unresolvable resource URIs now return -32602 instead of -32002. Use the new Laravel\Mcp\Enums\ErrorCode enum rather than hard-coded numbers.
6. OAuth: make stored client-secret columns nullable, and confirm APP_URL is correct in production because it forms the client metadata URL.
7. UI capability: replace Server::CAPABILITY_UI with protected array $extensions = [Extension::Ui];.
8. Custom transports implement the new UsesProtocol interface instead of calling setProtocolVersion().

The official upgrade guide has before-and-after examples for each step. If you are upgrading the framework at the same time, check what's new in Laravel 13 and the latest Laravel 13.30 release, which includes a Storage::path() security fix.

Should you upgrade?

If you are starting a new MCP server, start on 1.0: it is the stable API and the current protocol. For existing 0.x servers, the upgrade is worth it for stateless requests and tool search alone, but budget time for the header changes in your tests and any OAuth integrations. Because legacy clients are still served, you can upgrade the server first and let your AI clients follow.

Keep reading: more Laravel articles and everything tagged Laravel AI.

Sources: Laravel News: Laravel MCP 1.0 Is Released, laravel/mcp v1.0.0 release notes, Laravel MCP documentation.