Laravel MCP 1.0 ships searchable catalogs and MCP 2026-07-28

Laravel MCP 1.0 is the first stable release of laravel/mcp, the package for building Model Context Protocol servers in Laravel. GitHub tagged v1.0.0 on 14 September 2026. The official Laravel account followed on 15 September, describing a protocol upgrade with support for MCP version 2026-07-28 — plus stateless servers, searchable tool catalogs, caching, improved OAuth, and MCP Apps updates.

The practical win for PHP teams is a large tool surface without stuffing every definition into a model's context. Keep always-on tools in the main list, search the rest on demand, and run 1.0 clients and older initialize clients against the same server.

Protocol 2026-07-28, with a fallback

The new revision uses server/discover instead of the initial initialize exchange. Clients that still connect with initialize keep working: the server responds with protocol version 2025-11-25 or 2025-06-18, depending on which one the client requests. The v1.0.0 GitHub notes include the change that serves those legacy initialize clients alongside the modern protocol.

Searchable catalogs

Register ToolSearch as an array key on the server's $tools property and leave common tools in the main list. The package registers search_tools, which accepts a query and a result limit and returns matching tools with names, descriptions, and expected inputs, and execute_tools, which runs one or more tools by name. Official docs say the search matches on tool name, description, and input schema, and that conditional registration still applies when catalog tools are searched or executed. Limits for one execute_tools call come from mcp.tool_search.max_tool_calls and mcp.tool_search.max_output_bytes.

Cache hints and stateless requests

Servers can tell clients which responses to reuse, how long to keep them, and whether they can be shared across users. Set a default with the Cacheable attribute (ttlMs and a public or private CacheScope), then override methods with cacheHints(). Laravel's MCP client honors those hints when you enable withCache(). Missing or zero ttlMs means no cache, and tool calls are not cacheable. Hints are advisory; a resource-level Cacheable attribute wins over method and server defaults. GitHub lists the client work as "Honor server caching hints on the client."

Under 2026-07-28 the server processes each request independently. Every HTTP request and stdio message carries the protocol version and client features in params._meta. The MCP-Session-Id header, Request::sessionId(), Request::setSessionId(), and the SessionInitialized event are gone. To correlate calls, pass your own identifier in request arguments or _meta.

OAuth is stricter

OAuth now requires PKCE. OAuthClient::redirect() throws an OAuthException if the authorization server omits code_challenge_methods_supported from its metadata. Client ID Metadata Documents are supported: client_id is an HTTPS URL for a JSON document, and Mcp::oAuthRoutesFor() serves it 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. MCP Apps support is listed under the extensions capability.

If you are on 0.9

ValidateMcpHeaders runs on every route registered through Mcp::web(). POSTs on 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, matching the tool or prompt name or the resource URI. A mismatch returns HTTP 400 with JSON-RPC error -32020. Older initialize clients that send no protocol metadata in _meta skip header validation. Tests that use postJson() need the headers and params._meta as well.

Read the searchable catalog and cache-hint sections in the Laravel MCP docs, then walk the v1.0.0 release notes and the Laravel News upgrade summary before you bump from 0.9.