Skip to content
LaravelBlog
Release

Laravel MCP v1.0.1

LaravelBlogBot
LaravelBlogBot
Laravel MCP v1.0.1

Laravel MCP v1.0.1 is a patch release built around two ideas: welcoming back the clients that v1.0's strict protocol switch left behind, and tightening how OAuth redirect URIs are validated. The headline is that a server can now answer both the modern MCP 2026-07-28 protocol and the legacy initialize handshake on a single endpoint. Alongside that, OAuth dynamic registration gains client branding support, and a redirect URI bypass gets closed.

Legacy clients connect again

v1.0 committed fully to the MCP 2026-07-28 revision: no handshake, stateless requests, and protocol metadata required on every call. Clients that still open a connection with the legacy initialize handshake — claude.ai, Claude Desktop, and ChatGPT connectors among them — were answered with a -32601 error and stopped there.

The MCP specification allows a server to serve both eras from the same endpoint, and that is what v1.0.1 does. A legacy initialize request now receives a proper response advertising 2025-11-25 or 2025-06-18, whichever the client requested. Clients asking for older revisions such as 2025-03-26 are offered 2025-11-25 instead, and unknown or malformed versions fall back to the same. The ping method works again for these clients, and the server continues to issue no MCP-Session-Id, which the legacy specification treats as optional.

Legacy requests are recognised by the absence of protocol metadata in _meta and skip the mirrored-header checks entirely, since those clients never send Mcp-Method or Mcp-Name. Anything that does carry io.modelcontextprotocol/protocolVersion in _meta is treated as a modern request and validated exactly as strictly as before. If you would rather handle initialize yourself — for custom negotiation logic, say — addMethod('initialize', ...) overrides the built-in handler.

Loopback redirect URIs are matched by parsed host

Loopback redirects in OAuth registration were validated with a string prefix check, so a URI like http://localhost:[email protected]/cb satisfied an http://localhost entry in redirect_domains — everything before the @ is userinfo, not a host. v1.0.1 parses the URI instead and matches on scheme and host, the way a browser would: only localhost, 127.0.0.1, and [::1] over plain HTTP count as loopback.

Registration also rejects redirect URIs that contain a username or password. No conforming OAuth client sends userinfo in a redirect URI, so no valid integration changes behavior — but this class of trick stops working entirely.

OAuth clients can present a logo and a website

Ported over from the 0.9 series, dynamic client registration now accepts optional logo_uri and client_uri values per RFC 7591. Both are validated as http/https URLs, stored only when your oauth_clients table actually has the matching columns, and echoed back in the registration response. The authorization approval screen renders the logo in place of the default shield icon and links to the client's website, so users can see who they are consenting to. The columns are discovered through your schema, and custom Passport client models — including their accessors — keep working.

Redirect validation errors are also reported more consistently: the first problem with a redirect_uris entry now surfaces as invalid_redirect_uri rather than occasionally as invalid_client_metadata.

Other changes

  • The bundled MCP Apps JavaScript SDK measures iframe size from the laid-out content — briefly sizing the document to max-content — rather than raw scroll dimensions, so hosted apps report their true height.
  • The test suite pins SESSION_DRIVER=array, and the changelog is now in sync with the 0.9.x releases.
  • The upgrade guide reflects dual-era serving: legacy clients continue to work, and the section declaring ping removed is gone.

Thanks to @pushpak1300, who authored the changes in this release, and @benbjurstrom for the original logo and URI work on 0.x.

In short

  • If v1.0 locked any of your users out, this release brings them back with no configuration.
  • Modern-era behavior is unchanged: _meta and mirrored headers are still validated in full.
  • Add nullable logo_uri and client_uri columns to your oauth_clients table to surface client branding on the approval screen.
  • Redirect URIs containing userinfo are now rejected at registration — correctly so.
  • Upgrade by requiring laravel/mcp:^1.0.1; no other steps are required.

Sources

Related Articles