Laravel Releases MCP 1.0 With New AI Tool Discovery and OAuth

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, introducing support for the MCP 2026-07-28 protocol revision and several new features for AI-powered applications.

Key Highlights

• Laravel MCP 1.0 is the package’s first stable release.
• Adds support for MCP revision 2026-07-28.
• Introduces searchable tool catalogs to reduce AI context usage.
• Adds cache hints and support for stateless MCP servers.
• OAuth authorization now requires PKCE.
• Introduces Client ID Metadata Documents.
• Existing clients using the older initialize exchange remain supported.

Searchable Tool Catalogs Reduce AI Context Usage

Laravel MCP 1.0 introduces searchable tool catalogs, allowing AI agents to discover tools only when they are needed.

Instead of sending every available tool definition to a model, developers can keep commonly used tools readily available while placing less frequently used tools behind ToolSearch.

This approach can reduce the amount of tool information occupying an AI model’s context window while allowing agents to access additional capabilities when required.

Cache Hints Improve Response Reuse

The Laravel MCP client can follow cache hints when caching is enabled with withCache().

Related Articles:

Responses containing a valid ttlMs value can be cached according to the specified duration, while responses with a missing or zero ttlMs are not cached.

Tool calls themselves are not cacheable.

Stateless Servers Added

The new MCP protocol also introduces support for stateless servers, allowing each request to be processed independently.

Under the new approach, HTTP requests and standard input/output messages include the protocol version and supported client features through params._meta.

Several session-related components have been removed, including the MCP-Session-Id header, Request::sessionId(), Request::setSessionId(), and the SessionInitialized event.

Developers who need to associate related requests must instead provide their own identifier through request arguments or _meta.

Laravel MCP Strengthens OAuth Support

Laravel MCP 1.0 requires OAuth authorization servers to support PKCE. The package now throws an OAuthException when the authorization server’s metadata does not provide supported code challenge methods.

The release also adds support for Client ID Metadata Documents, allowing a client ID to be represented by an HTTPS URL pointing to a JSON document describing the client.

Laravel can serve the metadata document through an MCP OAuth route and can use it when supported by the authorization server, while falling back to Dynamic Client Registration where necessary.

The update also fixes an issue that could cause a new client to be registered with an authorization server every time the OAuth redirect process was executed.

Upgrade Requirements for Laravel Developers

Developers upgrading from Laravel MCP 0.9 are advised to review how their clients connect and send requests.

The new ValidateMcpHeaders middleware runs on routes registered through Mcp::web().

POST requests using the new protocol require MCP-Protocol-Version and Mcp-Method headers that correspond with the request body. Calls involving tools/call, prompts/get and resources/read also require an Mcp-Name header.

Header mismatches return HTTP 400 with JSON-RPC error code -32020.

However, older clients using initialize without protocol metadata in _meta remain exempt from the new header validation.

The Laravel MCP 1.0 upgrade also includes changes involving error codes, the removal of the Server::CAPABILITY_UI constant and updates to the custom transport contract.