È stato rilasciato Laravel MCP 1.0

Il team di Laravel ha rilasciato Laravel MCP 1.0, la prima versione stabile del pacchetto per creare server Model Context Protocol (MCP) nelle applicazioni Laravel. Questi server permettono alle applicazioni AI di usare gli strumenti e i dati della tua app, e questa release introduce il supporto per la revisione MCP 2026-07-28.

Ecco cosa contiene:

• Protocollo 2026-07-28: usa server/discover al posto dello scambio iniziale initialize
• Cataloghi di strumenti ricercabili: permettono a un agente di cercare gli strumenti nel momento in cui gli servono
• Suggerimenti di cache: indicano al client quali risposte può riutilizzare e per quanto tempo
• Server stateless: con il nuovo protocollo elaborano ogni richiesta in modo indipendente
• Modifiche a OAuth: richiedono il supporto a PKCE e aggiungono un nuovo modo per identificare i client
• Il supporto a MCP Apps è ora elencato nella capability extensions

I client che si connettono ancora con initialize continuano a funzionare. Il server risponde con la versione di protocollo 2025-11-25 o 2025-06-18, a seconda di quale viene richiesta dal client.

Cataloghi di strumenti ricercabili

Ogni definizione di strumento che invii a un modello occupa spazio nella sua context window, la quantità di informazioni con cui può lavorare contemporaneamente. ToolSearch ti permette di mantenere gli strumenti più comuni nell'elenco principale e di mettere gli altri dietro una ricerca:

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

Il pacchetto registra due strumenti per gestire questo meccanismo. search_tools accetta una query e un limite di risultati, poi restituisce gli strumenti corrispondenti con i loro nomi, le descrizioni e gli input previsti. execute_tools esegue uno o più strumenti per nome. L'agente può trovare e usare uno strumento senza caricare l'intero catalogo. (#324)

Suggerimenti di cache

Ora un server può indicare ai client quali risposte possono essere messe in cache, per quanto tempo conservarle e se possono essere condivise tra utenti. Imposta un valore predefinito con l'attributo Cacheable, poi usa cacheHints() per sovrascriverlo per singoli metodi:

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

Il client MCP di Laravel segue questi suggerimenti quando abiliti la cache con withCache(). Le risposte con ttlMs mancante o pari a zero non vengono messe in cache. Le chiamate agli strumenti non sono cacheable. (#301, #326)

Server stateless

Con il nuovo protocollo, il server elabora ogni richiesta in modo indipendente. Ogni richiesta HTTP e ogni messaggio su standard input/output (stdio) include la versione del protocollo e le funzionalità supportate dal client in params._meta.

L'header MCP-Session-Id, Request::sessionId(), Request::setSessionId() e l'evento SessionInitialized sono stati rimossi. Per tenere traccia delle chiamate correlate, passa un tuo identificatore negli argomenti della richiesta o in _meta. (#285)

OAuth

L'autorizzazione OAuth ora richiede il supporto a PKCE. OAuthClient::redirect() lancia una OAuthException se il server di autorizzazione omette code_challenge_methods_supported dai suoi metadata. In precedenza, rifiutava solo i server che includevano il campo senza il supporto a S256.

C'è anche il supporto ai Client ID Metadata Documents. Con questo metodo, il tuo client_id è un URL HTTPS di un documento JSON che descrive il tuo client, e Mcp::oAuthRoutesFor() serve quel documento su GET /mcp/oauth/{client}/client-metadata.json. Se non hai fornito un client ID, Laravel usa il documento quando il server di autorizzazione lo supporta, e in caso contrario ricade sulla Dynamic Client Registration, che MCP 2026-07-28 depreca.

Quando viene usato un documento di metadata, $token->clientSecret è null, quindi qualsiasi colonna del database che lo memorizza deve accettare null. Questo risolve anche un bug che registrava un nuovo client sul server di autorizzazione ogni volta che veniva eseguito redirect(). (#323, #342)

Note di aggiornamento

Se stai aggiornando dalla 0.9, controlla come i tuoi client si connettono e inviano le richieste. Il nuovo middleware ValidateMcpHeaders viene eseguito su ogni route registrata tramite Mcp::web().

Le richieste POST che usano il nuovo protocollo richiedono gli header MCP-Protocol-Version e Mcp-Method corrispondenti al body. Anche le chiamate a tools/call, prompts/get e resources/read richiedono Mcp-Name. Questo header deve corrispondere al nome dello strumento o del prompt, oppure all'URI della risorsa.

Anche i test che inviano queste richieste con postJson() necessitano degli header e dei campi params._meta. Un header non corrispondente restituisce HTTP 400 con codice di errore JSON-RPC -32020. I client più vecchi che usano initialize e non inviano metadata di protocollo in _meta sono esenti dalla validazione degli header.

L'elenco completo, incluse le modifiche ai codici di errore, la costante Server::CAPABILITY_UI rimossa e il contratto di trasporto personalizzato, è nella guida all'aggiornamento alla 1.0.

Riferimenti

• Note di rilascio della v1.0.0
• Changelog completo
• Guida all'aggiornamento