*/
public function icons(): array
{
return [
Icon::from('mcp/tool.png', mimeType: 'image/png'),
];
}
}
```
Іконки, визначені через атрибут і через метод `icons`, об'єднуються автоматично. Шляхи до іконок резолвляться так:
- Шляхи зі схемою URI, як-от `https:` чи `data:`, використовуються як є.
- Відносні шляхи перетворюються на URL за допомогою хелпера `asset` з Laravel.
## Автентифікація
Так само як і маршрути, ви можете автентифікувати вебсервери MCP за допомогою `middleware`. Додавання автентифікації до вашого MCP-сервера вимагатиме від користувача автентифікуватися, перш ніж користуватися будь-якою можливістю сервера.
Є два способи автентифікувати доступ до вашого MCP-сервера: проста автентифікація на основі токенів через [Laravel Sanctum](/docs/{{version}}/sanctum) чи будь-який токен, що передається в HTTP-заголовку `Authorization`. Або ж ви можете автентифікувати через OAuth за допомогою [Laravel Passport](/docs/{{version}}/passport).
### OAuth 2.1
Найнадійніший спосіб захистити ваші вебсервери MCP - OAuth за допомогою [Laravel Passport](/docs/{{version}}/passport).
Автентифікуючи свій MCP-сервер через OAuth, викличте метод `Mcp::oauthRoutes` у файлі `routes/ai.php`, щоб зареєструвати потрібні маршрути виявлення OAuth2 і реєстрації клієнтів. Далі застосуйте `middleware` `auth:api` з Passport до свого маршруту `Mcp::web` у файлі `routes/ai.php`:
```php
use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;
Mcp::oauthRoutes();
Mcp::web('/mcp/weather', WeatherExample::class)
->middleware('auth:api');
```
#### Нове встановлення Passport
Якщо ваш застосунок ще не використовує Laravel Passport, дотримуйтеся [посібника зі встановлення й розгортання](/docs/{{version}}/passport#installation) Passport, щоб додати його до свого застосунку. Перш ніж рухатися далі, у вас має бути модель `OAuthenticatable`, новий гард автентифікації й ключі passport.
Далі вам слід опублікувати надане Laravel MCP представлення авторизації Passport:
```shell
php artisan vendor:publish --tag=mcp-views
```
Потім вкажіть Passport використовувати це представлення методом `Passport::authorizationView`. Зазвичай цей метод слід викликати в методі `boot` `AppServiceProvider` вашого застосунку:
```php
use Laravel\Passport\Passport;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Passport::authorizationView(function ($parameters) {
return view('mcp.authorize', $parameters);
});
}
```
Це представлення буде показано кінцевому користувачеві під час автентифікації, щоб відхилити чи схвалити спробу автентифікації AI-агента.
> [!NOTE]
> У цьому сценарії ми просто використовуємо OAuth як шар перетворення до моделі автентифікації, що лежить в основі. Ми ігноруємо багато аспектів OAuth, як-от скопи.
#### Використання наявного встановлення Passport
Якщо ваш застосунок уже використовує Laravel Passport, Laravel MCP має безшовно працювати у вашому наявному встановленні Passport, але власні скопи наразі не підтримуються, оскільки OAuth використовується переважно як шар перетворення до моделі автентифікації, що лежить в основі.
Laravel MCP через метод `Mcp::oauthRoutes`, згаданий вище, додає, оголошує й використовує єдиний скоп `mcp:use`.
#### Passport чи Sanctum?
OAuth2.1 - це задокументований механізм автентифікації у специфікації Model Context Protocol, і він найширше підтримується серед MCP-клієнтів. З цієї причини ми рекомендуємо використовувати Passport, коли це можливо.
Якщо ваш застосунок уже використовує [Sanctum](/docs/{{version}}/sanctum), додавання Passport може виявитися обтяжливим. У такому разі ми рекомендуємо використовувати Sanctum без Passport, доки у вас не з'явиться чітка, необхідна вимога працювати з MCP-клієнтом, який підтримує лише OAuth.
### Sanctum
Якщо ви хочете захистити свій MCP-сервер за допомогою [Sanctum](/docs/{{version}}/sanctum), просто додайте `middleware` автентифікації Sanctum до свого сервера у файлі `routes/ai.php`. Далі переконайтеся, що ваші MCP-клієнти надсилають заголовок `Authorization: Bearer `, щоб автентифікація була успішною:
```php
use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;
Mcp::web('/mcp/demo', WeatherExample::class)
->middleware('auth:sanctum');
```
#### Власна автентифікація MCP
Якщо ваш застосунок видає власні API-токени, ви можете автентифікувати свій MCP-сервер, призначивши маршрутам `Mcp::web` будь-який `middleware` на свій розсуд. Ваш власний `middleware` може вручну перевіряти заголовок `Authorization`, щоб автентифікувати вхідний MCP-запит.
## Авторизація
Ви можете звернутися до поточного автентифікованого користувача методом `$request->user()`, що дозволяє виконувати [перевірки авторизації](/docs/{{version}}/authorization) у ваших MCP-інструментах і ресурсах:
```php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
/**
* Handle the tool request.
*/
public function handle(Request $request): Response
{
if (! $request->user()->can('read-weather')) {
return Response::error('Permission denied.');
}
// ...
}
```
## MCP-клієнт
Окрім створення серверів, Laravel MCP містить клієнт для підключення до інших MCP-серверів - як власних, так і сторонніх. Клієнт дозволяє вашому застосунку виявляти й викликати інструменти, які надає MCP-сервер, що особливо корисно, щоб дати вашим [AI-агентам](/docs/{{version}}/ai-sdk#mcp-tools) доступ до можливостей зовнішніх MCP-серверів.
### Підключення до серверів
Підключитися до MCP-сервера, доступного через HTTP, можна методом `Client::web`, передавши URL сервера:
```php
use Laravel\Mcp\Client;
$client = Client::web('https://mcp.example.com');
```
Щоб підключитися до локального MCP-сервера, який працює як команда, скористайтеся методом `Client::local`, указавши команду й будь-які аргументи, потрібні для запуску сервера:
```php
use Laravel\Mcp\Client;
$client = Client::local('php', ['artisan', 'mcp:start']);
```
Клієнт підключається ліниво, автоматично встановлюючи з'єднання під час першого переліку чи виклику інструментів. Якщо вам потрібно керувати з'єднанням вручну, скористайтеся методами `connect`, `connected` і `disconnect`:
```php
$client->connect();
if ($client->connected()) {
$capabilities = $client->capabilities();
$server = $client->serverInfo();
}
$client->disconnect();
```
Ви можете змінити тайм-аут запиту методом `withTimeout`:
```php
$client = Client::web('https://mcp.example.com')->withTimeout(30);
```
### Іменовані клієнти
Замість створювати клієнта щоразу, коли він вам потрібен, ви можете зареєструвати багаторазові іменовані клієнти. Зазвичай це роблять у методі `boot` сервіс-провайдера за допомогою фасада `Mcp`:
```php
use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;
Mcp::registerClient('github', fn () => Client::web('https://mcp.example.com'));
```
Щойно клієнта зареєстровано, ви можете отримати його будь-де у своєму застосунку за іменем:
```php
use Laravel\Mcp\Facades\Mcp;
$client = Mcp::client('github');
```
Іменовані клієнти створюються один раз на запит і автоматично від'єднуються наприкінці життєвого циклу запиту.
### Автентифікація клієнта
Щоб підключитися до вебсервера MCP, захищеного bearer-токеном, скористайтеся методом `withToken`. Ви можете передати рядок токена або замикання, яке ліниво його поверне:
```php
use Illuminate\Support\Facades\Auth;
use Laravel\Mcp\Client;
$client = Client::web('https://mcp.example.com')->withToken($token);
$client = Client::web('https://mcp.example.com')->withToken(
fn () => Auth::user()->mcpToken(),
);
```
Для серверів, захищених [OAuth 2.1](#oauth), налаштуйте клієнта методом `withOAuth`. Це клієнтський відповідник захисту ваших власних серверів через OAuth:
```php
use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;
Mcp::registerClient('github', fn () => Client::web('https://mcp.example.com')->withOAuth(
clientId: config('services.github_mcp.client_id'),
clientSecret: config('services.github_mcp.client_secret'),
));
```
> [!NOTE]
> Аргументи `clientId` і `clientSecret` можна опустити. Laravel використає [Client ID Metadata Document](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents), коли сервер авторизації їх підтримує, і повертається до [динамічної реєстрації клієнтів](https://datatracker.ietf.org/doc/html/rfc7591) для застарілих серверів.
Сервер авторизації має оголосити підтримку методу виклику коду PKCE `S256` у своїх метаданих. Laravel відхилить спробу авторизації, якщо підтримка PKCE не оголошена.
Далі зареєструйте OAuth-маршрути для іменованого клієнта у файлі `routes/ai.php` методом `oAuthRoutesFor`. Замикання, яке ви надаєте, отримує ім'я клієнта й отриманий `TokenSet` після обміну коду авторизації на токен доступу:
```php
use Illuminate\Support\Facades\Auth;
use Laravel\Mcp\Client\OAuth\TokenSet;
use Laravel\Mcp\Facades\Mcp;
Mcp::oAuthRoutesFor('github', function (string $client, TokenSet $token) {
Auth::user()->update([
'github_mcp_token' => $token->accessToken,
]);
return redirect('/dashboard');
});
```
Це реєструє три іменовані маршрути: маршрут підключення (`mcp.oauth.{client}.connect`), який перенаправляє користувача на сервер авторизації, маршрут зворотного виклику (`mcp.oauth.{client}.callback`), який обмінює код авторизації й викликає ваш обробник, і публічний маршрут Client ID Metadata Document (`mcp.oauth.{client}.client-metadata`). Маршрути підключення й зворотного виклику за замовчуванням використовують групу `middleware` `web`, яку ви можете перевизначити аргументом `middleware`. Маршрут метаданих цей `middleware` не використовує, бо сервер авторизації має мати змогу його отримати.
Документ метаданих описує ваш застосунок як публічного OAuth-клієнта й використовує `APP_URL` вашого застосунку для генерації ідентифікатора клієнта та URL зворотного виклику. Тому переконайтеся, що змінна оточення `APP_URL` правильно встановлена у продакшені. Ви можете налаштувати маршрут метаданих і надати додаткові метадані за допомогою аргументів `clientMetadataUri` і `clientMetadata`:
```php
use Laravel\Mcp\Client\OAuth\TokenSet;
use Laravel\Mcp\Facades\Mcp;
Mcp::oAuthRoutesFor(
'github',
function (string $client, TokenSet $token) {
// Store the token...
return redirect('/dashboard');
},
clientMetadataUri: 'oauth/github/client.json',
clientMetadata: [
'client_name' => 'Acme Weather Dashboard',
'logo_uri' => 'https://acme.com/logo.png',
],
);
```
Щоб розпочати потік авторизації, перенаправте користувача на маршрут підключення:
```php
return redirect()->route('mcp.oauth.github.connect');
```
### Інструменти
Отримати інструменти, які надає MCP-сервер, можна методом `tools`, що повертає колекцію інструментів з ключами за іменами:
```php
use Laravel\Mcp\Facades\Mcp;
$tools = Mcp::client('github')->tools();
foreach ($tools as $tool) {
$tool->name;
$tool->title;
$tool->description;
$tool->inputSchema;
}
```
Клієнт автоматично проходить сторінками всіх доступних інструментів. Ви можете обмежити кількість повернутих інструментів аргументом `limit`:
```php
$tools = Mcp::client('github')->tools(limit: 10);
```
Щоб викликати інструмент, скористайтеся методом `callTool`, передавши ім'я інструмента й масив аргументів. Повернутий екземпляр `ToolResult` надає відповідь інструмента:
```php
use Laravel\Mcp\Facades\Mcp;
$result = Mcp::client('github')->callTool('current-weather', [
'location' => 'New York',
]);
$result->text(); // The text content of the response...
(string) $result; // Equivalent to calling text()...
$result->isError; // Whether the tool reported an error...
$result->structuredContent; // Structured content, if any...
```
Як альтернативу ви можете викликати інструмент безпосередньо з екземпляра переліченого інструмента:
```php
$tools = Mcp::client('github')->tools();
$result = $tools['current-weather']->call([
'location' => 'New York',
]);
```
Якщо ви створюєте агентів за допомогою [Laravel AI SDK](/docs/{{version}}/ai-sdk), ви також можете передати інструменти з MCP-клієнта безпосередньо агенту, дозволивши моделі викликати їх під час відповіді на промпт. Докладніше дивіться в розділі [MCP Tools](/docs/{{version}}/ai-sdk#mcp-tools) документації AI SDK.
### Промпти
Отримати промпти, які надає MCP-сервер, можна методом `prompts`, що повертає колекцію промптів з ключами за іменами:
```php
use Laravel\Mcp\Facades\Mcp;
$prompts = Mcp::client('github')->prompts();
foreach ($prompts as $prompt) {
$prompt->name;
$prompt->title;
$prompt->description;
$prompt->arguments;
}
```
Клієнт автоматично проходить сторінками всіх доступних промптів. Ви можете обмежити кількість повернутих промптів аргументом `limit`:
```php
$prompts = Mcp::client('github')->prompts(limit: 10);
```
Щоб отримати промпт, скористайтеся методом `getPrompt`, передавши ім'я промпта й масив аргументів. Повернутий екземпляр `PromptResult` надає згенеровані повідомлення:
```php
use Laravel\Mcp\Facades\Mcp;
$result = Mcp::client('github')->getPrompt('describe-weather', [
'location' => 'New York',
]);
$result->text(); // The text content of the messages...
(string) $result; // Equivalent to calling text()...
$result->messages; // The raw messages returned by the prompt...
$result->description; // The prompt description, if any...
```
### Ресурси
Отримати ресурси, які надає MCP-сервер, можна методом `resources`, що повертає колекцію ресурсів з ключами за URI:
```php
use Laravel\Mcp\Facades\Mcp;
$resources = Mcp::client('github')->resources();
foreach ($resources as $resource) {
$resource->uri;
$resource->name;
$resource->title;
$resource->description;
$resource->mimeType;
$resource->size;
}
```
Клієнт автоматично проходить сторінками всіх доступних ресурсів. Ви можете обмежити кількість повернутих ресурсів аргументом `limit`:
```php
$resources = Mcp::client('github')->resources(limit: 10);
```
Щоб прочитати ресурс, скористайтеся методом `readResource`, передавши URI ресурсу. Повернутий екземпляр `ResourceReadResult` надає вміст ресурсу:
```php
use Laravel\Mcp\Facades\Mcp;
$result = Mcp::client('github')->readResource('weather://guidelines');
$result->content(); // The content of the resource, decoding base64 blobs as needed...
(string) $result; // Equivalent to calling content()...
$result->mimeType(); // The MIME type of the resource, if any...
$result->contents; // The raw contents returned by the resource...
```
## Тестування серверів
Ви можете тестувати свої MCP-сервери за допомогою вбудованого MCP Inspector або пишучи юніт-тести.
### MCP Inspector
[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) - це інтерактивний інструмент для тестування й налагодження ваших MCP-серверів. Використовуйте його, щоб підключитися до сервера, перевірити автентифікацію й випробувати інструменти, ресурси та промпти.
Ви можете запустити інспектор для будь-якого зареєстрованого сервера:
```shell
# Web server...
php artisan mcp:inspector mcp/weather
# Local server named "weather"...
php artisan mcp:inspector weather
```
Ця команда запускає MCP Inspector і надає налаштування клієнта, які ви можете скопіювати до свого MCP-клієнта, щоб переконатися, що все налаштовано правильно. Якщо ваш вебсервер захищено `middleware` автентифікації, обов'язково додайте потрібні заголовки, як-от bearer-токен `Authorization`, під час підключення.
### Юніт-тести
Ви можете писати юніт-тести для своїх MCP-серверів, інструментів, ресурсів і промптів.
Для початку створіть новий тест-кейс і викличте потрібний примітив на сервері, який його реєструє. Наприклад, щоб протестувати інструмент на `WeatherServer`:
```php tab=Pest
test('tool', function () {
$response = WeatherServer::tool(CurrentWeatherTool::class, [
'location' => 'New York City',
'units' => 'fahrenheit',
]);
$response
->assertOk()
->assertSee('The current weather in New York City is 72°F and sunny.');
});
```
```php tab=PHPUnit
/**
* Test a tool.
*/
public function test_tool(): void
{
$response = WeatherServer::tool(CurrentWeatherTool::class, [
'location' => 'New York City',
'units' => 'fahrenheit',
]);
$response
->assertOk()
->assertSee('The current weather in New York City is 72°F and sunny.');
}
```
Так само ви можете тестувати промпти й ресурси:
```php
$response = WeatherServer::prompt(...);
$response = WeatherServer::resource(...);
```
Ви також можете діяти від імені автентифікованого користувача, додавши метод `actingAs` ланцюжком перед викликом примітива:
```php
$response = WeatherServer::actingAs($user)->tool(...);
```
Отримавши відповідь, ви можете скористатися різними методами тверджень, щоб перевірити її вміст і статус.
Ви можете стверджувати, що відповідь успішна, методом `assertOk`. Він перевіряє, що відповідь не містить помилок:
```php
$response->assertOk();
```
Ви можете стверджувати, що відповідь містить певний текст, методом `assertSee`:
```php
$response->assertSee('The current weather in New York City is 72°F and sunny.');
```
Ви можете стверджувати, що відповідь містить помилку, методом `assertHasErrors`:
```php
$response->assertHasErrors();
$response->assertHasErrors([
'Something went wrong.',
]);
```
Ви можете стверджувати, що відповідь не містить помилки, методом `assertHasNoErrors`:
```php
$response->assertHasNoErrors();
```
Ви можете стверджувати, що відповідь містить певні метадані, методами `assertName()`, `assertTitle()` та `assertDescription()`:
```php
$response->assertName('current-weather');
$response->assertTitle('Current Weather Tool');
$response->assertDescription('Fetches the current weather forecast for a specified location.');
```
Ви можете стверджувати, що сповіщення були надіслані, методами `assertSentNotification` і `assertNotificationCount`:
```php
$response->assertSentNotification('processing/progress', [
'step' => 1,
'total' => 5,
]);
$response->assertSentNotification('processing/progress', [
'step' => 2,
'total' => 5,
]);
$response->assertNotificationCount(5);
```
Насамкінець, якщо ви хочете оглянути сирий вміст відповіді, скористайтеся методами `dd` чи `dump`, щоб вивести відповідь для налагодження:
```php
$response->dd();
$response->dump();
```