Розміщення MCP-сервера всередині додатка Laravel
ШІ-агентам потрібно більше, ніж просто зібраний (scraped) інтерфейс користувача. Їм потрібен спосіб викликати конкретні інструменти з відповідними дозволами. Саме це забезпечує Model Context Protocol (MCP).
Нещодавно я інтегрував MCP-сервер безпосередньо в додаток Laravel. Я хочу поділитися архітектурними рішеннями для його безпечної побудови.
Метафора рецепціоніста
Уявіть свій додаток як офісну будівлю.
- Веб-інтерфейс — це вестибюль для людей.
- REST API — це службовий вхід для систем.
- MCP-сервер — це стійка реєстрації для ШІ-агентів.
Агент показує ID і запитує виконання конкретного завдання. Рецепціоніст не віддає йому ключі від будівлі. Він перевіряє дозволи, виконує одне завдання і повертає структуровану відповідь.
Основні архітектурні рішення
1. Використовуйте єдину кінцеву точку
Не створюйте багато маршрутів для різних інструментів. Використовуйте одну /mcp кінцеву точку. Протокол автоматично обробляє виявлення інструментів. Одну точку доступу легше захистити та задокументувати.
2. Підтримка подвійної автентифікації
Різним викликаючим сторонам потрібні різні методи безпеки:
- Внутрішні клієнти (наприклад, CLI-інструменти) використовують персональні токени доступу Sanctum.
- Сторонні агенти (що діють від імені користувачів) використовують OAuth 2.1.
Використовуйте резолвер у стилі драйвера для обробки обох варіантів. Код інструмента має дбати лише про автентифікованого користувача, а не про те, як саме він увійшов у систему.
3. Дотримуйтесь існуючого RBAC
Автентифікація лише підтверджує, ким є викликаюча сторона. Ви все одно повинні перевіряти, що вона може робити. Кожен інструмент має відповідати існуючій можливості (ability). Якщо користувач не може переглядати учасників у веб-інтерфейсі, він не повинен мати змоги зробити це через MCP.
4. Обмежуйте вивід даних
Ніколи не повертайте повну модель бази даних. Ставтеся до виводу MCP як до публічного API. Повертайте лише ті конкретні поля, які потрібні агенту. Це запобігає випадковим витокам даних.
Тестування безпеки
Ваші тести мають доводити, що система коректно обробляє помилки. Перевірте, що:
- Неавторизований користувач отримує помилку
403 Forbidden. - Авторизований користувач отримує лише дозволені поля.
Хороший набір тестів — це ваш найкращий захист від витоку даних при використанні автономних агентів.
Підсумок
Щоб побудувати відповідальний MCP-сервер, дотримуйтесь цих трьох правил:
- Автентифікуйте кожного викликаючого користувача за допомогою відповідної схеми.
- Авторизуйте кожен інструмент, використовуючи вашу існуючу модель дозволів.
- Ставтеся до кожного результату роботи інструмента як до обмеженого публічного ресурсу.