Шлюз MCP (Gateway)

Маршруты

• POST /mcp/search — публичный MCP-сервер потокового HTTP (Streamable HTTP) только для чтения и поиска по каталогу.
• POST /mcp/gateway — аутентифицированный MCP-сервер потокового HTTP. Требует X-API-Key.

Доступные инструменты

Шлюз (Gateway) предоставляет только внутренние инструменты реестра (Registry) для чтения:

• search_skills(query, limit) — поиск навыков;
• get_skill_details(name) — сведения о навыке;
• get_server_health(name) — работоспособность сервера;
• gateway_info() — сведения о шлюзе.

Шлюз не проксирует произвольные удалённые адреса MCP и не принимает от MCP-клиента внешний адрес, заголовок аутентификации или токен.

Политика безопасности

Запись в каталоге, результат проверки работоспособности или активный статус в реестре никогда не дают разрешения на выполнение действий. Будущее подключение стороннего сервера через шлюз требует утверждённого снимка возможностей, списка разрешённых инструментов, профиля клиента, согласия пользователя и классификации риска.

Основа второй версии шлюза

Каждый вызов tools/call требует общий ключ программного интерфейса шлюза и X-Gateway-Client-Key, выданный для серверного профиля клиента. Профиль содержит явный список разрешённых внутренних инструментов только для чтения. Шлюз хранит только HMAC-хеш клиентского ключа, проверяет, что профиль не отозван, и проверяет разрешение на запрошенный инструмент до обработки вызова FastMCP. Отсутствующий, отозванный или неразрешённый клиентский ключ получает 403, а отсутствующий ключ шлюза — 401.

Оператор один раз создаёт профиль через POST /api/v1/admin/gateway-client-profiles. Ответ единственный раз возвращает его клиентский ключ hwg_.... Через тот же административный интерфейс можно просматривать несекретные метаданные профиля и отзывать его. Отзыв действует со следующего вызова инструмента.

Это граница для действующих внутренних инструментов поиска, а не средство общего выполнения действий через сторонние серверы. Шлюз не принимает внешние адреса, произвольные заголовки аутентификации, токены или имена удалённых инструментов. Для добавления внешнего выполнения по-прежнему нужны отдельно утверждённые снимок возможностей, список разрешённых инструментов, запись согласия, классификация риска и проект аудита.

Каждое разрешение имеет явные поля risk_class («класс риска») и consent_required («требуется согласие»). Текущий механизм выдаёт только разрешения read_only («только чтение») без согласия, а шлюз отклоняет любой другой класс риска и любое разрешение, требующее согласия. Это намеренное ограничение: прежде чем включать возможность не только для чтения, запись согласия должна быть спроектирована для аутентифицированного пользователя с узким описанием действия, сроком действия, отзывом и журналом аудита.

Обработчик проверки допускает только HTTPS-адреса на порту 443, разрешает DNS до соединения, отклоняет любые неглобальные адреса, закрепляет соединение за разрешённым адресом с TLS SNI, запрещает перенаправления и ограничивает заголовки, ответы и время ожидания. При ошибке проверки сервер сохраняет немаршрутизируемое состояние pending_verification («ожидает проверки»).

Журналы аудита запросов шлюза содержат только путь, код ответа, задержку и усечённую строку агента пользователя. В них намеренно не попадают ключи программного интерфейса, аргументы JSON-RPC и тела ответов внешних серверов.