Laravel MCP 1.0 Is Released

The Laravel team has released Laravel MCP 1.0, the first stable version of its package for building Model Context Protocol (MCP) servers in Laravel applications. These servers let AI applications use your app's tools and data, and this release brings support for MCP revision 2026-07-28.

Here's what's in it:

Protocol 2026-07-28 uses server/discover in place of the initial initialize exchange
Searchable tool catalogs let an agent look up tools as it needs them
Cache hints tell the client which responses it can reuse and for how long
Stateless servers process each request independently under the new protocol
OAuth changes require PKCE support and add a new way to identify clients
MCP Apps support is now listed under the extensions capability

Clients that still connect with initialize continue to work. The server responds with protocol version 2025-11-25 or 2025-06-18, depending on which one the client requests.

Searchable Tool Catalogs

Every tool definition you send to a model takes up room in its context window, the amount of information it can work with at once. ToolSearch lets you keep the common tools in the main list and put the rest behind a search:

use App\Mcp\Tools\CurrentWeatherTool;
use App\Mcp\Tools\HistoricalWeatherTool;
use App\Mcp\Tools\WeatherAlertsTool;
use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Tools\ToolSearch;
 
class WeatherServer extends Server
{
    protected array $tools = [
        // Always available to the agent...
        CurrentWeatherTool::class,
 
        // Searched only when needed...
        ToolSearch::class => [
            HistoricalWeatherTool::class,
            WeatherAlertsTool::class,
        ],
    ];
}

The package registers two tools to handle this. search_tools accepts a query and a result limit, then returns matching tools with their names, descriptions, and expected inputs. execute_tools runs one or more tools by name. The agent can find and use a tool without loading the whole catalog. (#324)

Cache Hints

A server can now tell clients which responses they can cache, how long to keep them, and whether they can share them across users. Set a default with the Cacheable attribute, then use cacheHints() to override it for individual methods:

use Laravel\Mcp\Enums\CacheScope;
use Laravel\Mcp\Server\Attributes\Cacheable;
 
#[Cacheable(ttlMs: 60_000, scope: CacheScope::Public)]
class WeatherServer extends Server
{
    /**
     * Get the cache hints for individual MCP methods.
     *
     * @return array<string, Cacheable>
     */
    protected function cacheHints(): array
    {
        return [
            'tools/list' => new Cacheable(ttlMs: 30_000),
        ];
    }
}

Laravel's MCP client follows these hints when you enable caching with withCache(). Responses with a missing or zero ttlMs are not cached. Tool calls are not cacheable. (#301, #326)

Stateless Servers

With the new protocol, the server processes each request independently. Every HTTP request and standard input/output (stdio) message includes the protocol version and the features the client supports in params._meta.

The MCP-Session-Id header, Request::sessionId(), Request::setSessionId(), and the SessionInitialized event have been removed. To track related calls, pass your own identifier in the request arguments or _meta. (#285)

OAuth

OAuth authorization now requires PKCE support. OAuthClient::redirect() throws an OAuthException if the authorization server leaves code_challenge_methods_supported out of its metadata. Previously, it only rejected servers that included the field without S256 support.

There's also support for Client ID Metadata Documents. With this method, your client_id is an HTTPS URL for a JSON document that describes your client, and Mcp::oAuthRoutesFor() serves that document at GET /mcp/oauth/{client}/client-metadata.json. If you have not supplied a client ID, Laravel uses the document when the authorization server supports it, and falls back to Dynamic Client Registration, which MCP 2026-07-28 deprecates.

When a metadata document is used, $token->clientSecret is null, so any database column that stores it must accept null. This also fixes a bug that registered a new client on the authorization server every time redirect() ran. (#323, #342)

Upgrade Notes

If you are upgrading from 0.9, check how your clients connect and send requests. The new ValidateMcpHeaders middleware runs on every route registered through Mcp::web().

POST requests using the new protocol need MCP-Protocol-Version and Mcp-Method headers that match the body. Calls to tools/call, prompts/get, and resources/read also need Mcp-Name. This header must match the tool or prompt name, or the resource URI.

Tests that send these requests with postJson() need the headers and the params._meta fields too. A header mismatch returns HTTP 400 with JSON-RPC error code -32020. Older clients that use initialize and send no protocol metadata in _meta are exempt from header validation.

The full list, including error code changes, the removed Server::CAPABILITY_UI constant, and the custom transport contract, is in the 1.0 upgrade guide.