laravel/mcp

• Align protocol error codes with MCP 2026-07-28 by @pushpak1300 in #282
• Add the server/discover method by @pushpak1300 in #295
• Serve only MCP 2026-07-28 and drop the initialize handshake by @pushpak1300 in #296
• Require the protocol metadata on every request by @pushpak1300 in #297
• Complete every result with the server info metadata by @pushpak1300 in #283
• Remove server session state for the stateless transports by @pushpak1300 in #285
• Validate the mirrored MCP request headers over HTTP by @pushpak1300 in #286
• Place the mirrored header contract in the protocol layer by @pushpak1300 in #299
• [master] Update .gitattributes by @jackbayliss in #308
• Add caching hints to every cacheable result by @pushpak1300 in #301
• Advertise MCP Apps through the extensions capability by @pushpak1300 in #303
• Negotiate modern and legacy protocol eras by @pushpak1300 in #304
• Restore Laravel 11 compatibility in implementation parsing by @pushpak1300 in #315
• Launch the MCP Inspector with a modern era config by @pushpak1300 in #316
• Acknowledge and gracefully close subscriptions/listen requests by @pushpak1300 in #318
• Mirror annotated tool parameters into client request headers by @pushpak1300 in #300
• Assert tools/list returns tools in declaration order by @pushpak1300 in #320
• Port searchable tool catalogs and inspector route prompts from 0.x by @pushpak1300 in #324
• Prefer Client ID Metadata Documents over dynamic registration by @pushpak1300 in #323
• Add 1.0 upgrade guide by @pushpak1300 in #319

What's Changed

• Let an MCP App shrink by measuring the body in size notifications by @sergeevpasha in #344
• Validate loopback redirect URIs by parsed host by @pushpak1300 in #351

New Contributors

• @sergeevpasha made their first contribution in #344

Full Changelog: v0.9.5...v0.9.6

What's Changed

• Add oauth client logo and uri by @benbjurstrom in #337

New Contributors

• @benbjurstrom made their first contribution in #337

Full Changelog: v0.9.4...v0.9.5

What's Changed

• [0.x] Update .gitattributes by @jackbayliss in #309
• Add searchable tool catalogs by @pushpak1300 in #317

Full Changelog: v0.9.3...v0.9.4

What's Changed

• Pin MCP Inspector to v1-latest by @pushpak1300 in #307
• Prompt for route parameter values in mcp:inspector by @lazerg in #294

Full Changelog: v0.9.2...v0.9.3

What's Changed

• Bump actions/checkout from 7.0.0 to 7.0.1 in the github-actions group by @dependabot[bot] in #274
• Fix mcp:inspector passing mcp:start {handle} as one argument instead of two by @johankrijt in #281

New Contributors

• @johankrijt made their first contribution in #281

Full Changelog: v0.9.1...v0.9.2

• Reject malformed JSON-RPC parameters by @pushpak1300 in #273

What's Changed

• Use negotiated MCP protocol version for HTTP client requests by @andrew-downey in #257
• Improve test error when unexpected errors are found in response by @axlon in #259
• Fix schema return type in tool stub by @axlon in #261
• Bump stefanzweifel/git-auto-commit-action from 7.1.0 to 7.2.0 in the github-actions group by @dependabot[bot] in #263
• Bump stefanzweifel/git-auto-commit-action from 7.1.0 to 7.2.0 in the github-actions group by @dependabot[bot] in #264
• Fix nested OAuth resource path with preceding route parameters by @lazerg in #262
• Add #[SensitiveParameter] to parameters carrying secrets by @axlon in #265
• Fix CursorPaginator returning trailing items for a negative cursor offset by @dfinchenko in #267
• Update phpdoc for assertStructuredContent by @chrisvanlier2005 in #268
• Fix DCR scope persistence for Passport clients by @Gujiassh in #270
• Serialize structured content before asserting by @chrisvanlier2005 in #269

New Contributors

• @andrew-downey made their first contribution in #257
• @axlon made their first contribution in #259
• @dfinchenko made their first contribution in #267
• @chrisvanlier2005 made their first contribution in #268

Full Changelog: v0.8.2...v0.9.0

Upgrading To v0.9.0 From v0.8.0

Custom Client Transports

Likelihood Of Impact: low

The Laravel\Mcp\Client\Contracts\Transport contract now requires a setProtocolVersion method. The client calls this method after the initialize handshake so the transport can send the negotiated protocol version on subsequent requests.

If your application implements this contract, add the method to your transport:

public function setProtocolVersion(string $version): void
{
    $this->protocolVersion = $version;
}

Transports that do not send per-request headers may implement the method as a no-op, as the first-party StdioTransport does.

Client Protocol Version Negotiation

Likelihood Of Impact: Medium

The MCP client now validates the negotiated protocol version against the new ProtocolVersion::clientSupported() method rather than ProtocolVersion::supported(). The client supports 2025-11-25 and 2025-06-18.

Connecting to a server that negotiates 2025-03-26 or 2024-11-05 previously succeeded and will now throw a Laravel\Mcp\Exceptions\ClientException.
The ProtocolVersion::supported() method is unchanged and still reports every version the server accepts.

What's Changed

• Bump shivammathur/setup-php from 2.37.1 to 2.37.2 in the github-actions group by @dependabot[bot] in #252
• feat: compute default AppResource ui.domain from current URL for Claude compatibility by @cirolosapio in #231
• Bump actions/checkout from 6.0.3 to 7.0.0 in the github-actions group by @dependabot[bot] in #255
• Allow OAuth client registration without a client name by @lazerg in #254

New Contributors

• @cirolosapio made their first contribution in #231
• @lazerg made their first contribution in #254

Full Changelog: v0.8.1...v0.8.2

What's Changed

• Add resources support to the MCP client by @pushpak1300 in #243
• feat: automatically convert model not found exceptions to proper error messages by @calebdw in #244
• Add withHeaders() to the MCP web client by @pushpak1300 in #250
• Bump actions/checkout from 6.0.2 to 6.0.3 in the github-actions group by @dependabot[bot] in #251
• Centralize exception handling in method handlers with debug-aware errors by @pushpak1300 in #249

New Contributors

• @calebdw made their first contribution in #244

Full Changelog: v0.8.0...v0.8.1

What's Changed

• Add MCP client tool listing and calling by @pushpak1300 in #226
• Add MCP client Streamable HTTP transport by @pushpak1300 in #227
• Add named MCP clients with tool list caching by @pushpak1300 in #228
• Extract caching into RegisteredClient by @pushpak1300 in #230
• GitHub Actions hardening by @nunomaduro in #234
• Remove MCP client tool-list caching layer by @pushpak1300 in #235
• Add Dependabot cooldown of 5 days by @nunomaduro in #237
• Enable Dependabot auto-merge by @nunomaduro in #238
• Make MCP client tools cacheable via recipe serialization by @pushpak1300 in #239
• Add OAuth layer for MCP web client by @pushpak1300 in #233
• Fix Mcp alias: correct facade class name by @adelf in #241
• Add prompts support to the MCP client by @pushpak1300 in #242

New Contributors

• @adelf made their first contribution in #241

Full Changelog: v0.7.2...v0.8.0

What's Changed

• return $this from ->dump() by @Gummibeer in #223
• Resolve URI template variables when testing resources by @pushpak1300 in #225
• Add MCP client foundation with stdio transport and ping by @pushpak1300 in #216

New Contributors

• @Gummibeer made their first contribution in #223

Full Changelog: v0.7.1...v0.7.2

• Return 201 from OAuth client registration per RFC 7591 by @danniehansen in https://github.com/laravel/mcp/pull/207
• Fix TypeError when JSON-RPC request id is not a string or int by @pushpak1300 in https://github.com/laravel/mcp/pull/208
• Add ResourceLink content type (MCP spec 2025-06-18) by @rupeshstha in https://github.com/laravel/mcp/pull/200
• Extract JSON-RPC primitives to shared namespace for client reuse by @pushpak1300 in https://github.com/laravel/mcp/pull/211
• Pin GitHub Actions to commit SHAs and add Dependabot config by @joetannenbaum in https://github.com/laravel/mcp/pull/213
• Bump shivammathur/setup-php from 2.37.0 to 2.37.1 in the github-actions group by @dependabot[bot] in https://github.com/laravel/mcp/pull/214
• Extract protocol versions to shared enum for client reuse by @pushpak1300 in https://github.com/laravel/mcp/pull/215
• Add Icon and Implementation (MCP spec 2025-11-25) by @pushpak1300 in https://github.com/laravel/mcp/pull/219

• docs(readme): point test badge to workflow file URL by @Gujiassh in https://github.com/laravel/mcp/pull/201
• Add MCP UI App support by @pushpak1300 in https://github.com/laravel/mcp/pull/196

What's Changed

• Fix route:cache memory exhaustion caused by circular reference by @radumetes in https://github.com/laravel/mcp/pull/197

New Contributors

• @radumetes made their first contribution in https://github.com/laravel/mcp/pull/197

Full Changelog: https://github.com/laravel/mcp/compare/v0.6.6...v0.6.7

• fix: preserve unicode characters in JSON-RPC responses by @indigoram89 in https://github.com/laravel/mcp/pull/191
• Add MCP UI App support with interactive HTML resources by @pushpak1300 in https://github.com/laravel/mcp/pull/182
• Revert "Add MCP UI App support with interactive HTML resources" by @pushpak1300 in https://github.com/laravel/mcp/pull/195
• Preserve existing OAuth discovery routes by @Gujiassh in https://github.com/laravel/mcp/pull/192

What's Changed

• fix: support custom URI schemes in OAuth client registration by @alexis-riot in https://github.com/laravel/mcp/pull/181
• fix: return tool errors for auth failures by @Gujiassh in https://github.com/laravel/mcp/pull/186
• fix: authorization_servers and issuer should be the root URL, not the resource path by @pktharindu in https://github.com/laravel/mcp/pull/185

New Contributors

• @alexis-riot made their first contribution in https://github.com/laravel/mcp/pull/181
• @pktharindu made their first contribution in https://github.com/laravel/mcp/pull/185

Full Changelog: https://github.com/laravel/mcp/compare/v0.6.4...v0.6.5

• Remove redundant "When to Apply" section from skill body by @pushpak1300 in https://github.com/laravel/mcp/pull/175
• Validate OAuth registration client names by @Gujiassh in https://github.com/laravel/mcp/pull/177
• Add nested OAuth resource metadata regression coverage by @Gujiassh in https://github.com/laravel/mcp/pull/178

• Add assertStructuredContent($closure) support by @gdebrauwer in https://github.com/laravel/mcp/pull/172

• Makes imports consistent by @nunomaduro in https://github.com/laravel/mcp/pull/171

• Add missing @throws annotation to toJsonRpcResponse method by @mohammadRezaei1380 in https://github.com/laravel/mcp/pull/166
• Update boost skill description and remove core guideline by @pushpak1300 in https://github.com/laravel/mcp/pull/170

• Allow localhost redirect with dynamic ports by @dylanbr in https://github.com/laravel/mcp/pull/156
• Add Image and Audio content types with Storage integration by @pushpak1300 in https://github.com/laravel/mcp/pull/155
• Remove incorrect Response::structured docblock throw by @nathanheffley in https://github.com/laravel/mcp/pull/160
• Add Boost Guidelines & Skills by @pushpak1300 in https://github.com/laravel/mcp/pull/153
• Add facade documenter workflow and sync Mcp facade docblocks by @pushpak1300 in https://github.com/laravel/mcp/pull/161
• Add Allow header to 405 responses for unsupported HTTP methods by @pushpak1300 in https://github.com/laravel/mcp/pull/162
• Fix CI failures in facade documenter and static analysis by @pushpak1300 in https://github.com/laravel/mcp/pull/163
• Add example of registering MCP Tool in a Server by @mohammadRezaei1380 in https://github.com/laravel/mcp/pull/164

• Update stubs to use attribute syntax by @pushpak1300 in https://github.com/laravel/mcp/pull/157

• Add attribute alternatives for primitive and server configuration by @pushpak1300 in https://github.com/laravel/mcp/pull/154

• Add configurable JSON response formatting by @LAlex14 in https://github.com/laravel/mcp/pull/150
• Change JSON response formatting to compact by default by @pushpak1300 in https://github.com/laravel/mcp/pull/151
• Add SessionInitialized event by @jessarcher in https://github.com/laravel/mcp/pull/152

• Update command description formatting to match all other Laravel Commands by @matthewjohns0n in https://github.com/laravel/mcp/pull/146
• Add host and port options to MCP Inspector command by @pushpak1300 in https://github.com/laravel/mcp/pull/147
• Fix streaming generator handling under Octane by @csfh in https://github.com/laravel/mcp/pull/148

• Rename stub files with mcp- prefix and update references by @pushpak1300 in https://github.com/laravel/mcp/pull/145

• Drop Php 8.1 Support by @pushpak1300 in https://github.com/laravel/mcp/pull/141
• Add assertStructuredContent method by @gdebrauwer in https://github.com/laravel/mcp/pull/140
• Supports Laravel 13 by @crynobone in https://github.com/laravel/mcp/pull/144

• Fix JSON-RPC notification param serialization by @csfh in https://github.com/laravel/mcp/pull/136

• Implement MCP scope registration in service provider by @pushpak1300 in https://github.com/laravel/mcp/pull/131

What's Changed

• fix: correct header name to MCP-Session-Id by @batosai in https://github.com/laravel/mcp/pull/132

New Contributors

• @batosai made their first contribution in https://github.com/laravel/mcp/pull/132

Full Changelog: https://github.com/laravel/mcp/compare/v0.5.0...v0.5.1

• Add Completion Support by @pushpak1300 in https://github.com/laravel/mcp/pull/127

What's Changed

• Bump Laravel version by @florianraith in https://github.com/laravel/mcp/pull/128

New Contributors

• @florianraith made their first contribution in https://github.com/laravel/mcp/pull/128

Full Changelog: https://github.com/laravel/mcp/compare/v0.4.1...v0.4.2

What's Changed

• Add 2025-11-25 to supported protocolVersion by @pushpak1300 in https://github.com/laravel/mcp/pull/125

Full Changelog: https://github.com/laravel/mcp/compare/v0.4.0...v0.4.1

What's Changed

• Add Annotation Support on Resources by @pushpak1300 in https://github.com/laravel/mcp/pull/111
• Add structuredContent & outputSchema Support by @macbookandrew in https://github.com/laravel/mcp/pull/83
• Standardise Role case names by @pushpak1300 in https://github.com/laravel/mcp/pull/116
• Test Improvements by @crynobone in https://github.com/laravel/mcp/pull/115
• PHP 8.5 Compatibility by @pushpak1300 in https://github.com/laravel/mcp/pull/114
• Fix casing for keys in OAuthRegisterController response by @pushpak1300 in https://github.com/laravel/mcp/pull/117
• Update JsonSchema usage by @pushpak1300 in https://github.com/laravel/mcp/pull/120
• Add Support For Resource Templates by @pushpak1300 in https://github.com/laravel/mcp/pull/113
• Remove unused resource-template stub and update JsonSchema import by @pushpak1300 in https://github.com/laravel/mcp/pull/122

New Contributors

• @macbookandrew made their first contribution in https://github.com/laravel/mcp/pull/83
• @crynobone made their first contribution in https://github.com/laravel/mcp/pull/115

Breaking Change

1. Case Name Updates (https://github.com/laravel/mcp/pull/116)

Applications referencing the previous case names will need manual updates.

Required changes

• Role::ASSISTANT should be updated to Role::Assistant
• Role::USER should be updated to Role::User

Make sure your codebase reflects these changes before upgrading to avoid build or runtime errors.

2. JsonSchema Contract Change (https://github.com/laravel/mcp/pull/120)

Tool implementations that explicitly type hint Illuminate\JsonSchema\JsonSchema in their schema() or outputSchema() methods must update to use the contract interface Illuminate\Contracts\JsonSchema\JsonSchema.

Migration Guide

Before

use Illuminate\JsonSchema\JsonSchema;

public function schema(JsonSchema $schema): array
{
    //
}

After

use Illuminate\Contracts\JsonSchema\JsonSchema;

public function schema(JsonSchema $schema): array
{
    //
}

This affects only custom tool classes that override the schema methods. The update is minimal, requiring only the import change to the contract interface.

Full Changelog: https://github.com/laravel/mcp/compare/v0.3.4...v0.4.0

• Add _meta support by @pushpak1300 in https://github.com/laravel/mcp/pull/106
• Remove non-spec fields from resource content responses by @pushpak1300 in https://github.com/laravel/mcp/pull/110

• Add MCP service provider to testbench config by @zacksmash in https://github.com/laravel/mcp/pull/100
• Fix client_name rename in oauth registrar by @mikebouwmans in https://github.com/laravel/mcp/pull/104
• fix: allow multi-segment issuer paths by @isaac-bowen in https://github.com/laravel/mcp/pull/105

What's Changed

• Ensure the property field exists in tool input schemas by @pushpak1300 in https://github.com/laravel/mcp/pull/97

New Contributors

• @pushpak1300 made their first contribution in https://github.com/laravel/mcp/pull/97

Full Changelog: https://github.com/laravel/mcp/compare/v0.3.1...v0.3.2

• refactor: move to first class callable by @ashleyhindle in https://github.com/laravel/mcp/pull/94
• Cast client_id to string in JSON response by @mostafa-rz in https://github.com/laravel/mcp/pull/93
• Feature: adds security to the OAuth registration endpoint by @jsandfordhughescoop in https://github.com/laravel/mcp/pull/87

• Add assertDontSee() to TestResponse and extend test coverage by @mattwells-coex in https://github.com/laravel/mcp/pull/74
• Fix tool annotation type error when using custom Attributes by @Daanra in https://github.com/laravel/mcp/pull/75
• Add Macroable and Conditionable traits to some core classes by @mattwells-coex in https://github.com/laravel/mcp/pull/76

• feat: default the MCP inspector to 'stdio' when inspecting a local server by @ashleyhindle in https://github.com/laravel/mcp/pull/52
• Fix error message formatting in InspectorCommand by @aymanebouljam in https://github.com/laravel/mcp/pull/53
• InspectorCommand error message improvement by @szabi-bc in https://github.com/laravel/mcp/pull/55
• Uses nowdoc for LLMs by @nunomaduro in https://github.com/laravel/mcp/pull/56
• Remove .junie Detritus by @yitzwillroth in https://github.com/laravel/mcp/pull/59
• Enhance documentation consistency and Tool class annotations by @aymanebouljam in https://github.com/laravel/mcp/pull/57
• add basic sessionid support by @ashleyhindle in https://github.com/laravel/mcp/pull/58
• Fixes artisan optimize command by @nunomaduro in https://github.com/laravel/mcp/pull/66
• [0.x] Adds support for custom request classes by @nunomaduro in https://github.com/laravel/mcp/pull/63

• First official "beta" release of Laravel MCP package.

Initial pre-release.