Размещение MCP-сервера внутри приложения Laravel
ИИ-агентам нужно нечто большее, чем просто спарсенный UI. Им нужен способ вызова конкретных инструментов с соответствующими правами доступа. Именно это и делает Model Context Protocol (MCP).
Недавно я интегрировал MCP-сервер напрямую в приложение Laravel. Я хочу поделиться архитектурными решениями для его безопасной реализации.
Метафора с администратором
Представьте ваше приложение как офисное здание.
- Веб-интерфейс — это вестибюль для людей.
- REST API — это служебный вход для систем.
- MCP-сервер — это стойка регистрации для ИИ-агентов.
Агент предъявляет удостоверение личности и запрашивает выполнение конкретной задачи. Администратор не выдает ему ключи от всего здания. Он проверяет права доступа, выполняет одну задачу и возвращает структурированный ответ.
Ключевые архитектурные решения
1. Используйте единую конечную точку
Не создавайте множество маршрутов для разных инструментов. Используйте один эндпоинт /mcp. Протокол автоматически обрабатывает обнаружение инструментов. Единую точку входа проще защитить и документировать.
2. Поддерживайте двойную аутентификацию
Разным вызывающим сторонам требуются разные методы безопасности:
- Собственные (first-party) клиенты (например, CLI-инструменты) используют персональные токены доступа Sanctum.
- Сторонние (third-party) агенты (действующие от имени пользователей) используют OAuth 2.1.
Используйте резолвер в стиле драйверов для обработки обоих случаев. Код инструмента должен заботиться только об аутентифицированном пользователе, а не о том, как именно он вошел в систему.
3. Соблюдайте существующую модель RBAC
Аутентификация лишь подтверждает, кто вызывает систему. Вы все равно должны проверять, что пользователю разрешено делать. Каждый инструмент должен сопоставляться с существующей возможностью (ability). Если пользователь не может просматривать участников в веб-интерфейсе, он не должен иметь возможности сделать это через MCP.
4. Ограничивайте вывод данных
Никогда не возвращайте полную модель базы данных. Относитесь к выводу MCP как к публичному API. Возвращайте только те конкретные поля, которые необходимы агенту. Это предотвращает случайные утечки данных.
Тестирование безопасности
Ваши тесты должны доказывать, что система корректно обрабатывает ошибки. Проверьте, что:
- Неавторизованный пользователь получает ошибку
403 Forbidden. - Авторизованный пользователь получает только разрешенные поля.
Хороший набор тестов — ваша лучшая защита от утечек данных при использовании автономных агентов.
Итоги
Чтобы создать ответственный MCP-сервер, следуйте этим трем правилам:
- Аутентифицируйте каждого вызывающего участника, используя подходящую схему.
- Авторизуйте каждый инструмент, используя вашу существующую модель разрешений.
- Относитесь к выводу каждого инструмента как к ограниченному публичному ресурсу.