Команда Laravel випустила Laravel MCP 1.0 - першу стабільну версію пакета для побудови серверів Model Context Protocol (MCP) у Laravel-застосунках. Ці сервери дозволяють AI-застосункам використовувати інструменти та дані вашого додатка. Цей реліз приносить підтримку ревізії MCP 2026-07-28.
Ключові зміни релізу
Протокол 2026-07-28 використовує server/discover замість початкового обміну через initialize. Пошукові каталоги інструментів дозволяють агенту знаходити потрібні інструменти за запитом. Кеш-підказки повідомляють клієнта, які відповіді можна повторно використовувати і як довго. Stateless сервери обробляють кожен запит незалежно за новим протоколом. Зміни OAuth вимагають підтримки PKCE та додають новий спосіб ідентифікації клієнтів. Підтримка MCP Apps тепер перелічена у можливості extensions.
Клієнти, які все ще підключаються через initialize, продовжують працювати. Сервер відповідає версією протоколу 2025-11-25 або 2025-06-18, залежно від того, яку запитує клієнт.
Пошукові каталоги інструментів
Кожне визначення інструмента, яке ви надсилаєте моделі, займає місце у її контекстному вікні - обсязі інформації, з якою вона може працювати одночасно. ToolSearch дозволяє зберігати загальні інструменти в основному списку, а решту розміщувати за пошуком:
use App\Mcp\Tools\CurrentWeatherTool;
use App\Mcp\Tools\HistoricalWeatherTool;
use App\Mcp\Tools\WeatherAlertsTool;
use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Tools\ToolSearch;
class WeatherServer extends Server
{
protected array $tools = [
// Завжди доступні для агента...
CurrentWeatherTool::class,
// Шукаються лише за потреби...
ToolSearch::class => [
HistoricalWeatherTool::class,
WeatherAlertsTool::class,
],
];
}
Пакет реєструє два інструменти для обробки цього. search_tools приймає запит та ліміт результатів, потім повертає відповідні інструменти з їхніми назвами, описами та очікуваними вхідними даними. execute_tools виконує один або кілька інструментів за назвою. Агент може знайти та використати інструмент без завантаження всього каталогу.
Кеш-підказки
Сервер тепер може повідомляти клієнтам, які відповіді вони можуть кешувати, як довго їх зберігати і чи можна ними ділитися між користувачами. Встановіть значення за замовчуванням атрибутом Cacheable, а потім використовуйте cacheHints() для перевизначення окремих методів:
use Laravel\Mcp\Enums\CacheScope;
use Laravel\Mcp\Server\Attributes\Cacheable;
#[Cacheable(ttlMs: 60_000, scope: CacheScope::Public)]
class WeatherServer extends Server
{
protected function cacheHints(): array
{
return [
'tools/list' => new Cacheable(ttlMs: 30_000),
];
}
}
MCP-клієнт Laravel дотримується цих підказок, коли ви вмикаєте кешування через withCache(). Відповіді з відсутнім або нульовим ttlMs не кешуються. Виклики інструментів не підлягають кешуванню.
Stateless сервери
З новим протоколом сервер обробляє кожен запит незалежно. Кожен HTTP-запит та повідомлення стандартного вводу/виводу (stdio) включає версію протоколу та функції, які підтримує клієнт, у params._meta.
Заголовок MCP-Session-Id, методи Request::sessionId(), Request::setSessionId() та подію SessionInitialized видалено. Щоб відстежувати пов'язані виклики, передавайте власний ідентифікатор в аргументах запиту або _meta.
OAuth
Авторизація OAuth тепер вимагає підтримки PKCE. OAuthClient::redirect() викидає OAuthException, якщо сервер авторизації не включає code_challenge_methods_supported у свої метадані. Раніше він відхиляв лише сервери, які включали це поле без підтримки S256.
Також додано підтримку Client ID Metadata Documents. За цього методу ваш client_id є HTTPS URL для JSON-документа, який описує вашого клієнта, а Mcp::oAuthRoutesFor() віддає цей документ за адресою GET /mcp/oauth/{client}/client-metadata.json. Якщо ви не надали client ID, Laravel використовує документ, коли сервер авторизації це підтримує, і повертається до Dynamic Client Registration, яку MCP 2026-07-28 визнає застарілою.
Коли використовується документ метаданих, $token->clientSecret дорівнює null, тому будь-який стовпець бази даних, який його зберігає, повинен приймати null. Це також виправляє помилку, через яку новий клієнт реєструвався на сервері авторизації кожного разу при запуску redirect().
Примітки щодо оновлення
Якщо ви оновлюєтесь з версії 0.9, перевірте, як ваші клієнти підключаються та надсилають запити. Новий middleware ValidateMcpHeaders виконується на кожному маршруті, зареєстрованому через Mcp::web().
POST-запити з новим протоколом потребують заголовків MCP-Protocol-Version та Mcp-Method, які відповідають тілу запиту. Виклики tools/call, prompts/get та resources/read також потребують Mcp-Name. Цей заголовок повинен відповідати назві інструмента чи підказки або URI ресурсу.
Тести, які надсилають ці запити через postJson(), також потребують заголовків та полів params._meta. Невідповідність заголовка повертає HTTP 400 з кодом помилки JSON-RPC -32020. Старіші клієнти, які використовують initialize і не надсилають метадані протоколу в _meta, звільнені від валідації заголовків.
Повний список змін, включаючи зміни кодів помилок, видалену константу Server::CAPABILITY_UI та контракт кастомного транспорту, доступний у керівництві з оновлення до версії 1.0.
Посилання
