MCP-шлюз для ИИ-агентов: токены, маскирование, аудит, kill-switch
Мы поставили один шлюз между агентами для написания кода и внутренними системами. У каждого агента свой токен и список разрешений, каждый результат маскируется до выхода наружу, каждый вызов попадает в аудит, а одна кнопка останавливает всё.
· 5 мин чтения
Агенты для написания кода становятся намного полезнее, когда могут читать системы, в которых команда действительно работает: трекер задач, git-сервер, базу данных SQL. Обычный путь туда — вписать учётные данные в конфигурацию каждого агента. Это работает, пока не появятся четыре вопроса. Какой агент что прочитал? Не попал ли номер телефона или персональный идентификационный номер в контекст модели? Можно ли остановить одного агента, не останавливая остальных? Где лежат пароли от баз данных?
Чтобы ответить на эти вопросы в одном месте, мы написали небольшой шлюз. С одной стороны он говорит с агентами, с другой — с «коннекторами», и в обе стороны по Model Context Protocol. В этой статье описан его дизайн в версии 0.2.0, выпущенной 2 ноября 2026 года, и то, чему мы научились по ходу работы.
Устройство системы
Частей три:
- Шлюз: один процесс Node.js, около 950 строк, без зависимостей из npm (только
node:http,node:fsиnode:crypto). Он открывает один MCP-эндпоинт, хранит реестр агентов, применяет политику и маскирование и пишет журнал аудита. - Коннекторы: небольшие MCP-серверы рядом с системами, к которым они подключаются. Коннектор хранит учётные данные своей системы, слушает только localhost и публикуется для шлюза через обратный туннель. Запрос он принимает, только если совпадает bearer-секрет, причём сравнение выполняется за постоянное время.
- Админ-панель: веб-страница на server-sent events. На ней видны вызовы в реальном времени, список агентов, состояние коннекторов и kill-switch.
Ключевое свойство: шлюз не хранит ни одного секрета подключённых систем. Даже если хост шлюза будет скомпрометирован, атакующий получит хеши токенов агентов и журнал аудита, а не пароли от баз. Коннекторы отдают инструменты под префиксом, поэтому агент видит не сырую базу, а инструмент <connector>-sql_query.
- 1ЗапросАгент вызывает инструмент на шлюзе со своим личным токеном.
- 2ПолитикаШлюз по порядку проверяет kill-switch, паузу, список разрешений, правила аргументов и лимит.
- 3КоннекторВызов идёт через туннель к коннектору, у которого хранятся настоящие учётные данные.
- 4МаскаПерсональные данные в результате маскируются до того, как покинут шлюз.
- 5АудитЗамаскированные запрос и ответ пишутся в журнал и отправляются на живую панель.
Идентичность и политика для каждого агента
Каждый агент получает личный токен вида ag_<имя>_<32 случайных символа>. Он показывается один раз, а сервер хранит только его хеш SHA-256. После двадцати неудачных попыток с одного адреса этот адрес блокируется на десять минут — и для агентов, и для входа в админку.
Политика привязана к агенту, а не к коннектору:
- Список разрешённых инструментов с подстановками (
*,<connector>-*или один конкретный инструмент). Неразрешённый инструмент удаляется изtools/list, так что модель его просто не видит, а если всё же вызовет — получит отказ. - Лимит вызовов в минуту (по умолчанию 30, настраивается от 1 до 600).
- Срок действия и необязательный список разрешённых IP.
- Список разрешённых аргументов. Например, аргумент базы данных можно ограничить одной конкретной базой. Шлюз заодно сужает JSON-схему инструмента в
tools/listдо этого enum, и модель не тратит вызовы на угадывание. - Пауза для одного агента, отключение одного коннектора и глобальный kill-switch.
Порядок проверок важен, потому что каждый отказ записывается с кодом статуса (killed, paused, unknown, denied, arg, rate, expired, ip). Упрощённый поток из callTool выглядит так:
if (state.killed) return deny("kill-switch", "killed");
if (agent.paused) return deny("agent paused", "paused");
const hit = catalog().find((t) => t.full === name);
if (!hit) return deny("unknown tool", "unknown");
if (!toolAllowed(agent, name)) return deny("not allowed", "denied");
if (argViolation(agent, hit.tool, args)) return deny("argument not allowed", "arg");
if (overRate(agent.name, agent.rpm || 30)) return deny("rate limit", "rate");
const result = scrubResult(await connector.call(hit.tool.name, args));
Каждый инструмент, который шлюз отдаёт агентам, помечен readOnlyHint: true. В MCP эта пометка лишь рекомендательная, поэтому её подкрепляют коннекторы. SQL-инструмент принимает только один оператор SELECT или WITH и отклоняет INTO, EXEC, системные процедуры, OPENROWSET, WAITFOR и разделители операторов. Запрос выполняется в транзакции READ UNCOMMITTED с таймаутом блокировок и всегда откатывается. Возвращается не больше 200 строк, таймаут — 30 секунд. Для самых чувствительных сред коннектор вдобавок использует логин, который только читает на уровне самой базы. Фильтра по ключевым словам никогда не бывает достаточно, поэтому транзакция и логин — отдельные слои.
Маскирование: регулярных выражений мало
Результаты маскируются до того, как попадут к агенту: персональные идентификационные номера, номера паспортов, телефоны, email-адреса, номера карт и всё, что похоже на секрет (JWT, распространённые префиксы токенов, пары password=). Правила для секретов идут первыми, чтобы правило для цифр не «съело» токен наполовину. Каждое правило оставляет небольшую полезную часть значения: у карты — последние четыре цифры, у email — первую букву и домен.
Первая версия опиралась только на регулярные выражения, и их предел мы нашли быстро. Телефон, сохранённый как девять цифр подряд, ничем не отличается от девятизначного налогового номера организации. Никакой regex их не различит, а маскировать каждое девятизначное число значит уничтожить полезные данные. Решением стало маскирование по имени столбца. SQL-коннектор возвращает Markdown-таблицы, и шлюз читает строку заголовков. Значение в столбце с именем вроде Phone, MobilePhone, Email, Passport или Password маскируется независимо от формы.
Администраторы могут добавлять свои маски — как regex или как шаблон имени столбца. Понадобились две проверки. Шаблоны с вложенными квантификаторами вроде (a+)+ отклоняются из-за катастрофического бэктрекинга. Шаблоны, совпадающие с пустой строкой, тоже отклоняются: они замаскировали бы всё подряд.
Маскирование можно отключить по категориям, например на время отладки. Пока оно выключено, каждая запись аудита фиксирует, какие категории были отключены в этот момент, и позже по журналу видно, где данные маскировались, а где нет.
Аудит, живой просмотр и оповещения
Версия 0.1.0 записывала, кто что вызвал и сколько это заняло, но не то, что вернулось. Это оказалось неудачным компромиссом: когда результат выглядел странно, проверять было нечего. Версия 0.2.0, вышедшая в тот же день, хранит до 16 КБ аргументов запроса и до 64 КБ ответа ровно в том виде, в каком его увидел агент, то есть уже замаскированным. Журнал ведётся в JSONL, по файлу на день, и хранится 30 дней. Кольцевой буфер в памяти держит последние 5000 записей для панели.
Панель показывает каждый вызов как события «start» и «end», поэтому медленный запрос виден ещё во время выполнения. Действия администратора — пауза агента, смена масок, нажатие kill-switch — тоже пишутся в журнал, с пометкой type: admin. Идентификатор MCP-сессии сохраняется вместе с вызовом, так что один разговор агента можно выделить из загруженного журнала.
Оповещения уходят в чат-канал: включение и выключение kill-switch, отключение масок, падение и восстановление коннектора, неудачные входы, всплески вызовов и необычно большие выборки. Полезными их делают две детали. Коннектор считается упавшим только после двух неудачных проверок подряд, так что разовый сбой сети не поднимает тревогу. А каждый ключ оповещения отправляется не чаще раза в 10 минут.
Чему мы научились
- Держите политику там, где идентичность. Привязка правил к агентам, а не к системам, превратила «этот агент читает трекер, но не базу» в одну настройку.
- Прячьте то, что запрещено. Удаление запрещённых инструментов из
tools/listи сужение enum-аргументов сократило лишние вызовы сильнее, чем сообщения об ошибках. Модель не может злоупотребить инструментом, которого никогда не видела. - Пишите в журнал то, что увидел агент, а не то, что вернула система. Хранение замаскированного ответа не даёт журналу аудита стать второй копией персональных данных.
- Кнопка остановки должна быть скучной. Kill-switch — одно булево значение, которое проверяется раньше всего остального. Он опустошает
tools/listи отклоняет вызовы с понятной причиной, поэтому агенты останавливаются спокойно, а не повторяют попытки.
Ограничения
- Маскирование основано на шаблонах. Имена и фамилии не распознаются, и README прямо об этом говорит. Свободные текстовые поля могут содержать персональные данные в форме, которую не предусмотрело ни одно правило.
- Единственный режим — только чтение. Пути для записи нет, и для его добавления понадобится другая модель подтверждений.
- Коннектор на рабочей станции доступен, только пока эта машина включена.
- Лимиты и счётчики ошибок живут в памяти и сбрасываются при перезапуске процесса. Для одного экземпляра это приемлемо, для кластера — нет.
- Мы не измеряли точность и полноту маскирования на размеченном наборе данных, поэтому не можем назвать цифру точности.
Повторите сами
Репозиторий шлюза закрыт; эти открытые инструменты позволяют проверить любой MCP-сервер, в том числе стоящий за вашим собственным шлюзом.
$ npx @modelcontextprotocol/inspector
$ claude mcp add --transport http my-gateway https://example.com/mcp --header "Authorization: Bearer <agent-token>" - Репозиторий
- Репозиторий закрыт; команды используют только публичные инструменты.
- Материалы
- wonmortech/research
Источники
- dtwinuz/gateway: README, gateway/server.mjs, connector/connector.mjs (private repository)
- dtwinuz/gateway git history: v0.1.0 to v0.2.0 and alerts, 2026-11-02 to 2026-11-03
- modelcontextprotocol.io/specification
Похожие материалы
Смотреть ещё- Агенты и MCP Мультиагентная оркестрация на практике Один оркестратор, три узкие роли и изолированные worktree. Что сработало, когда восемь агентов строили восемь модулей в одной ветке, и с какими сбоями мы столкнулись по пути.
- Агенты и MCP Управление Claude Code из Telegram Небольшой бот на Python превращает чат в телефоне в пульт для Claude Code на настольном компьютере: один headless-процесс на сообщение, хуки для уведомлений и подтверждений, параллельные слоты. Что мы построили за день и что узнали о запросах размером с экран телефона.