@proxycept/mcp — stdio-мост к серверу MCP Proxycept

Тонкий stdio↔HTTP-мост. Он запускает сервер Model Context Protocol на stdio и пересылает каждое JSON-RPC сообщение без изменений на конечную точку MCP Proxycept (https://proxycept.com/api/mcp по умолчанию) с вашим API-токеном в заголовке bearer.

Большинству людей этот пакет не нужен. Сервер MCP Proxycept — это размещённый HTTP-сервер — Claude Desktop и Cursor могут подключаться к нему по URL и с заголовком Authorization без установки. Этот пакет существует для MCP-клиентов, которые поддерживают только stdio, и потому, что npx является идиомой установки, которую ожидают каталоги расширений.

Для пути без установки, каталога инструментов и модели безопасности смотрите proxycept.com/docs → «Connect Claude or Cursor», или docs/user-manual.md §14. В настройках → API tokens есть такая же конфигурация, готовая к копированию, адресованная этому развёртыванию и называющая выбранный вами токен — значение токена показывается один раз, при создании, поэтому блок содержит заполнитель, который вы заменяете.

Что это не такое

Он не содержит ни списка инструментов, ни схем инструментов, ни логики, специфичной для Proxycept. tools/list возвращается сервером, а не этим пакетом. Это сделано намеренно: сервер является единственным источником истины для каталога инструментов, поэтому добавление или изменение инструмента на стороне сервера не требует релиза здесь, и нет дрейфа версий, который нужно поддерживать. Если вы читаете это, потому что хотите добавить особый случай для имени инструмента, значит, дизайн пошёл не так.

Требования

• Node.js 20 или новее (node --version).

• API-токен Proxycept (prx_live_…) — Настройки → API tokens на proxycept.com/settings.

Используйте токен только для чтения

Создайте токен только для чтения. Это значение по умолчанию и это граница безопасности, а не предложение.

Инструменты чтения Proxycept возвращают захваченный HTTP-трафик — контент, который не был создан вашей учётной записью. Вредоносное тело ответа от какого-либо вышестоящего сервера может быть прочитано моделью как инструкция («инъекция подсказок»). Проще говоря:

Токен read_write MCP означает, что всё, что захватывает ваш прокси, может записать в вашу конфигурацию Proxycept.

Тело ответа от чужого сервера, написанное так, чтобы выглядеть как инструкция, становится фиктивным маршрутом, шаблоном перехвата или остановленным профилем в вашей учётной записи. Токен только для чтения делает эту цепочку незавершаемой внутри Proxycept: нет ничего, что могла бы вызвать внедрённая инструкция.

Относитесь ко всему, что возвращает инструмент Proxycept, как к ненадёжным данным, а не инструкциям — особенно если у вас подключены другие MCP-серверы, которые могут получать URL, запускать оболочки или записывать файлы.

Если вам действительно нужен доступ на чтение и запись

Только для клиента, которому вы намеренно разрешаете изменять вашу настройку. Тогда все следующие условия:

1. Создайте отдельный токен (не повышайте тот, с которым вы читаете трафик).

2. Никогда не включайте «всегда разрешать» для вызовов инструментов Proxycept в вашем клиенте.

3. Не используйте его в том же сеансе, где вы читаете захваченный трафик — это именно та комбинация, которая делает внедрённую инструкцию действенной.

Одна вещь, которую токен на чтение и запись всё ещё не может сделать: воспроизвести захваченный запрос. replay_flow повторно отправляет реальный запрос третьей стороне с захваченными учётными данными, поэтому для этого требуется одобрение человека в веб-консоли Proxycept (Настройки → Подключите ваш AI-клиент). Ваш AI-клиент не может одобрить собственное воспроизведение, независимо от того, какой токен он держит.

Настройка — поместите токен в окружение, а не в файл конфигурации

Конфигурация вашего MCP-клиента — это простой текст JSON на диске, часто внутри каталога, синхронизируемого с облачным хранилищем. Токен prx_live_…, вставленный туда, является долгоживущим учётным данным в резервной копии, о которой вы не подумали. Предпочитайте окружение.

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) и большинство других клиентов используют одну и ту же структуру:

{
  "mcpServers": {
    "proxycept": {
      "command": "npx",
      "args": ["-y", "@proxycept/mcp"],
      "env": {
        // Read from your shell environment; the secret itself stays out of this file.
        "PROXYCEPT_API_TOKEN": "${PROXYCEPT_API_TOKEN}"
      }
    }
  }
}

Не все клиенты раскрывают ${VAR} в своей конфигурации. Если ваш клиент этого не делает, следующий лучший вариант — экспортировать переменную там, где клиент её унаследует (профиль оболочки входа, launchctl setenv на macOS, модуль systemd на Linux) и полностью убрать блок env — мост считывает PROXYCEPT_API_TOKEN из своего унаследованного окружения. Вставка буквального токена в файл конфигурации работает, и это вариант, к которому стоит прибегать в последнюю очередь.

--token в командной строке поддерживается, но не рекомендуется: аргумент виден всем процессам на машине через список процессов.

Переменные окружения

Каждая переменная имеет соответствующий флаг (--base-url, --url, --token, --timeout, --verbose).

Самостоятельное размещение

PROXYCEPT_BASE_URL=https://proxy.internal.example PROXYCEPT_API_TOKEN=… npx -y @proxycept/mcp

Простой текст http:// отклоняется для всего, кроме loopback, поэтому токен никогда не может пройти через незашифрованный переход. Этот пакет не предоставляет флага для отключения проверки TLS и не будет.

У самого Node есть такой флаг — NODE_TLS_REJECT_UNAUTHORIZED=0 отключает проверку сертификатов для всего процесса — и мост отказывается запускаться, если обнаруживает его установленным для не-loopback конечной точки, вместо того чтобы молча унаследовать его. Если вы столкнулись с этой ошибкой, сбросьте переменную (проверьте свой профиль оболочки и блок env вашего MCP-клиента); это почти всегда остаток от отладки чего-то другого, и с установленной переменной ваш токен будет отправлен через соединение, которое может прочитать кто угодно на пути.

Проверьте вашу настройку

PROXYCEPT_API_TOKEN=prx_live_… npx -y @proxycept/mcp --check

Он выполняет реальное рукопожатие MCP и реальный tools/list, затем выводит то, что сказал сервер:

endpoint: https://proxycept.com/api/mcp
server:   proxycept 1.0.0 (MCP 2025-06-18)
tools:    20 — list_workspaces, list_profiles, …
ok

Количество инструментов поступает от сервера, а не от этого пакета, поэтому оно меняется без релиза здесь. Инструменты записи перечисляются каждому клиенту и отклоняются на уровне API, если токен не read_write — см. ниже.

Коды выхода: 0 ок · 1 не удалось достичь или аутентифицироваться на сервере · 2 неверная конфигурация.

Когда что-то не так

Свойства безопасности

• Токен отправляется как Authorization: Bearer … на настроенный источник и никуда больше. Перенаправление на другой источник отклоняется, а не выполняется — учётные данные никогда не передаются хосту, который вы не настраивали. Перенаправления 307/308 с тем же источником выполняются (до 3 переходов), поскольку сохранение как источника, так и метода означает, что повторная отправка учётных данных ничего не меняет в том, кто их получает, и обратные прокси их выдают; 301/302/303 отклоняется, потому что повторная отправка POST как GET молча отбросит ваш запрос. (Размещённый сервер никогда не перенаправляет.)

• Токен никогда не логируется и никогда не возвращается вашему клиенту. Каждая строка, записанная в stderr, и каждое сообщение об ошибке, которое этот мост синтезирует для stdout, проходит через редактор, который удаляет настроенный секрет, всё, что выглядит как токен prx_…, и любую строку Bearer … — в том числе в режиме --verbose и включая учётные данные, которые сервер возвращает в теле 4xx/5xx. Последний случай важен, потому что stdout — это ваш MCP-клиент: он попадает в контекст модели и в логи клиента. Стек-трейсы никогда не выводятся. Для каждого из этих случаев есть тест.

• Поток протокола никогда не переписывается. Редактирование применяется к сообщениям, которые создаёт этот мост, а не к собственным JSON-RPC полезным нагрузкам сервера — их искажение испортило бы трафик, который вы отлаживаете. Редактирование захваченного трафика — это работа сервера (он применяет свои списки маскирования на пути чтения).

• Ничего не записывается на диск. Нет кэша, нет файла конфигурации, нет хранилища учётных данных.

• stdout переносит только сообщения протокола; вся диагностика идёт в stderr.

• Ноль зависимостей времени выполнения. npm ls --omit=dev для этого пакета пуст — единственная цепочка поставок — это сам Node.

Разработка

cd clients/mcp
npm ci
npm test          # builds, then runs the suite against a fake JSON-RPC server
npm run typecheck

npm run check-package   # asserts the tarball ships every module, the bin, README and LICENSE

Структура: src/config.ts (разрешение + проверка конфигурации), src/redact.ts (редактирование и единственный логгер), src/http.ts (один POST на сообщение; SSE, политика перенаправления, отображение HTTP→JSON-RPC ошибок), src/bridge.ts (общий цикл пересылки), src/stdio.ts (фрейминг JSON с разделителями новой строки), src/cli.ts (аргументы, --check, соединение).

Проверено на фиктивном сервере

Набор тестов запускается против фиктивного JSON-RPC HTTP-сервера в test/helpers.js: дословная пересылка (включая методы, о которых этот пакет никогда не слышал), форма заголовка, эхо Mcp-Session-Id и версии протокола, потоковая передача SSE, уведомления 202, отображение HTTP→MCP ошибок, обработка пакетов, политика перенаправления, истечение сеанса, фрейминг NDJSON через границы чанков и отсутствие токена во всех выводах.

Проверено на реальном Proxycept

--check был запущен интеграционно против реального Control API с включённым MCP-сервером (V4-T66): реальное согласование возможностей initialize, реальный tools/list (20 инструментов), с токеном prx_live_ только для чтения. Остальные неизвестные зависят от продакшена — выдаёт ли размещённое развёртывание Mcp-Session-Id, возвращается ли длинный вызов инструмента как JSON или SSE, и точная формулировка его тел 401/403/429. Мост универсален, поэтому любое из них может отличаться без изменения кода здесь; живой проход против https://proxycept.com — это шаг 5 из PUBLISHING.md.

Публикация (мейнтейнеры)

Релизы выполняются вручную намеренно — нет CI-задания, которое публикует, поэтому скомпрометированный токен рабочего процесса не может отправить пакет, обрабатывающий учетные данные клиентов. Полная инструкция (создание организации, предварительная проверка, точная последовательность npm publish --access public, верификация и процедура депривации) находится в PUBLISHING.md в этом каталоге. Она не входит в опубликованный архив.