ProxyKey MCP: как дать ИИ-агенту доступ к API без выдачи ключа
Современные ИИ-агенты умеют самостоятельно писать код, редактировать конфигурационные файлы, запускать команды и подключать внешние сервисы. Claude Code, Cursor и аналогичные инструменты способны почти полностью настроить приложение, однако у такого подхода есть важная проблема: агенту часто приходится работать с API-ключами.
На практике токен, который хотя бы один раз оказался в контексте модели, следует считать потенциально скомпрометированным. Он может попасть в историю диалога, журналы выполнения, диагностический вывод или сторонний сервис, если агент обрабатывает данные, содержащие промпт-инъекцию. Поэтому распространённая схема "положить ключ в `.env` и дать модели доступ к shell" не обеспечивает достаточной изоляции.
ProxyKey предлагает другой подход: агент получает не сам секрет, а набор MCP-инструментов для управления доступом к API. Значение ключа при этом остаётся за пределами контекста модели.
Почему обычный credential-прокси не бывает полностью zero-knowledge
Credential-прокси выступает посредником между приложением и внешним API. Он принимает виртуальный токен, находит связанный с ним реальный ключ, расшифровывает его в оперативной памяти и добавляет в исходящий запрос.
Это означает, что прокси не может быть "нулезнаниевым" в буквальном смысле: для выполнения запроса ему необходимо получить доступ к секрету хотя бы на короткое время. Однако важен другой принцип - ключ не должен быть доступен агенту, пользователю или вызывающему приложению.
В ProxyKey секрет расшифровывается только внутри прокси и только на время обработки конкретного запроса. После этого он не возвращается клиенту и не используется повторно в открытом виде.
Модель Secret - Pass - Proxy
Архитектура строится вокруг трёх сущностей.
Secret - настоящий ключ провайдера: токен Telegram, ключ облачного API или учётные данные другого сервиса. Пользователь вводит его через веб-панель один раз. Значение хранится в зашифрованном виде с использованием AES-256-GCM и envelope encryption. После создания API не предоставляет операцию, возвращающую этот ключ обратно.
Pass - виртуальный токен формата `vlt_...`, связанный с конкретным секретом. Для него можно отдельно настроить срок действия, ограничения по IP, лимиты запросов и журналирование. Pass не раскрывает исходный ключ и используется только как идентификатор разрешённого доступа.
Proxy - промежуточный слой, который принимает запрос с виртуальным токеном, проверяет его права, временно расшифровывает секрет и подставляет его в запрос к провайдеру.
Для приложения изменения минимальны: достаточно заменить хост и токен, а путь, тело запроса и большинство заголовков остаются прежними. Поддерживаются потоковые ответы через SSE. Для Telegram сохраняется привычная структура URL, например:
```text
/p/telegram-bot/
```
MCP-сервер для управления доступом
Регистрация MCP-доступа выполняется через обычный веб-сценарий: GitHub OAuth или magic link. В результате пользователь получает токен вида `mcp_...`. Он нужен для подключения самого MCP-сервера и не является заменой `pass`, используемого в запросах к провайдерам.
Подключение выполняется по транспорту Streamable HTTP. В конфигурации клиента указывается MCP-сервер и токен авторизации. После этого агент получает инструменты для создания, настройки и контроля виртуальных доступов.
Набор функций разделён на несколько групп.
Каталог и секреты
- `list_providers` - показывает доступных провайдеров и поддерживаемые способы авторизации;
- `list_secrets` - возвращает список секретов только с метаданными;
- `get_manual_secret_setup` - формирует инструкцию или ссылку для ручного ввода ключа человеком.
Управление pass
- `create_pass` - создаёт виртуальный токен для существующего секрета;
- `create_pending_pass` - выпускает токен до появления реального ключа;
- `update_pass` - изменяет лимиты, IP-привязку и срок действия;
- `rotate_pass` - выпускает новый токен с прежними параметрами;
- `revoke_pass` - немедленно отключает доступ;
- `delete_pass` - удаляет ранее отозванный токен;
- `rebind_pass_ip` - сбрасывает текущую привязку к IP и запускает её заново.
Наблюдаемость
- `list_passes` - показывает созданные pass, их состояние и ограничения;
- `get_pass_logs` - предоставляет журнал запросов конкретного токена;
- `get_pass_stats` - отображает статистику использования.
Ключевая особенность заключается в контракте интерфейса: ни один из этих методов не принимает и не возвращает значение реального секрета. Это не рекомендация и не правило, которое агент может случайно нарушить, а техническое ограничение самой спецификации.
По аналогичному принципу через MCP нельзя включить журналирование содержимого запросов. Такие потенциально чувствительные настройки доступны только человеку через административную панель.
Сценарий pending secret
Наиболее показательный пример - настройка Telegram-бота, которого ещё не успели создать в BotFather.
Обычно агенту пришлось бы остановиться: конфигурация требует токен, но токена пока нет. В ProxyKey используется отложенная привязка.
1. Агент вызывает `create_pending_pass`.
2. Виртуальный токен `vlt_...` создаётся сразу и добавляется в конфигурацию приложения.
3. При обращении к прокси такой pass получает статус `original_key_required`, поскольку настоящий секрет ещё не указан.
4. Агент вызывает `get_manual_secret_setup` и передаёт человеку инструкцию или ссылку.
5. Пользователь открывает панель и вводит токен Telegram напрямую.
6. Pass автоматически активируется, без дополнительного участия агента.
7. Бот начинает работать с тем же виртуальным токеном, который уже был прописан в конфигурации.
За всё время значение настоящего ключа не появляется в контексте модели, файлах проекта или сообщениях агента.
Что остаётся человеку
Разграничение строится не на обещании "не показывать ключ", а на разделении интерфейсов.
Панель администратора предназначена для операций, где необходимо увидеть или ввести секрет: первоначальной настройки, замены ключа, удаления учётных данных и изменения чувствительных параметров.
MCP-интерфейс предназначен для автоматизации: выпуска виртуальных токенов, установки лимитов, отзыва доступа, просмотра метаданных и анализа статистики.
Такой дизайн снижает риск случайного раскрытия. Агент может управлять жизненным циклом доступа, но не получает инструмента, с помощью которого можно было бы извлечь исходный ключ.
Ограничения hosted-моделей
Изоляция секрета особенно важна при использовании облачных моделей. Даже если агент работает в доверенном окружении, его контекст может сохраняться, проходить трассировку или обрабатываться инфраструктурой поставщика модели.
Кроме того, агент может читать файлы проекта, вывод команд и содержимое документов. Если токен находится в `.env`, конфигурации или логах, он потенциально становится частью входных данных модели. Отдельный риск создают вредоносные инструкции в репозитории или внешних документах: промпт-инъекция может заставить агента вывести содержимое переменной, отправить его в другой сервис или записать в диагностический файл.
Proxy-подход не устраняет все угрозы, но исключает один из наиболее опасных классов: агент физически не получает значение секрета.
Дополнительные меры безопасности
Виртуальный токен следует выдавать с минимально необходимыми правами. Для разных окружений лучше создавать отдельные pass: например, для разработки, тестирования и продакшена. Это упрощает отзыв доступа и позволяет понять, какой именно компонент отправлял запросы.
IP-привязка полезна для сервисов со стабильной сетевой инфраструктурой. Если приложение работает через меняющиеся адреса, разумнее использовать более мягкий режим и компенсировать его коротким TTL, ограничением частоты запросов и регулярной ротацией.
Отдельные журналы по каждому pass помогают обнаружить аномалии без раскрытия ключа. При этом важно не включать запись тел запросов, если в них могут содержаться пользовательские данные или другие секреты.
Ротация виртуального токена также не требует замены реального ключа у провайдера. Можно перевыпустить pass, сохранить прежние ограничения и постепенно переключить приложение на новое значение.
Когда такой паттерн не подходит
ProxyKey не заменяет полноценную систему управления секретами во всех сценариях. Если процесс требует прямого доступа к ключу внутри доверенного backend-сервиса, лучше использовать специализированное хранилище секретов и строгую серверную авторизацию.
Дополнительный прокси-слой также может добавить задержку, зависимость от сети и необходимость контролировать доступность посредника. Для высоконагруженных систем потребуются продуманное кэширование служебных данных, мониторинг и резервные сценарии.
Наконец, виртуальный pass не защищает от злоупотреблений со стороны самого приложения, которому он выдан. Если атакующий получил возможность отправлять запросы через легитимный сервис, необходимо ограничивать методы, частоту, IP-диапазоны и срок действия токена.
Итог
Главная идея ProxyKey MCP - не передавать ИИ-агенту секрет, а предоставить ему безопасный интерфейс управления доступом. Агент может подготовить конфигурацию, создать виртуальный токен, настроить лимиты, проверить состояние и дождаться ручного ввода ключа. При этом настоящий API-ключ остаётся в панели и используется прокси только во время выполнения запроса.
Сценарий `pending secret` особенно удобен для автоматизации: разработку и развёртывание можно начать до выпуска реальных учётных данных, а затем активировать доступ без изменения конфигурации и без передачи токена модели. Такой подход не делает инфраструктуру абсолютно неуязвимой, но существенно уменьшает последствия утечки контекста и лучше соответствует принципу минимально необходимого доступа.