zscaler-mcp-server — это сервер Model Context Protocol (MCP), который соединяет AI‑агентов с платформой Zscaler Zero Trust Exchange. По умолчанию сервер работает в режиме только для чтения ради безопасности и требует явного включения для записи.

Подтверждение поддержки

-> Заявление об ограничениях: перед использованием данного провайдера, пожалуйста, ознакомьтесь с нашим Общим заявлением о поддержке (замените текст ссылки на русский). Также смотрите наше руководство по устранению неполадок для справки по типичным проблемам.

Важно

🚧 Public Preview: данный проект в настоящее время находится на стадии публичного предварительного просмотра и активно развивается. Возможны изменения функций до стабильного выпуска 1.0. Рекомендуем избегать продакшн-развертываний. Мы будем благодарны за отзывы через GitHub Issues, которые помогут сформировать финальный релиз.

Требования

Конфигурация окружения
Установка
Использование

Командная строка

Конфигурация сервиса
Дополнительные параметры командной строки
Учётные данные и аутентификация Zscaler API

OneAPI Аутентификация

Устойчивость к проблемам аутентификации
Конфигурация MCP Server
Как библиотека
Использование в контейнере

Использование готового образа (рекомендовано)

Сборка локально (разработка)
Интеграция с редактором/ассистентом

Использование uvx (рекомендуется)

Соms выбор сервиса
Использование отдельных переменных окружения
Версия Docker
Дополнительные варианты развертывания

Удалённое развертывание MCP (EC2, VM и пр.)

Azure Container Apps / Virtual Machine / AKS (Preview)
Google Cloud (Cloud Run / GKE / VM / ADK агент)
Kubernetes (Helm Chart)
Amazon Bedrock AgentCore
Использование MCP Server с агентами

Claude Desktop

Cursor
Visual Studio Code + GitHub Copilot
Платформенные интеграции
Устойчивость и устранение неполадок
Лицензия

📺 Обзор

Сервер Zscaler Integrations MCP Server добавляет контекст вашим агентам. Примеры запросов:

"List my ZPA Application segments"
"List my ZPA Segment Groups"
"List my ZIA Rule Labels"

Важно

🚫 РЕЖИМ ТОЛЬКО-ЧТЕНИЕ ПО УМОЛЧАНИЮ: для повышения безопасности этот MCP сервер по умолчанию работает в режиме read-only. Доступны только операции list_* и get_*. Чтобы включить инструменты, допускающие создание, обновление или удаление ресурсов Zscaler, вы должны явно включить режим записи, используя флаг --enable-write-tools или установив ZSCALER_MCP_WRITE_ENABLED=true. Подробности — в разделе Безопасность и разрешения.

Совет

Эффективное формулирование промптов: на сервере доступно 402 инструментa для многих сервисов Zscaler. Большинство клиентов MCP (Claude Desktop, Cursor и т. д.) используют откладываемую загрузку инструментов и будут искать инструменты, соответствующие вашему промпту. Чтобы получить наилучшие результаты, точно указывайте сервис и действие в промптах:

Хорошо: «List my ZPA application segments» — целевой сервис и инструмент заданы напрямую
Хорошо: «Show ZIA firewall rules» — понятный сервис (zia) и действие (list)
Менее эффективно: «Show me my devices» — неоднозначно; несколько сервисов предоставляют инструменты, связанные с устройствами

Когда сервис отключён, его инструменты полностью удаляются из сервера. Однако AI‑агент может попытаться найти связанные инструменты в других сервисах. Если результат неожиданный, уточняйте промпт конкретным именем сервиса (например, zpa, zia, zdx, zcc, zcell, zms).

🔒 Безопасность и разрешения

Сервер Zscaler MCP реализует дизайн, ориентированный на безопасность, с детальным управлением разрешениями и безопасными значениями по умолчанию:

Режим только для чтения (по умолчанию — всегда доступен)

По умолчанию сервер работает в режиме только для чтения, доступными являются только инструменты, возвращающие список или данные:

✅ ВСЕГДА ДОСТУПНО — инструменты read-only зарегистрированы на сервере
✅ Подходит для автономной работы AI‑агентов
✅ Нет риска случайного изменения или удаления ресурсов
✅ Все операции list_* и get_* доступны (110+ read-only инструментов)
❌ Все операции create_*, update_* и delete_* отключены по умолчанию
💡 Примечание: может потребоваться включить read-only инструменты в настройках UI вашего AI‑агента

# Read-only mode (default - безопасный режим)
zscaler-mcp

Когда сервер запускается в режиме read-only, вы увидите:

🔒 Server running in READ-ONLY mode (safe default)
   Only list and get operations are available
   To enable write operations, use --enable-write-tools AND --write-tools flags

💡 Read-only инструменты ВСЕГДА зарегистрированы сервером независимо от любых флагов. Их не нужно включать на стороне сервера. Примечание: UI вашего AI‑агента (например, Claude Desktop) может требовать включения отдельных инструментов перед использованием.

Режим записи (Explicit Opt-In — Allowlist ОБЯЗАТЕЛЕН)

Чтобы включить инструменты, которые могут создавать, изменять или удалять ресурсы Zscaler, необходимо предоставить ОБА флага:

✅ --enable-write-tools — глобальная разблокировка для записывающих операций
✅ --write-tools "pattern" — ОБЯЗАТЕЛЬНО явный allowlist

🔐 БЕЗОПАСНОСТЬ: Allowlist ОБЯЗАТЕЛЕН — если вы задали --enable-write-tools без --write-tools, будет зарегистрировано 0 write‑tools. Это обеспечивает явный выбор пишущих операций.

# ❌ Неправильно: без allowlist запись не включится
zscaler-mcp --enable-write-tools

# ✅ Правильно: требуется явный allowlist
zscaler-mcp --enable-write-tools --write-tools "zpa_create_*,zpa_delete_*"

При попытке включить режим записи без allowlist выводится:

⚠️  WRITE TOOLS MODE ENABLED
⚠️  NO allowlist provided - 0 write tools will be registered
⚠️  Read-only tools will still be available
⚠️  To enable write operations, add: --write-tools 'pattern'

Allowlist инструментов для записи (ОБЯЗАТЕЛЬНО)

Allowlist обеспечивает двухуровневую защиту:

✅ Первая защита: --enable-write-tools — глобальная разблокировка
✅ Вторая защита: явный allowlist определяет, какие инструменты записи будут зарегистрированы (обязательно)

Примеры allowlist’ов:

# Разрешить ТОЛЬКО конкретные инструменты записи с использованием подстановок
zscaler-mcp --enable-write-tools --write-tools "zpa_create_*,zpa_delete_*"

# Разрешить конкретные инструменты без подстановок
zscaler-mcp --enable-write-tools --write-tools "zpa_create_application_segment,zia_create_rule_label"

# Разрешить все операции записи для ZPA (но без ZIA/ZDX/ZTW)
zscaler-mcp --enable-write-tools --write-tools "zpa_*"

Или через переменные окружения:

export ZSCALER_MCP_WRITE_ENABLED=true
export ZSCALER_MCP_WRITE_TOOLS="zpa_create_*,zpa_delete_*"
zscaler-mcp

Поддерживаемые паттерны подстановки:

zpa_create_* — разрешить все инструменты создания ZPA
zpa_delete_* — разрешить все инструменты удаления ZPA
zpa_* — разрешить все пишущие инструменты ZPA
*_application_segment — разрешить все операции над сегментами приложений
zpa_create_application_segment — точное совпадение (без подстановки)

При использовании корректного allowlist’а вы увидите:

⚠️  WRITE TOOLS MODE ENABLED
⚠️  Explicit allowlist provided - only listed write tools will be registered
⚠️  Allowed patterns: zpa_create_*, zpa_delete_*
⚠️  Server can CREATE, MODIFY, and DELETE Zscaler resources
🔒 Security: 85 write tools blocked by allowlist, 8 allowed

Философия дизайна инструментов

Кажная операция — отдельный инструмент с конкретным именем, ясно отражающим назначение:

✅ Хорошо (Глагольная основа — текущий дизайн)

zpa_list_application_segments    ← Read-only, безопасно для allow-list
zpa_get_application_segment      ← Read-only, безопасно для allow-list
zpa_create_application_segment   ← Операция записи, требует --enable-write-tools
zpa_update_application_segment   ← Операция записи, требует --enable-write-tools
zpa_delete_application_segment   ← Уничтожающая операция, требует --enable-write-tools

Такой подход позволяет AI‑помощникам (Claude, Cursor, GitHub Copilot):

разрешать read-only инструменты для автономного исследования
требовать явного подтверждения пользователя для операций записи
чётко понимать назначение каждого инструмента по названию

Ответы: API‑запись в неизменном виде

Read‑tool возвращает запись Zscaler API без изменений. Сервер не

обрезает, не переименовывает и не переобъявляет набор атрибутов ресурса — этот набор атрибутов принадлежит API, поэтому будущее добавление полей Zscaler будет приходить к вам без обновления сервера.

Чтобы ответы были короткими, вы контролируете возвращаемое, а не сервер:

--toolsets — загружать только нужный срез инструментов, чтобы каталог инструментов оставался небольшим (см. Toolsets).
query — каждый list‑инструмент принимает опциональное выражение JMESPath применяемое к результатам, чтобы агент проецировал ровно то, что нужно:

zcc_list_devices(query="[*].{user: user, policy: policyName}")   # только два поля
zcc_list_devices(query="[?registrationState=='Quarantined']")    # только изолированные устройства
zcc_list_devices(query="length(@)")                              # только счетчик

Названия полей совпадают с тем, что возвращает Zscaler API. Оставьте query пустым, чтобы получить полные записи.

Уровни безопасности

Сервер реализует несколько уровней безопасности ( defense-in-depth ). Первые девять уровней применяются на каждом транспорте, включая stdio — они управляют тем, какие инструменты доступны и как подтверждаются опасные вызовы. Остальные уровни HTTP‑зависимы (TLS, проверка host‑header, ACL по источнику IP, аутентификация MCP‑клиента) и описаны в разделе Сетевые уровни контроля (только HTTP) ниже.

Инструменты Read‑Only всегда включены: безопасные операции list_* и get_* доступны всегда (254 инструмента read-only).
По умолчанию режим записи отключён: инструменты записи отключены, если явно не включено через --enable-write-tools.
Обязательный Allowlist: записи требуют явного --write-tools allowlist (с поддержкой подстановок).
OneAPI Entitlement Filter: на старте, для продуктов, на которые учетные данные OneAPI не могут обращаться, соответствующие toolsets отбрасываются (см. ниже в разделе OneAPI Entitlement Filter).
Выбор toolsets: можно сузить зарегистрированную поверхность инструментов до конкретного среза (например, --toolsets zia_url_filtering,zpa_app_segments). См. раздел Toolsets.
Название инструментов по глаголу: каждый инструмент явно указывает на своё назначение (list, get, create, update, delete).
Аннотации метаданных инструментов: все инструменты аннотированы как readOnlyHint или destructiveHint для фреймворков AI‑агентов.
Подтверждение со стороны AI‑агента: все инструменты записи, помеченные destructiveHint=True, вызывают диалог с разрешениями в AI‑помощнике.
Человеческое подтверждение для DELETE: операции удаления требуют подтверждения сервера. У клиентов, поддерживающих elicitation (Claude Desktop, Cursor), сервер просит клиента запросить у человека подтверждение, и ответ приходит как протокольное поле — чтобы подменённый агент не мог авторизовать удаление. Клиенты без такой возможности используют криптографический токен подтверждения (HMAC-SHA256, одноразовый, TTL 5 минут), связанный с конкретной операцией и параметрами.
Контроль через переменные окружения: ZSCALER_MCP_WRITE_ENABLED, ZSCALER_MCP_WRITE_TOOLS, ZSCALER_MCP_TOOLSETS, ZSCALER_MCP_DISABLE_ENTITLEMENT_FILTER и списки отключений можно управлять централизованно без изменений кода.
Очистка вывода: каждый текст в результатах инструментов пропускается через трехступенчатый санитайзер перед попаданием в агент — скрытые/управляющие символы (BiDi overrides, нулевые символы, BOM, мягкие дефисы) удаляются, HTML и комментарии удаляются (через bleach), синтаксис Markdown-ссылок/изображений нейтрализуется, чтобы встроенные URL не могли быть внедрены в агента, а info‑строки fenced code blocks, содержащие токены impersonation (system, assistant, tool, ignore, …) сводятся к нейтральному тегу text. Это защита от атак prompt‑injection. По умолчанию включено. Отключить можно через ZSCALER_MCP_DISABLE_OUTPUT_SANITIZATION=true (используйте только для диагностики).
Аудит‑логирование: при включённом --log-tool-calls / ZSCALER_MCP_LOG_TOOL_CALLS=true каждое выполнение инструмента логируется с аргументами (чувствительные значения замаскированы), длительностью и кратким результатом.

Этот многоуровневый подход обеспечивает сохранность безопасности даже если один контроль обходят, другие остаются в силе. Уровни 1–12 применяются на любых транспортах: stdio, sse и streamable-http.

Toolsets

Инструменты сгруппированы в 63 именованных toolsets, чтобы можно было загружать только тот срез, который нужен агенту (например, zia_url_filtering (5 инструментов) вместо загрузки всех инструментов от обслуживаемого сервиса). Toolsets уменьшают стоимость контекста агента и улучшают точность отбора инструментов.

# Загрузить только два среза
zscaler-mcp --toolsets zia_url_filtering,zpa_app_segments

# Или использовать предустановленный набор по умолчанию
zscaler-mcp --toolsets default

# Или загрузить все зарегистрированные toolsets
zscaler-mcp --toolsets all

# Эквивалент через переменную окружения
export ZSCALER_MCP_TOOLSETS="zia_url_filtering,zpa_app_segments"

Когда параметр --toolsets не указан, загружаются все toolsets, чьи сервисы включены (сохранение исторически принятого поведения по умолчанию).

Агент может также включать дополнительные toolsets во время выполнения через постоянно включённые инструменты zscaler_list_toolsets, zscaler_get_toolset_tools и zscaler_enable_toolset.

Полный каталог (29 toolsets по всем сервисам), правила приоритета фильтрации, рекомендации по инструментам и полная справка есть в docs/guides/toolsets.md.

OneAPI Entitlement Filter

После разрешения toolset сервер читает токен OneAPI и скрывает toolset’ы для продуктов, к которым у клиента нет прав. Если ваш клиент OneAPI имеет доступ только к ZIA и ZPA, то все toolset’ы для zdx_* / zcc_* / ztw_* / zid_* / zeasm_* / zins_* / zms_* будут отброшены на старте — даже если указан --toolsets all.

Это предотвращает обнаружение инструментов, первый вызов которых вернёт только 401 Unauthorized. Фильтр применяется на каждом транспорте, включая stdio.

Если нужно обойти фильтр (для диагностики необычной формы токена), используйте:

zscaler-mcp --no-entitlement-filter
# или
export ZSCALER_MCP_DISABLE_ENTITLEMENT_FILTER=true

Обрабатываются только продуктовые entitlement — роли не влияют. Сервер передает на стороне API проверку прав по конкретному действию; entitlement‑фильтр лишь препятствует объявлению инструментов для продуктов, к которым клиент не имеет доступа.

Криптографическое подтверждение для разрушительных действий

Удаление не выполняется при первом вызове. Что происходит дальше зависит от клиента:

Клиенты, поддерживающие elicitation получают интерактивную подсказку с названием ресурса, на которую отвечает человек. Агент не получает доступ к одобрению.
Все остальные клиенты получают криптографический подтверждающий токен (HMAC-SHA256), который должен быть передан обратно для продолжения. Токен привязан к конкретной операции и параметрам, одноразовый и действует 5 минут — нельзя подделать, повторно использовать или применить к другому ресурсу.

Запрещено отключать этот механизм. Удаления необратимы на живом арендаторе, поэтому сервер не предоставляет флаг или переменную окружения, который пропускает этот этап. Если вы не хотите, чтобы агент что‑то удалял, не включайте инструменты удаления: режим записи выключен по умолчанию и --write-tools принимает явные паттерны (см. раздел Режим записи).

Контроль на уровне сети (HTTP только)

Следующие четыре подпункта — TLS, allowlist по IP источника, проверка host‑header и сканер plaintext‑секретов .env — применяются только к HTTP‑транспортам (sse, streamable-http). Они контролируют, кто может достичь сервера по сети. Они независимы от инструментальных контролей уровня безопасности, перечисленных выше (режим read-only, allowlist на запись, toolsets, entitlement‑фильтр, уведомления через HMAC), которые применяются на каждом транспорте, включая stdio.

Соответствующая аутентификация MCP клиента (Bearer / Basic / OAuth 2.1) — пятый уровень сетевой защиты — подробно описана в разделе Аутентификация MCP Client ниже.

Поддержка HTTPS/TLS

HTTPS требуется по умолчанию для не‑локальных развертываний. Сервер откажется запускаться на не‑локальном интерфейсе без TLS‑сертификатов, если явно не установлено ZSCALER_MCP_ALLOW_HTTP=true.

При работе с HTTP‑транспортами (sse или streamable-http) предоставляйте TLS‑сертификаты:

ZSCALER_MCP_TLS_CERTFILE=/path/to/cert.pem
ZSCALER_MCP_TLS_KEYFILE=/path/to/key.pem

# Необязательно: пароль приватного ключа и CA‑пакеты
ZSCALER_MCP_TLS_KEYFILE_PASSWORD=your-key-password
ZSCALER_MCP_TLS_CA_CERTS=/path/to/ca-bundle.pem

При настройке TLS сервер автоматически запускается с HTTPS. Это работает как с общими (CA‑подписанными), так и с частными (самоподписанными) сертификатами. Для тестирования можно сгенерировать самоподписанный сертификат:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes \
  -subj "/CN=localhost"

Контроль доступа по IP источника

Можно ограничить набор клиентских IP, позволенных для подключения, используя переменную окружения ZSCALER_MCP_ALLOWED_SOURCE_IPS. При неустановке фильтрация по IP источника отключена и передана под ноги внешним контролям (фаервол, AWS Security Groups и пр.).

# Разрешить только конкретные IP/сети
ZSCALER_MCP_ALLOWED_SOURCE_IPS=10.0.0.0/8,172.16.0.5

# Разрешить все (то же, что и не устанавливать переменную)
ZSCALER_MCP_ALLOWED_SOURCE_IPS=0.0.0.0/0

Поддерживаются отдельные IPv4/IPv6 адреса, CIDR и wildcard 0.0.0.0/0. Эндпойнты здоровья (/health, /healthz, /ready) свободны от ограничений, чтобы проверки балансировщиков продолжали работать. Запросы с запрещённых IP возвращают 403 Forbidden.

Безопасность `.env` файл предупреждение

При старте с HTTP‑транспортами сервер автоматически сканирует файл .env в рабочем каталоге на предмет plaintext‑секретов (значения с SECRET, PASSWORD, KEY или TOKEN). При обнаружении выдается предупреждение о безопасности с настоятельной рекомендацией использовать секрет‑менеджер или переменные окружения.

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

При запуске сервер регистрирует сводный Security Posture Banner, суммарно отражающий активную конфигурацию безопасности — режим транспорта, статус валидации хоста, режим аутентификации, TLS, и любые активные предупреждения. Это облегчает быструю проверку состояния безопасности.

Ключевые принципы безопасности:

Нет скрытой кнопки «включить все инструменты записи» — allowlist обязательно
AI‑агенты должны запрашивать разрешение на выполнение любых операций записи (destructiveHint)
Каждое разрушительное действие требует явного одобрения через систему разрешений AI‑агента
Разрушительные подтверждения криптографически привязаны, чтобы предотвратить обход
Контроль через переменные окружения: ZSCALER_MCP_WRITE_ENABLED, ZSCALER_MCP_WRITE_TOOLS, ZSCALER_MCP_TOOLSETS, ZSCALER_MCP_DISABLE_ENTITLEMENT_FILTER, и списки отключений

Лучшие практики

Read‑Only по умолчанию: безопасные операции не требуют настройки — read‑only инструменты всегда доступны
Обязательный Allowlist: всегда задавайте явный --write-tools
Разработка/Тестирование: используйте узкие allowlist’ы (например, --write-tools "zpa_create_application_segment")
Продакшен/Агенты: держите сервер в режиме read‑only для автономных операций
CI/CD: никогда не устанавливайте ZSCALER_MCP_WRITE_ENABLED=true без соответствующего ZSCALER_MCP_WRITE_TOOLS
Наименьшие привилегии: используйте как можно более узкие паттерны allowlist
Использование подстановок: для контроля на уровне сервиса (например, zpa_create_*) или операции (например, *_create_*)
Аудит: регулярно пересматривайте, какие write‑инструменты разрешены, и удаляйте лишнее
Конкретные промпты: учитывая 402 инструмента и отложенную загрузку, используйте промпты, соответствующие нужному сервису

🔐 MCP Client Authentication

📖 Полная документация: Authentication & Deployment Guide

При работе MCP Server поверх HTTP (sse или streamable-http) можно включить аутентификацию для контроля кто может подключиться к серверу. Это независимо от учетных данных Zscaler API, которые контролируют, как сервер аутентифицируется к Zscaler API.

Для HTTP‑транспорта сервер автоматически обнаруживает и включает аутентификацию, если присутствуют переменные окружения, связанные с аутентификацией. Для stdio аутентификация не применяется (изоляция процессов обеспечивает безопасность).

Режимы аутентификации

Сервер поддерживает четыре режима аутентификации, настраиваемые через переменные окружения:

Режим	Описание	Лучшее применение
api-key	Простая общая секрета — клиент отправляет Authorization: Bearer	Быстрая настройка, внутр. окружения, разработка
jwt	Внешний IdP через JWKS — токены валидируются локально по открытым ключам	Корпоративный SSO, многоарендная архитектура (Auth0, Okta, Azure AD, Keycloak, AWS Cognito, PingOne, Google)
zscaler	Валидация учетных данных Zscaler OneAPI — клиент отправляет Basic Auth с client_id:client_secret	Окружения, уже использующие учетные данные Zscaler API
oidc	OAuth 2.1 через ваш IdP — ресурс охраняется OAuth 2.0 (RFC 9728) и клиенты аутентифицируются напрямую через IdP	Вход через браузер для операторов‑людей, любой OIDC‑провайдер

Быстрый старт

Включите аутентификацию, установив в вашем .env следующие переменные:

# Включение аутентификации
ZSCALER_MCP_AUTH_ENABLED=true
ZSCALER_MCP_AUTH_MODE=api-key

# Для режима api-key: задайте общий секрет
ZSCALER_MCP_AUTH_API_KEY=sk-your-secret-key-here

Затем запустите сервер с HTTP‑транспортом:

zscaler-mcp --transport streamable-http

Клиенты должны включать ключ в заголовке Authorization:

Authorization: Bearer sk-your-secret-key-here

Как это работает

Аутентификация реализована как промежуточное звено ASGI, которое оборачивает HTTP‑транспорт:

MCP Client Request
      │
      ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Auth         │────▶│  MCP          │────▶│  Zscaler     │
│  Middleware   │     │  Server       │     │  APIs        │
└──────────────┘     └──────────────┘     └──────────────┘
 Layer 1: WHO          MCP Protocol        Layer 2: HOW
 can connect?          Processing          server talks
                                           to Zscaler

Слой 1 (MCP Client Auth): управляется переменными ZSCALER_MCP_AUTH_* — валидирует входящий запрос
Слой 2 (Zscaler API Auth): управляется ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET и пр. — аутентифицирует сервер к Zscaler API

Эти два слоя полностью независимы. Можно включить один, оба или ни один.

Конфигурация по режимам

API Key

ZSCALER_MCP_AUTH_ENABLED=true
ZSCALER_MCP_AUTH_MODE=api-key
ZSCALER_MCP_AUTH_API_KEY=sk-your-secret-key-here

JWT (External IdP через JWKS)

ZSCALER_MCP_AUTH_ENABLED=true
ZSCALER_MCP_AUTH_MODE=jwt
ZSCALER_MCP_AUTH_JWKS_URI=https://your-idp.com/.well-known/jwks.json
ZSCALER_MCP_AUTH_ISSUER=https://your-idp.com
ZSCALER_MCP_AUTH_AUDIENCE=zscaler-mcp-server
ZSCALER_MCP_AUTH_ALGORITHMS=RS256,ES256   # Optional (по умолчанию RS256,ES256)

Zscaler OneAPI Credentials

ZSCALER_MCP_AUTH_ENABLED=true
ZSCALER_MCP_AUTH_MODE=zscaler
# Использует ZSCALER_VANITY_DOMAIN и ZSCALER_CLOUD из вашей конфигурации

Клиенты аутентифицируются с базовым доступом (Basic Auth) (client_id:client_secret) или собственными заголовками (X-Zscaler-Client-ID / X-Zscaler-Client-Secret).

По умолчанию аутентификация

Для HTTP‑транспортов (sse, streamable-http) сервер автоматически обнаруживает и включает аутентификацию, если присутствуют связанные с ней переменные окружения (например, ZSCALER_MCP_AUTH_JWKS_URI, ZSCALER_MCP_AUTH_API_KEY или ZSCALER_VANITY_DOMAIN). Если аутентификация не сконфигурирована и ZSCALER_MCP_AUTH_ENABLED не явно задана, сервер регистрирует предупреждение безопасности и продолжает работу без аутентификации.

Чтобы явно отключить аутентификацию, задайте:

ZSCALER_MCP_AUTH_ENABLED=false

Аутентификация не применяется к транспорту stdio (изоляция ОС обеспечивает безопасность).

OAuth 2.1 (`oidc` режим)

oidc режим превращает сервер в ресурс, защищённый OAuth 2.0 (RFC 9728). Сервер публикует /.well-known/oauth-protected-resource, указывая ваш IdP; клиент выполняет OAuth‑поток напрямую через IdP и предоставляет полученный токен. Единственная задача сервера — проверить подпись токена по открытым ключам IdP.

Настройка осуществляется полностью через переменные окружения — без кода и дополнительных пакетов:

OIDCPROXY_BASE_URL=http://localhost:8000
OIDCPROXY_AUDIENCE=zscaler-mcp-server
# Optional: scopes a token must carry, comma-separated
# OIDCPROXY_REQUIRED_SCOPES=zscaler.read
ZSCALER_MCP_AUTH_ENABLED=true
ZSCALER_MCP_AUTH_MODE=oidc

OIDCPROXY_CONFIG_URL=https://your-tenant.auth0.com/.well-known/openid-configuration
OIDCPROXY_CLIENT_ID=<your app registration's client id>
OIDCPROXY_BASE_URL=http://localhost:8000
OIDCPROXY_AUDIENCE=zscaler-mcp-server
# Optional: scopes a token must carry, comma-separated
# OIDCPROXY_REQUIRED_SCOPES=zscaler.read

Примечания:

Для IdP: приложение с callback URL вашего клиента (http://localhost:3334/oauth/callback для mcp-remote, порт фиксирован) зарегистрировано, и идентификатор API совпадает с OIDCPROXY_AUDIENCE.
Нет клиента секрета. Подпись токена проверяется по ключам IdP, не по нашим учетным данным. OIDCPROXY_CLIENT_SECRET игнорируется, если задан.
OIDCPROXY_BASE_URL — это публичный URL вашего сервера, используемый клиентами в качестве идентификатора ресурса — а не URL IdP.
OIDCPROXY_AUDIENCE по умолчанию совпадает с OIDCPROXY_CLIENT_ID. В Entra ID ID клиента в aud; Auth0 использует идентификатор API.
провайдеры IdP: все совместимы с OpenID Connect (Auth0, Okta, Microsoft Entra ID, Keycloak, Google, AWS Cognito, PingOne).
Все остальные слои безопасности (TLS, ACL по источнику, проверка Host) остаются активными.

📖 Подробные инструкции настройки — включая пошаговое руководство по Microsoft Entra ID, конфигурацию IdP JWKS, примеры для Docker, конфигурацию клиента для Claude/Cursor/VS Code и устранение неполадок: Authentication & Deployment Guide.

Поддерживаемые инструменты

Сервер Zscaler Integrations MCP Server предоставляет 402 инструмента для всех основных сервисов Zscaler:

Сервис	Описание	Инструменты
ZIA	Zscaler Internet Access — политики безопасности	166 read/write
ZPA	Zscaler Private Access — доступ к приложениям	109 read/write
ZDX	Zscaler Digital Experience — мониторинг и аналитика	31 read/write
ZCell	Zscaler Cellular — учёт SIM‑карт, аналитика использования и политики отклонений	20 read-only
ZMS	Zscaler Microsegmentation — агенты, ресурсы, политики	20 read-only
ZTW	Zscaler Workload Segmentation	19 read/write
Z-Insights	Z-Insights analytics — веб‑трафик, киберинциденты, shadow IT	16 read-only
ZIdentity	ZIdentity — идентификация и доступ	10 read-only
EASM	External Attack Surface Management	7 read-only
ZCC	Zscaler Client Connector — управление устройствами	4 read-only

📖 Полный справочник инструментов →

Примечание: все операции записи требуют флага --enable-write-tools и явного allowlist’а --write-tools. Подробности — в разделе Безопасность и разрешения.

Установка и настройка

Требования

Python 3.11 и выше
uv или pip
учетные данные Zscaler API (см. ниже)

Конфигурация окружения

Скопируйте пример файла окружения и настройте ваши учетные данные:

cp .env.example .env

Затем отредактируйте .env с вашими учетными данными Zscaler API:

Необходимая конфигурация (OneAPI):

ZSCALER_CLIENT_ID: Ваш Zscaler OAuth client ID
ZSCALER_CLIENT_SECRET: Ваш Zscaler OAuth client secret
ZSCALER_CUSTOMER_ID: Ваш Zscaler customer ID
ZSCALER_VANITY_DOMAIN: Ваш vanity domain

Опциональная конфигурация:

ZSCALER_CLOUD: (Опционально) облачный окружение (e.g., beta) — требуется только для работы с Beta Tenant
ZSCALER_PRIVATE_KEY: (Опционально) PEM‑кодированный приватный ключ для JWT‑аутентификации, используется вместо ZSCALER_CLIENT_SECRET
ZSCALER_MCP_SERVICES: список сервисов через запятую (по умолчанию — все сервисы)
ZSCALER_MCP_TRANSPORT: транспорт — stdio, sse, или streamable-http (по умолчанию stdio)
ZSCALER_MCP_DEBUG: включить отладочный логгинг — true/false (по умолчанию false)
ZSCALER_MCP_HOST: хост для HTTP‑транспорта (по умолчанию 127.0.0.1)
ZSCALER_MCP_PORT: порт для HTTP‑транспорта (по умолчанию 8000)

Альтернатива — можно устанавливать переменные окружения без файла .env.

Важно: убедитесь, что ваш API‑клиент имеет необходимые разрешения для выбранных сервисов. В любой момент можно обновить разрешения в консоли Zscaler.

Установка

Установка через VS Code (быстрая настройка)

Примечание: это откроет VS Code и предложит конфигурацию MCP сервера. Необходимо заменить заполнители (<YOUR_CLIENT_ID>, и т. д.) на ваши реальные учетные данные Zscaler.

Установка с использованием uv (рекомендуется)

uv tool install zscaler-mcp

Установка из исходников через uv (разработка)

uv pip install -e .

Удалённое развёртывание: при работе на EC2/VM сначала активируйте окружение проекта: source .venv/bin/activate. См. Remote MCP Deployment.

Установка из исходников через pip

pip install -e .

Установка через make (для удобства)

make install-dev

Подсказка

Если zscaler-mcp-server не найден, добавьте путь к исполняемому файлу в PATH.

Для интеграции с редакторами/помощниками смотрите раздел Использование MCP Server с агентами.

Использование

Примечание

Стандарт безопасности по умолчанию: все примеры ниже выполняются в режиме read-only (только list_* и get_*). Чтобы включить операции записи (create_*, update_*, delete_*), добавьте флаг --enable-write-tools к любой команде или задайте ZSCALER_MCP_WRITE_ENABLED=true в окружении.

Командная строка

Запустите сервер с настройками по умолчанию (stdio транспорт, read-only):

zscaler-mcp

Запустите сервер с включёнными операциями записи:

zscaler-mcp --enable-write-tools

Запуск с SSE транспортом:

zscaler-mcp --transport sse

Запуск с транспортом streamable-http:

zscaler-mcp --transport streamable-http

Запуск с транспортом streamable-http на произвольном порту:

zscaler-mcp --transport streamable-http --host 0.0.0.0 --port 8080

Конфигурация сервиса

Сервер Zscaler Integrations MCP поддерживает несколько способов указания включённых сервисов:

1. Аргументы командной строки (наивысший приоритет)

Укажите сервисы через списки через запятую:

# Включить конкретные сервисы
zscaler-mcp --services zia,zpa,zdx

# Включить только один сервис
zscaler-mcp --services zia

2. Переменная окружения (резервный вариант)

Задайте переменную ZSCALER_MCP_SERVICES:

# Экспорт переменной окружения
export ZSCALER_MCP_SERVICES=zia,zpa,zdx
zscaler-mcp

# Или передать в одну строку
ZSCALER_MCP_SERVICES=zia,zpa,zdx zscaler-mcp

3. Поведение по умолчанию (все сервисы)

Если ни параметры командной строки, ни переменная окружения не заданы, включаются все доступные сервисы.

Порядок приоритета сервисов:

аргумент командной строки --services (перекрывает всё)
переменная окружения ZSCALER_MCP_SERVICES (резервная)
все сервисы (по умолчанию)

Исключение сервисов и инструментов

Чтобы сохранить большую часть инструментов доступной, но исключить несколько, используйте --disabled-tools или --disabled-services вместо перечисления всех включённых инструментов.

Оба флага поддерживают подстановки через шаблоны (паттерны) в стиле fnmatch.

# Исключить один инструмент
zscaler-mcp --disabled-tools zia_list_devices

# Исключить все инструменты по префиксу сервиса
zscaler-mcp --disabled-tools "zcc_*"

# Исключить несколько паттернов
zscaler-mcp --disabled-tools "zcc_*,zdx_list_devices"

# Исключить целые сервисы
zscaler-mcp --disabled-services zcc,zdx

# Комбинация: оставить сервисы, но исключить конкретные инструменты
zscaler-mcp --disabled-tools "zia_list_devices,zdx_*_analysis"

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

export ZSCALER_MCP_DISABLED_TOOLS="zia_list_devices,zdx_*"
export ZSCALER_MCP_DISABLED_SERVICES="zcc"

Приоритет: --disabled-tools имеет преимущество над --tools (список включённых). Инструмент, совпадающий с обоими списками, будет исключен.

Дополнительные параметры командной строки

# Включить операции записи (create, update, delete)
zscaler-mcp --enable-write-tools

# Включить отладочный логgинг
zscaler-mcp --debug

# Комбинация нескольких опций
zscaler-mcp --services zia,zpa --enable-write-tools --debug

Для полного списка доступных опций:

zscaler-mcp --help

Доступные флаги командной строки:

--transport: протокол транспорта (stdio, sse, streamable-http)
--services: список сервисов через запятую
--disabled-services: список сервисов для исключения (например, zcc,zdx)
--tools: список конкретных инструментов через запятую
--disabled-tools: список инструментов для исключения, поддерживает подстановки (например, zcc_*,zdx_list_devices)
--toolsets: список идентификаторов toolset’ов через запятую (например, zia_url_filtering,zpa_app_segments). Специальные значения: default (курируемый subset по умолчанию), all (все toolsets). По умолчанию загружаются все toolset’ы сервисов, которые включены. См. docs/guides/toolsets.md.
--no-entitlement-filter: Пропустить Entitlement фильтр OneAPI, который обрезает toolsets до продуктов, на которые настроенная ZSCALER_CLIENT_ID имеет доступ. Экстренный режим — фильтр нефатальный по умолчанию.
--enable-write-tools: Включить операции записи (по умолчанию отключено по соображениям безопасности)
--write-tools: Обязательный allowlist паттернов инструментов записи (например, "zpa_create_*,zpa_delete_*")
--log-tool-calls: Включить аудит‑логирование по каждому вызову инструмента (имя инструмента, замаскированные аргументы, продолжительность, итог)
--debug: Включить отладочный логгинг
--host: Хост для HTTP‑транспортов (по умолчанию 127.0.0.1)
--port: Порт для HTTP‑транспортов (по умолчанию 8000)
--user-agent-comment: Дополнительный текст в User-Agent
--generate-auth-token: Сгенерировать фрагмент токена аутентификации клиента и выйти
--list-tools: Перечислить все доступные инструменты и выйти
--version: Показать версию сервера и выйти

Поддерживаемые агенты

Zscaler API Credentials & Authentication

Сервер Zscaler Integrations MCP Server использует исключительно OneAPI‑аутентификацию. Единая пара учетных данных аутентифицирует сервер на все продукты Zscaler (ZIA, ZPA, ZCC, ZDX, Zscaler Cellular, ZTW, ZIdentity, ZMS, Z-Insights, EASM).

Zscaler Cellular (ZCell) требует одну дополнительную учетную запись — ваш Zscaler Cellular customer ID через ZCELL_CUSTOMER_ID — отдельный от ZSCALER_CUSTOMER_ID (используется ZPA). См. таблицу переменных окружения ниже.

OneAPI Аутентификация

Требования

Создайте API Client в платформе ZIdentity
Получите clientId, clientSecret (или privateKey для JWT), customerId, и vanityDomain
Подробнее: Understanding OneAPI

Быстрая настройка

Создайте файл .env в корне проекта (или там, где запускаете MCP сервер):

# OneAPI credentials (required)
ZSCALER_CLIENT_ID=your_client_id
ZSCALER_CLIENT_SECRET=your_client_secret
ZSCALER_CUSTOMER_ID=your_customer_id
ZSCALER_VANITY_DOMAIN=your_vanity_domain

# Required only for Zscaler Cellular (ZCell)
ZCELL_CUSTOMER_ID=your_zscaler_cellular_customer_id

# Optional: only if targeting Beta tenant
ZSCALER_CLOUD=beta

⚠️ Безопасность: не добавляйте .env в контроль версий. Добавьте в .gitignore.

OneAPI переменные окружения

Переменная окружения	Требуется	Описание
ZSCALER_CLIENT_ID	Да	OneAPI client ID из консоли ZIdentity
ZSCALER_CLIENT_SECRET	Да (или ZSCALER_PRIVATE_KEY)	OneAPI client secret
ZSCALER_CUSTOMER_ID	Да (для инструментов ZPA)	Zscaler customer/tenant ID
ZCELL_CUSTOMER_ID	Да (для инструментов Zscaler Cellular)	Zscaler Cellular customer ID (отличный от ZSCALER_CUSTOMER_ID; также принимается как config key zcellCustomerId)
ZSCALER_VANITY_DOMAIN	Да	Vanity‑домeн вашей организации (например, acme)
ZSCALER_CLOUD	Нет	Облачное переопределение (beta, zscalertwo); опускать для продакшна
ZSCALER_PRIVATE_KEY	Нет	PEM‑кодированный приватный ключ для JWT‑аутентификации (используется вместо ZSCALER_CLIENT_SECRET)

Верификация

После заполнения .env запустите сервер:

zscaler-mcp

Если учетные данные действительны, сервер запустится корректно. Клиент Zscaler SDK создаётся лениво при первом вызове инструмента, поэтому недействительные или ротирующиеся учетные данные проявляют ошибку в момент вызова, а не при старте сервера.

Устойчивость к проблемам аутентификации

Симптом	Вероятная причина	Исправление
Не удалось инициализировать Zscaler SDK из-за отсутствия OneAPI учетных данных: [...]	Одна или несколько из ZSCALER_CLIENT_ID, ZSCALER_VANITY_DOMAIN, или (для ZPA) ZSCALER_CUSTOMER_ID пусты	Установите перечисленные переменные в .env или в вашем окружении
Необходимо задать Either ZSCALER_CLIENT_SECRET или ZSCALER_PRIVATE_KEY для OneAPI клиента	Отсутствуют оба материала аутентификации	Задайте один из ZSCALER_CLIENT_SECRET или ZSCALER_PRIVATE_KEY
401/403 от Zscaler API во время вызова инструмента	У клиента нет нужной области доступа к продукту, креды аннулированы	Проверьте разрешения OneAPI в ZIdentity; при необходимости обновите креды

Конфигурация MCP Server

Следующие переменные окружения управляют поведением MCP Server (аутентификация не касается):

Переменная окружения	Значение по умолчанию	Описание
ZSCALER_MCP_TRANSPORT	stdio	Транспортный протокол (stdio, sse, или streamable-http)
ZSCALER_MCP_SERVICES	""	Список сервисов через запятую (пусто = все сервисы). Значения: zcc, zdx, zia, zid, zpa, ztw
ZSCALER_MCP_TOOLS	""	Список конкретных инструментов (пусто = все инструменты)
ZSCALER_MCP_DISABLED_SERVICES	""	Исключить сервисы (e.g., zcc,zdx). Приоритет выше ZSCALER_MCP_SERVICES.
ZSCALER_MCP_DISABLED_TOOLS	""	Исключаемые инструменты. Поддерживает подстановки. Приоритет над ZSCALER_MCP_TOOLS.
ZSCALER_MCP_WRITE_ENABLED	false	Включать операции записи (true/false). При false — доступны только read-only Tools. Установите true или используйте флаг --enable-write-tools для разблокировки.
ZSCALER_MCP_WRITE_TOOLS	""	ОБЯЗАТЕЛЬНЫЙ список разрешённых инструментов записи (например, `zpa_*`). Требуется `ZSCALER_MCP_WRITE_ENABLED=true`. Если пусто — 0 инструментов записи зарегистрировано.
ZSCALER_MCP_DEBUG	false	Включить отладочный логгинг (true/false)
ZSCALER_MCP_HOST	127.0.0.1	Хост для HTTP‑транспорта
ZSCALER_MCP_PORT	8000	Порт для HTTP‑транспорта
ZSCALER_MCP_DISABLE_HOST_VALIDATION	false	Отключить валидацию Host‑header при работе на EC2/публичном IP (true/false). Можно также указать `--host 0.0.0.0`, что автоматически отключает её.
ZSCALER_MCP_ALLOWED_HOSTS	""	Разрешённые значения Host для удалённого развёртывания (например, 34.201.19.115:,localhost:). В продакшне предпочтительнее свой набор.
ZSCALER_MCP_TLS_CERTFILE	""	Путь к TLS сертификату (PEM) для HTTPS.
ZSCALER_MCP_TLS_KEYFILE	""	Путь к TLS приватному ключу (PEM) для HTTPS.
ZSCALER_MCP_TLS_KEYFILE_PASSWORD	""	Пароль к зашифрованному TLS приватному ключу (если применимо).
ZSCALER_MCP_TLS_CA_CERTS	""	Путь к CA‑сертификатам для взаимной TLS или цепочек доверия.
ZSCALER_MCP_ALLOW_HTTP	false	Разрешить plaintext HTTP на не‑локальных интерфейсах. HTTPS по умолчанию для удалённых развертываний. Включайте только если TLS терминируется на прокси.
ZSCALER_MCP_ALLOWED_SOURCE_IPS	""	Список разрешённых IP клиентов/CIDR (напр., 10.0.0.0/8,172.16.0.5). По умолчанию фильтрация по IP отключена. Установить 0.0.0.0/0, чтобы разрешить всё.
ZSCALER_MCP_CONFIRMATION_TTL	300	Время жизни HMAC‑токена в секундах. Не применяется к sealed requestState, используемому некоторыми клиентами elicitation (SDK envelope TTL, по умолчанию 600s). Нет переменной, которая пропускает само подтверждение.
ZSCALER_MCP_REQUEST_STATE_KEYS	(unset)	Общая связка ключей для SEP‑2322 requestState. JSON‑массив или запятая. Каждый ключ ≥32 байт. Требуется для многокопий HTTP‑развертываний с включённой записью — при отсутствии используется ключ на уровне процесса.
ZSCALER_MCP_DISABLE_OUTPUT_SANITIZATION	false	Отключить санитацию вывода (BiDi / нулевые символы / HTML / Markdown / кодовые суффиксы). По умолчанию включено. Отключать только для диагностики — отключение удаляет защиту от prompt‑injection.
ZSCALER_MCP_USER_AGENT_COMMENT	""	Дополнительная информация, добавляемая в комментарий User-Agent

Заголовок User-Agent

Сервер MCP автоматически добавляет в каждый запрос к Zscaler сервисам собственный заголовок User-Agent. Формат:

User-Agent: zscaler-mcp-server/<version> python/<version> <os>/<architecture>

Пример:

User-Agent: zscaler-mcp-server/0.3.1 python/3.11.8 darwin/arm64

С дополнительной пометкой:

Вы можете дополнить User-Agent дополнительной информацией (например, данные агента AI) через переменную окружения ZSCALER_MCP_USER_AGENT_COMMENT или через CLI‑флаг --user-agent-comment:

# Через окружение
export ZSCALER_MCP_USER_AGENT_COMMENT="Claude Desktop 1.2024.10.23"

# Через CLI‑флаг
zscaler-mcp --user-agent-comment "Claude Desktop 1.2024.10.23"

Это приводит к:

User-Agent: zscaler-mcp-server/0.3.1 python/3.11.8 darwin/arm64 Claude Desktop 1.2024.10.23

User-Agent помогает Zscaler идентифицировать трафик API MCP и может быть полезен для поддержки, аналитики и отладки.

Как библиотека

Вы можете использовать Zscaler Integrations MCP Server в качестве Python‑библиотеки в своих приложениях:

from zscaler_mcp.server import ZscalerMCPServer

# Создание сервера в режиме read-only (по умолчанию)
server = ZscalerMCPServer(
    debug=True,  # Опционально, включить отладку
    enabled_services={"zia", "zpa", "zdx"},  # Опционально, по умолчанию все сервисы
    enabled_tools={"zia_list_rule_labels", "zpa_list_application_segments"},  # Опционально, по умолчанию все инструменты
    disabled_services={"zcc"},  # Опционально, исключить сервисы
    disabled_tools={"zcc_*", "zdx_list_devices"},  # Опционально, исключить инструменты по имени или по wildcard
    user_agent_comment="My Custom App",  # Опционально, дополнительная информация в User-Agent
    enable_write_tools=False  # Опционально, по умолчанию False (режим read-only)
)

# Запуск со стандартным транспортом (stdio)
server.run()

# Или запуск со SSE транспортом
server.run("sse")

# Или запуск со streamable-http транспортом
server.run("streamable-http")

# Или запуск со streamable-http транспортом на произвольном хосте/порте
server.run("streamable-http", host="0.0.0.0", port=8080)

Пример с включёнными операциями записи:

from zscaler_mcp.server import ZscalerMCPServer

# Создание сервера с включёнными операциями записи
server = ZscalerMCPServer(
    debug=True,
    enabled_services={"zia", "zpa"},
    enable_write_tools=True  # Включить операции CREATE/UPDATE/DELETE
)

# Запуск сервера
server.run("stdio")

Доступные сервисы: zcc, zdx, zcell, zia, zid, zeasm, zins, zms, zpa, ztw

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

from zscaler_mcp.server import ZscalerMCPServer
import os

# Загрузка из переменных окружения
server = ZscalerMCPServer(
    debug=True,
    enabled_services={"zia", "zpa"}
)

# Запуск сервера
server.run("stdio")

Запуск примеров

# Запуск со стандартным выводом (stdio)
python examples/basic_usage.py

# Запуск со SSE
python examples/sse_usage.py

# Запуск со streamable-http
python examples/streamable_http_usage.py

Контейнерное использование

Сервер Zscaler Integrations MCP Server доступен как готовый образ контейнера для упрощённого развёртывания:

Использование готового образа (рекомендовано)

# Загружаем последний готовый образ
docker pull zscaler/zscaler-mcp-server:latest

# Запуск с файлом .env (рекомендовано)
docker run --rm --env-file /path/to/.env zscaler/zscaler-mcp-server:latest

# Запуск с .env и SSE транспортом
docker run --rm -p 8000:8000 --env-file /path/to/.env \
  zscaler/zscaler-mcp-server:latest --transport sse --host 0.0.0.0

# Запуск с .env и streamable-http транспортом
docker run --rm -p 8000:8000 --env-file /path/to/.env \
  zscaler/zscaler-mcp-server:latest --transport streamable-http --host 0.0.0.0

# Запуск с .env и кастомным портом
docker run --rm -p 8080:8080 --env-file /path/to/.env \
  zscaler/zscaler-mcp-server:latest --transport streamable-http --host 0.0.0.0 --port 8080

# Запуск с .env и конкретными сервисами
docker run --rm --env-file /path/to/.env \
  zscaler/zscaler-mcp-server:latest --services zia,zpa,zdx

# Использование конкретной версии образа
docker run --rm --env-file /path/to/.env \
  zscaler/zscaler-mcp-server:1.2.3

# Альтернатива: отдельные переменные окружения
docker run --rm -e ZSCALER_CLIENT_ID=your_client_id -e ZSCALER_CLIENT_SECRET=your_secret \
  -e ZSCALER_CUSTOMER_ID=your_customer_id -e ZSCALER_VANITY_DOMAIN=your_vanity_domain \
  zscaler/zscaler-mcp-server:latest

Сборка локально (разработка)

Для разработки или кастомизации можно собрать образ локально:

# Построить Docker образ
docker build -t zscaler-mcp-server .

# Запуск локально собранного образа
docker run --rm -e ZSCALER_CLIENT_ID=your_client_id -e ZSCALER_CLIENT_SECRET=your_secret \
  -e ZSCALER_CUSTOMER_ID=your_customer_id -e ZSCALER_VANITY_DOMAIN=your_vanity_domain zscaler-mcp-server

Примечание: при использовании HTTP‑транспортов в Docker всегда указывайте --host 0.0.0.0, чтобы разрешить внешние соединения к контейнеру.

Editor/Assistant Integration

Вы можете интегрировать Zscaler Integrations MCP Server с вашим редактором или AI‑помощником. Ниже примеры конфигураций для популярных клиентов MCP:

Использование `uvx` (рекомендовано)

{
  "mcpServers": {
    "zscaler-mcp-server": {
      "command": "uvx",
      "args": ["--env-file", "/absolute/path/to/.env", "zscaler-mcp"]
    }
  }
}

Примечание: опубликованный PyPI пакет называется zscaler-mcp (а не zscaler-mcp-server). При интеграции как плагина Claude Code используйте ${CLAUDE_PLUGIN_ROOT}/.env, а для расширений Gemini используйте ${extensionPath}${pathSeparator}.env.

Дополнительные параметры развёртывания

Удалённое MCP‑развертывание (EC2, VM и т. п.)

При развёртывании MCP сервера на удалённом хосте (HTTP‑соединение с клиента на другой машине):

Настройка сервера:

Установите учетные данные и настройте конфигурацию (см. разделы Installation и Environment Configuration)
Если используется Editable Install (uv pip install -e .), активируйте виртуальное окружение перед запуском — иначе может быть запущена другая версия
Используйте --host 0.0.0.0 для привязки ко всем интерфейсам. Это автоматически отключает проверку Host header (необходимо при использовании публичного IP).
Убедитесь, что фаервол разрешает входящие соединения на выбранный порт (например, 8000)

Конфигурация клиента (Claude Desktop):

Claude Desktop ожидает, что команда запуска порождает процесс. Для удалённого HTTP‑подключения используйте mcp-remote, который поддерживает заголовки аутентификации.

macOS / Linux:

{
  "mcpServers": {
    "zscaler-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://YOUR_SERVER_IP:8000/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer sk-your-api-key"
      ]
    }
  }
}

Windows:

На Windows пути с пробелами ломают npx при вызове напрямую. Оборачивайте вызов в cmd /c:

{
  "mcpServers": {
    "zscaler-mcp-server": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "http://YOUR_SERVER_IP:8000/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer sk-your-api-key"
      ]
    }
  }
}

--allow-http: требуется при подключении к HTTP‑концовкам за пределами локального хоста. mcp-remote по умолчанию требует HTTPS для не‑локальных URL. Пропускать нельзя.

Использование режима аутентификации Zscaler (Basic Auth):

Замените заг

Подтверждение поддержки

📄 Содержание

📺 Обзор

🔒 Безопасность и разрешения

Режим только для чтения (по умолчанию — всегда доступен)

Режим записи (Explicit Opt-In — Allowlist ОБЯЗАТЕЛЕН)

Allowlist инструментов для записи (ОБЯЗАТЕЛЬНО)

Философия дизайна инструментов

✅ Хорошо (Глагольная основа — текущий дизайн)

Ответы: API‑запись в неизменном виде

Уровни безопасности

Toolsets

OneAPI Entitlement Filter

Криптографическое подтверждение для разрушительных действий

Контроль на уровне сети (HTTP только)

Поддержка HTTPS/TLS

Контроль доступа по IP источника

Безопасность .env файл предупреждение

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

Лучшие практики

🔐 MCP Client Authentication

Режимы аутентификации

Быстрый старт

Как это работает

Конфигурация по режимам

API Key

JWT (External IdP через JWKS)

Zscaler OneAPI Credentials

По умолчанию аутентификация

OAuth 2.1 (oidc режим)

Поддерживаемые инструменты

Установка и настройка

Требования

Конфигурация окружения

Установка

Установка через VS Code (быстрая настройка)

Установка с использованием uv (рекомендуется)

Установка из исходников через uv (разработка)

Установка из исходников через pip

Установка через make (для удобства)

Использование

Командная строка

Конфигурация сервиса

1. Аргументы командной строки (наивысший приоритет)

2. Переменная окружения (резервный вариант)

3. Поведение по умолчанию (все сервисы)

Исключение сервисов и инструментов

Дополнительные параметры командной строки

Поддерживаемые агенты

Zscaler API Credentials & Authentication

OneAPI Аутентификация

Требования

Быстрая настройка

OneAPI переменные окружения

Верификация

Устойчивость к проблемам аутентификации

Конфигурация MCP Server

Заголовок User-Agent

Как библиотека

Запуск примеров

Контейнерное использование

Использование готового образа (рекомендовано)

Сборка локально (разработка)

Editor/Assistant Integration

Использование uvx (рекомендовано)

Дополнительные параметры развёртывания

Удалённое MCP‑развертывание (EC2, VM и т. п.)

Безопасность `.env` файл предупреждение

OAuth 2.1 (`oidc` режим)

Использование `uvx` (рекомендовано)