关于 Zscaler Zero Trust Exchange
Zscaler Zero Trust Exchange MCP 服务让 AI Agent 通过 400 多个工具访问 Zscaler 的 ZPA、ZIA、ZDX、ZCC 等服务。默认以只读模式运行，写操作需显式开启并配置允许列表，目前处于公开预览阶段。
主要功能
- 01覆盖 ZPA、ZIA、ZDX、ZCC 等多个服务
- 02默认只读模式
- 03写操作需显式开启并配置允许列表
- 04支持 JMESPath 查询过滤返回结果
- 05可按服务选择工具集
适用场景
- 01让 AI Agent 查询 ZPA 应用分段或分段组
- 02在变更前以只读方式核查 ZIA 防火墙规则
- 03通过 Agent 按条件筛选 ZCC 设备列表
MCP 相关
该项目是一个 MCP 服务，向 MCP 客户端暴露 Zscaler 各服务的工具，并按照权限设置控制可用工具。
配置
本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。
uvx zscaler-mcpZSCALER_CLIENT_ID密钥Zscaler OneAPI Client ID from ZIdentity console.ZSCALER_CLIENT_SECRET密钥Zscaler OneAPI Client Secret from ZIdentity console.ZSCALER_CUSTOMER_IDZscaler Customer ID from ZIdentity console.ZSCALER_VANITY_DOMAINZscaler vanity domain (e.g. mycompany.zscloud.net).本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。
工具
254收录的工具列表 · 更新于 2 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| query | any | 否 | 可选的 JMESPath 表达式，在 API 调用后应用于结果，以便在客户端进行筛选和投影。示例："[?enabled==`true`]"、"[*].{name: name, id: id}"、"length(@)"。省略则返回完整记录。重要：字段名称是返回记录中的键，通常为 snake_case（`custom_category`），即使 Zscaler API 文档中使用 camelCase（`customCategory`）也是如此——猜错拼写会得到一个看似真实的空列表。如果尚未查看过此工具返回的记录，请先不带 `query` 调用一次，并从响应中读取键名。 |
| org_id | string | 是 |
详细介绍
zscaler-mcp-server 是一个模型上下文协议（MCP）服务，可将 AI Agent 连接到 Zscaler Zero Trust Exchange 平台。出于安全考虑，服务默认以只读模式运行；如需启用写入操作，必须明确选择加入。
支持免责声明
-> 免责声明： 使用此提供方之前，请参阅我们的一般支持声明。有关常见问题的指引，也可参阅我们的故障排除指南。
重要
🚧 公开预览版：此项目目前处于公开预览阶段，仍在积极开发中。稳定版 1.0 发布之前，功能可能会发生变化。我们鼓励大家探索和测试，但请避免将其部署到生产环境。欢迎通过 GitHub Issues 提供反馈，帮助完善最终版本。
📄 目录
- 📺 概览
- 🔒 安全与权限
- 🔐 MCP 客户端身份验证
- 支持的工具
- 安装与设置
- 使用方法
- Zscaler API 凭据与身份验证
- 作为库使用
- 容器使用
- 编辑器／助手集成
- 其他部署选项
- 将 MCP 服务与 Agent 搭配使用
- 平台集成
- 故障排查
- 许可证
📺 概览
Zscaler Integrations MCP Server 为你的 Agent 提供上下文。可以尝试以下提示词：
- “列出我的 ZPA 应用程序分段”
- “列出我的 ZPA 分段组”
- “列出我的 ZIA 规则标签”
警告
🔒 默认只读：出于安全考虑，此 MCP 服务默认以只读模式运行。仅提供
list_*和get_*操作。若要启用可创建、更新或删除 Zscaler 资源的工具，必须使用--enable-write-tools标志或设置ZSCALER_MCP_WRITE_ENABLED=true，明确启用写入模式。详情请参阅安全与权限部分。
提示
编写有效的提示词：此服务在多个 Zscaler 服务中提供 402 个工具。大多数 MCP 客户端（Claude Desktop、Cursor 等）会使用延迟加载工具的方式，并根据你的提示词搜索相关工具。为获得最佳效果，请在提示词中明确指定服务和操作：
- 效果好：“列出我的 ZPA 应用程序分段”——直接定位正确的服务和工具
- 效果好：“显示 ZIA 防火墙规则”——明确指定服务（
zia）和操作（list）- 效果较差：“给我看看我的设备”——含义模糊；多个服务都提供与设备相关的工具
当某项服务被禁用时，其工具会从服务中完全移除。不过，AI Agent 仍可能尝试在其他服务中查找相关工具。如果结果不符合预期，请在提示词中补充具体的服务名称（例如
zpa、zia、zdx、zcc、zcell、zms）。
🔒 安全与权限
Zscaler MCP Server 采用安全优先的设计，提供精细的权限控制和安全的默认设置：
只读模式（默认 — 始终可用）
默认情况下，服务以只读模式运行，仅公开用于列出或检索信息的工具：
- ✅ 始终可用 — 只读工具由服务注册
- ✅ 可供 AI Agent 自主安全使用
- ✅ 不存在意外修改或删除资源的风险
- ✅ 所有
list_*和get_*操作均可用（110 多个只读工具） - ❌ 默认禁用所有
create_*、update_*和delete_*操作 - 💡 注意：你可能需要在 AI Agent 的 UI 设置中启用只读工具
# Read-only mode (default - safe)
zscaler-mcp
服务以只读模式启动时，你会看到：
🔒 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
💡 服务始终会注册只读工具，不受任何标志影响。你无需在服务端启用它们。注意：你的 AI Agent UI（例如 Claude Desktop）可能要求你在使用前启用各个工具。
写入模式（明确选择启用 — 必须提供允许列表）
若要启用可创建、修改或删除 Zscaler 资源的工具，必须同时提供两个标志：
- ✅
--enable-write-tools— 全局解锁写入操作 - ✅
--write-tools "pattern"— 必须明确指定允许列表
🔐 安全性：必须提供允许列表 — 如果设置了
--enable-write-tools，却未设置--write-tools，则不会注册任何写入工具。这可确保你明确选择要启用的写入操作。
# ❌ WRONG: This will NOT enable any write tools (allowlist missing)
zscaler-mcp --enable-write-tools
# ✅ CORRECT: Explicit allowlist required
zscaler-mcp --enable-write-tools --write-tools "zpa_create_*,zpa_delete_*"
尝试在未提供允许列表的情况下启用写入模式时：
⚠️ 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'
写入工具允许列表（必须）
允许列表提供两层安全保护：
- ✅ 第一道关卡：必须设置
--enable-write-tools（全局解锁） - ✅ 第二道关卡：由明确指定的允许列表决定要注册哪些写入工具（必须）
允许列表示例：
# Enable ONLY specific write tools with wildcards
zscaler-mcp --enable-write-tools --write-tools "zpa_create_*,zpa_delete_*"
# Enable specific tools without wildcards
zscaler-mcp --enable-write-tools --write-tools "zpa_create_application_segment,zia_create_rule_label"
# Enable all ZPA write operations (but no 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— 精确匹配（不使用通配符）
使用有效的允许列表时，你会看到：
⚠️ 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, safe to allow-list
zpa_get_application_segment ← Read-only, safe to allow-list
zpa_create_application_segment ← Write operation, requires --enable-write-tools
zpa_update_application_segment ← Write operation, requires --enable-write-tools
zpa_delete_application_segment ← Destructive, requires --enable-write-tools
这种设计可让 AI 助手（Claude、Cursor、GitHub Copilot）：
- 将只读工具加入允许列表，以便自主探索
- 要求用户明确确认写入操作
- 通过工具名称清楚了解每个工具的用途
响应：原样返回的 API 记录
只读工具会原样返回 Zscaler API 记录。服务不会删减、重命名或重新声明资源属性 — 属性集合由 API 决定，因此 Zscaler 日后新增的字段无需升级服务即可传给你。
为缩小响应内容，你可以控制返回内容，而非由服务猜测。可通过以下两种方式控制：
-
--toolsets— 仅加载所需的工具子集，以缩小工具目录（参见 工具集）。 -
query— 每个列表工具都接受可选的 JMESPath 表达式，用于筛选结果，让 Agent 仅提取所需内容：zcc_list_devices(query="[*].{user: user, policy: policyName}") # just those two fields zcc_list_devices(query="[?registrationState=='Quarantined']") # just quarantined devices zcc_list_devices(query="length(@)") # just the count
字段名称与 Zscaler API 返回的完全一致。不指定 query 即可获取完整记录。
安全层
服务采用多层安全防护（纵深防御）。前九层适用于所有传输方式，包括 stdio——它们决定开放哪些工具，以及如何确认高风险调用。其余仅适用于 HTTP 的安全层（TLS、主机标头验证、源 IP 访问控制列表、MCP 客户端身份验证）将在下文的网络级控制（仅限 HTTP）部分介绍。
- 始终启用只读工具：始终提供安全的
list_*和get_*操作（254 个工具）。 - 默认禁用写入模式：除非通过
--enable-write-tools明确启用，否则写入工具处于禁用状态。 - 强制允许列表：写入操作需要通过
--write-tools明确指定允许列表（支持通配符）。 - OneAPI 权限过滤器：启动时，会静默移除 OneAPI 凭据无法调用的产品对应的工具集（请参阅下文的 OneAPI 权限过滤器）。
- 工具集选择：可选地将已注册的工具范围缩小到特定子集（例如
--toolsets zia_url_filtering,zpa_app_segments）。请参阅下文的工具集部分。 - 基于动词的工具命名：每个工具都清楚标明其用途（
list、get、create、update、delete）。 - 工具元数据注解：所有工具都标注了
readOnlyHint或destructiveHint，供 AI Agent 框架使用。 - AI Agent 确认：所有标记为
destructiveHint=True的写入工具都会在 AI 助手中触发权限对话框。 - DELETE 操作需人工确认：删除操作必须通过由服务发起的确认流程。在支持 MCP elicitation 的客户端（Claude Desktop、Cursor）上，服务会请求客户端提示人工确认，答案会作为协议字段返回——因此，被劫持的 Agent 无法伪造批准；若往返流程失败，则默认拒绝。对于不具备此能力的客户端，则回退到加密确认令牌（HMAC-SHA256、单次使用、5 分钟 TTL，并绑定具体工具和参数），可防止批准被用于其他资源、重放或重复使用——但它本身并不能防御提示词注入，因为被劫持的 Agent 会收到并能够兑换该令牌。此回退方案也仅限单进程使用；支持 elicitation 的客户端不受影响。完整分析请参阅MCP 协议安全态势——确认威胁模型。
- 环境变量控制：可以集中管理
ZSCALER_MCP_WRITE_ENABLED、ZSCALER_MCP_WRITE_TOOLS、ZSCALER_MCP_TOOLSETS、ZSCALER_MCP_DISABLE_ENTITLEMENT_FILTER和各禁用列表，无需更改代码。 - 输出净化：每个工具结果中的所有字符串在传递给 Agent 前都会经过三阶段净化——剥离不可见字符和控制字符（双向覆盖字符、零宽字符、BOM、软连字符），移除原始 HTML 和 HTML 注释（通过
bleach），对 Markdown 链接/图片语法进行中和处理，防止嵌入的 URL 被偷偷传递给 Agent，并将包含角色冒充令牌（system、assistant、tool、ignore等）的 Markdown 代码围栏信息字符串折叠为中性的text标签。这可以防御攻击者或疏忽的管理员嵌入到可编辑 Zscaler 资源（规则说明、位置名称、标签说明等）中的提示词注入载荷。默认启用。可通过ZSCALER_MCP_DISABLE_OUTPUT_SANITIZATION=true选择退出（仅用于诊断）。 - 审计日志记录：设置
--log-tool-calls/ZSCALER_MCP_LOG_TOOL_CALLS=true后，每次工具调用都会记录其参数（敏感值会被隐去）、耗时和结果摘要。
这种多层防护方法可确保即使某一项安全控制被绕过，其他措施仍能防止未授权操作。上述第 1–12 层同样适用于 stdio、sse 和 streamable-http。
工具集
工具分为 63 个命名的工具集，因此你可以只加载 Agent 实际需要的部分（例如，加载 zia_url_filtering（5 个工具），而不是加载所有服务的所有工具（402 个））。工具集可降低 Agent 的上下文成本，并提高工具选择的准确性。
# Load just two slices
zscaler-mcp --toolsets zia_url_filtering,zpa_app_segments
# Or use the curated default-on subset
zscaler-mcp --toolsets default
# Or load every registered toolset explicitly
zscaler-mcp --toolsets all
# Equivalent via environment variable
export ZSCALER_MCP_TOOLSETS="zia_url_filtering,zpa_app_segments"
未指定 --toolsets 时，将加载所有已启用服务对应的工具集（保留历史默认行为）。
Agent 还可以在运行时通过始终可用的 zscaler_list_toolsets、zscaler_get_toolset_tools 和 zscaler_enable_toolset 工具启用其他工具集。
如需查看完整目录（涵盖所有服务中的 29 个工具集）、筛选优先级规则、各工具集的 Agent 指南和完整参考，请参阅 docs/guides/toolsets.md。
OneAPI 权限筛选器
工具集选择确定后，服务会从为你的 ZSCALER_CLIENT_ID 签发的 OneAPI bearer token 中读取产品权限，并静默移除凭据无权调用的产品对应的工具集。如果你的 OneAPI 客户端仅拥有 ZIA 和 ZPA 权限，那么在启动时，所有 zdx_* / zcc_* / ztw_* / zid_* / zeasm_* / zins_* / zms_* 工具集都会被筛除——即使指定了 --toolsets all 也是如此。
这样可避免 Agent 发现那些首次调用只会返回 401 Unauthorized 的工具。此筛选器适用于所有传输方式，包括 stdio。
筛选器运行时，启动时会显示一条日志，例如：
entitlement filter applied: entitled services=['zia', 'zpa'], kept 12 toolset(s), removed 17 toolset(s)
此筛选器不会导致启动失败。如果缺少凭据、无法访问 token 端点、无法解码 token，或者 token 中没有可识别的产品权限，服务会记录一条 WARN 日志，并按用户选择的工具集正常启动，不做更改。
如需绕过此筛选器（例如，在诊断特殊 token 格式时）：
zscaler-mcp --no-entitlement-filter
# or
export ZSCALER_MCP_DISABLE_ENTITLEMENT_FILTER=true
只会考虑产品权限，不考虑角色名称。服务会将各项操作的权限检查交由实时 API 执行；权限筛选器只确保我们不会为客户端完全无权访问的产品展示工具。
危险操作的加密确认
删除操作不会在首次调用时执行。具体处理方式取决于客户端：
- 支持 MCP elicitation 的客户端会显示一个交互式提示词，列出资源名称，并由人工作答。AI Agent 不会处理此批准。
- 其他所有客户端都会收到一个加密确认令牌（HMAC-SHA256），必须将其传回才能继续操作。该令牌绑定到特定操作及其参数，只能使用一次，并会在 5 分钟后过期，因此无法伪造、重放，也不能用于其他资源。
无法关闭此机制。 删除操作对正在使用的租户不可逆，因此服务没有提供可跳过此门槛的标志或环境变量。如果你不希望 Agent 删除任何内容，请勿将删除工具加入允许列表：写入工具默认关闭，且 --write-tools 需要明确指定模式（请参阅写入模式）。
网络级控制（仅 HTTP）
接下来的四个小节——TLS、源 IP 允许列表、主机标头验证和 .env 明文密钥扫描器——仅适用于 HTTP 传输方式（sse、streamable-http）。它们用于控制谁能通过网络访问服务。这些控制与上文安全层中列出的工具级控制相互独立（只读模式、写入允许列表、工具集、权限筛选器、HMAC 确认）；后者适用于所有传输方式，包括 stdio。
相应的 MCP 客户端身份验证（Bearer / Basic / OAuth 2.1）是第五个网络级安全层，详见下文的 MCP 客户端身份验证一节。
HTTPS/TLS 支持
默认情况下，非 localhost 部署必须使用 HTTPS。如果未配置 TLS 证书，服务器将拒绝在非 localhost 接口上启动，除非你显式设置 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
# Optional: private key password and CA bundle
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 访问控制
你可以使用 ZSCALER_MCP_ALLOWED_SOURCE_IPS 限制允许连接的客户端 IP。未设置时（默认情况），源 IP 过滤处于禁用状态，并交由上游控制措施（防火墙规则、AWS Security Groups 等）处理。
# Allow only specific IPs/subnets
ZSCALER_MCP_ALLOWED_SOURCE_IPS=10.0.0.0/8,172.16.0.5
# Allow all (effectively disable — same as not setting the variable)
ZSCALER_MCP_ALLOWED_SOURCE_IPS=0.0.0.0/0
支持单个 IPv4/IPv6 地址、CIDR 表示法和通配符 0.0.0.0/0。健康检查端点（/health、/healthz、/ready）不受限制，以确保负载均衡器探测正常运行。不允许的 IP 发出的请求将收到 403 Forbidden。
.env 文件安全警告
使用 HTTP 传输方式启动时，服务器会自动扫描工作目录中的任何 .env 文件，查找明文机密信息（值中包含 SECRET、PASSWORD、KEY 或 TOKEN）。如果检测到此类信息，服务器会记录安全警告，建议改用机密管理器或环境变量。
安全态势横幅
启动时，服务器会记录一个汇总的安全态势横幅，概述当前启用的安全配置，包括传输模式、主机验证状态、身份验证模式、TLS 状态以及任何活动警告。这样可以轻松快速地核查安全状态。
关键安全原则：
- 不存在“启用所有写入工具”的后门——允许列表是强制要求
- AI Agent 必须在执行任何写入操作（
destructiveHint）前请求许可 - 每项破坏性操作都必须通过 AI Agent 的权限框架获得用户明确批准
- 破坏性操作的确认信息会以加密方式绑定，防止通过提示词注入绕过
最佳实践
- 默认只读：安全操作无需配置，始终可使用只读工具
- 强制允许列表：启用写入模式时，始终提供明确的
--write-tools允许列表 - 开发/测试：使用范围较窄的允许列表（例如，
--write-tools "zpa_create_application_segment"） - 生产环境/Agent：对于执行自主操作的 AI Agent，保持服务器处于只读模式（默认设置）
- CI/CD：除非同时设置
ZSCALER_MCP_WRITE_TOOLS允许列表，否则绝不设置ZSCALER_MCP_WRITE_ENABLED=true - 最小权限：针对你的使用场景，使用范围尽可能窄的允许列表模式
- 通配符用法：使用通配符进行服务级控制（例如，
zpa_create_*）或操作级控制（例如，*_create_*） - 审计审查：定期审查允许列表中的写入工具，并移除不必要的工具
- 明确的提示词：借助 402 个工具和延迟加载机制，AI Agent 会根据相关性将提示词与工具匹配。使用特定服务的提示词（例如，“列出 ZPA 网段”，而不是*“显示我的网段”*），以便准确选择工具
🔐 MCP 客户端身份验证
📖 完整文档：身份验证与部署指南
通过 HTTP（sse 或 streamable-http 传输方式）运行 MCP 服务时，你可以启用身份验证，以控制谁可以连接到服务器。这与 Zscaler API 凭据身份验证相互独立；后者控制服务器如何向 Zscaler API 进行身份验证。
对于 HTTP 传输方式，当存在与身份验证相关的环境变量时，服务器会自动检测并启用身份验证。对于 stdio 传输方式，身份验证不适用（操作系统的进程隔离可提供安全保障）。
认证模式
服务器支持四种认证模式，通过环境变量进行配置：
| 模式 | 描述 | 适用场景 |
|---|---|---|
api-key | 简单的共享密钥——客户端发送 Authorization: Bearer <key> | 快速设置、内部环境、开发 |
jwt | 通过 JWKS 使用外部身份提供商——使用公钥在本地验证令牌 | 企业 SSO、多租户部署（Auth0、Okta、Azure AD、Keycloak、AWS Cognito、PingOne、Google） |
zscaler | Zscaler OneAPI 凭据验证——客户端通过 Basic Auth 发送 client_id:client_secret | 已在使用 Zscaler API 凭据的环境 |
oidc | 基于自有 IdP 的 OAuth 2.1——服务器是 OAuth 2.0 受保护资源（RFC 9728），客户端直接向 IdP 进行认证 | 面向人工操作员的浏览器登录、任何 OIDC 提供商 |
快速开始
在 .env 文件中设置以下环境变量以启用认证：
# Enable authentication
ZSCALER_MCP_AUTH_ENABLED=true
ZSCALER_MCP_AUTH_MODE=api-key
# For api-key mode: set a shared secret
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 客户端认证）：由
ZSCALER_MCP_AUTH_*变量控制——验证传入请求 - 第 2 层（Zscaler API 认证）：由
ZSCALER_CLIENT_ID、ZSCALER_CLIENT_SECRET等控制——向 Zscaler API 验证服务器身份
这两层完全独立。你可以启用其中一层、两层，或者都不启用。
按模式配置
API 密钥
ZSCALER_MCP_AUTH_ENABLED=true
ZSCALER_MCP_AUTH_MODE=api-key
ZSCALER_MCP_AUTH_API_KEY=sk-your-secret-key-here
JWT（通过 JWKS 使用外部 IdP）
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 (default: RS256,ES256)
Zscaler OneAPI 凭据
ZSCALER_MCP_AUTH_ENABLED=true
ZSCALER_MCP_AUTH_MODE=zscaler
# Uses ZSCALER_VANITY_DOMAIN and ZSCALER_CLOUD from your existing config
客户端使用 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 mode）
oidc mode 会将服务设为 OAuth 2.0 受保护资源（RFC 9728）。服务会发布 /.well-known/oauth-protected-resource，其中注明你的身份提供方；客户端读取该信息后，直接向身份提供方发起 OAuth 流程，并提交获取的令牌。服务唯一要做的就是根据身份提供方发布的公钥验证令牌签名。
整个配置只需通过环境变量完成，无需修改代码或安装额外软件包：
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
说明：
- 无需客户端密钥。 验证签名需要的是身份提供方的公钥，而不是我们的凭据。即使设置了
OIDCPROXY_CLIENT_SECRET，也会被忽略。 OIDCPROXY_BASE_URL是此服务的公开 URL，客户端会将其用作资源标识符；它不是身份提供方的 URL。OIDCPROXY_AUDIENCE默认值为OIDCPROXY_CLIENT_ID。Entra ID 会将客户端 ID 放入aud；Auth0 使用 API 标识符。- 服务启动时会从身份提供方的发现文档读取 issuer 和 JWKS URI，因此它们始终与身份提供方实际用于签名的值一致。
- 服务不提供
/authorize、/token或/register；客户端需要使用身份提供方颁发的客户端 ID，且无法自行注册。 - 适用于所有符合 OIDC 标准的提供方（Auth0、Okta、Microsoft Entra ID、Keycloak、Google、AWS Cognito、PingOne）。
- 其他所有安全层（TLS、源 IP ACL、主机验证）仍保持启用状态。
身份提供方要求： 注册一个应用，并配置客户端所用的回调 URL（mcp-remote 使用 http://localhost:3334/oauth/callback，且端口固定）；还需配置与 OIDCPROXY_AUDIENCE 匹配的 API／资源标识符。
📖 详细设置说明——包括 Microsoft Entra ID 分步指南、特定身份提供方的 JWKS 配置、Docker 部署示例、Claude/Cursor/VS Code 的客户端配置以及故障排除——请参阅身份验证与部署指南。
支持的工具
Zscaler Integrations MCP Server 为所有主要 Zscaler 服务提供 402 个工具：
| 服务 | 描述 | 工具 |
|---|---|---|
| ZIA | Zscaler Internet Access — 安全策略 | 166 个读写工具 |
| ZPA | Zscaler Private Access — 应用访问 | 109 个读写工具 |
| ZDX | Zscaler Digital Experience — 监控与分析 | 31 个读写工具 |
| ZCell | Zscaler Cellular — SIM 清单、使用情况分析与异常策略 | 20 个只读工具 |
| ZMS | Zscaler Microsegmentation — Agent、资源、策略 | 20 个只读工具 |
| ZTW | Zscaler Workload Segmentation | 19 个读写工具 |
| Z-Insights | Z-Insights 分析 — Web 流量、网络安全事件、影子 IT | 16 个只读工具 |
| ZIdentity | ZIdentity — 身份与访问管理 | 10 个只读工具 |
| EASM | 外部攻击面管理 | 7 个只读工具 |
| ZCC | Zscaler Client Connector — 设备管理 | 4 个只读工具 |
注意： 所有写入操作都需要
--enable-write-tools标志和明确指定的--write-tools允许列表。详情请参阅安全与权限部分。
安装与设置
先决条件
- Python 3.11 或更高版本
uv或 pip- Zscaler API 凭据（见下文）
环境配置
复制示例环境文件并配置凭据：
cp .env.example .env
然后编辑 .env，填入 Zscaler API 凭据：
必需配置（OneAPI）：
ZSCALER_CLIENT_ID：Zscaler OAuth 客户端 IDZSCALER_CLIENT_SECRET：Zscaler OAuth 客户端密钥ZSCALER_CUSTOMER_ID：Zscaler 客户 IDZSCALER_VANITY_DOMAIN：Zscaler 专属域名
可选配置：
ZSCALER_CLOUD：（可选）Zscaler 云环境（例如，beta）——仅与 Beta 租户交互时必需。ZSCALER_PRIVATE_KEY：（可选）采用 PEM 编码的私钥，用于基于 JWT 的 OneAPI 身份验证，可替代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。请参阅远程 MCP 部署。
使用 pip 从源代码安装
pip install -e .
使用 make 安装（便捷方式）
make install-dev
提示
如果找不到
zscaler-mcp-server，请更新 shell PATH。
有关通过代码编辑器/助手安装的信息，请参阅下文的将 MCP 服务与 Agent 配合使用部分。
使用方法
说明
默认安全模式：以下所有示例默认以只读模式运行（仅执行
list_*和get_*操作）。要启用写入操作（create_*、update_*、delete_*），请在任一命令中添加--enable-write-tools标志，或在环境中设置ZSCALER_MCP_WRITE_ENABLED=true。
命令行
使用默认设置运行服务（stdio 传输、只读模式）：
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 Server 支持多种方式指定要启用的服务：
1. 命令行参数（优先级最高）
使用逗号分隔的列表指定服务：
# Enable specific services
zscaler-mcp --services zia,zpa,zdx
# Enable only one service
zscaler-mcp --services zia
2. 环境变量（回退方式）
设置 ZSCALER_MCP_SERVICES 环境变量：
# Export environment variable
export ZSCALER_MCP_SERVICES=zia,zpa,zdx
zscaler-mcp
# Or set inline
ZSCALER_MCP_SERVICES=zia,zpa,zdx zscaler-mcp
3. 默认行为（所有服务）
如果未通过命令行或环境变量指定服务，则默认启用所有可用服务。
服务优先级顺序：
- 命令行
--services参数（优先级最高） ZSCALER_MCP_SERVICES环境变量（备用）- 所有服务（未指定时的默认值）
排除服务和工具
如果希望保留大部分工具，同时排除少数工具，请使用 --disabled-tools 或 --disabled-services，而不是逐一列出要包含的工具。
这两个标志都支持通过 fnmatch 模式使用通配符。
# Exclude a single tool
zscaler-mcp --disabled-tools zia_list_devices
# Exclude all tools from a service prefix
zscaler-mcp --disabled-tools "zcc_*"
# Exclude multiple patterns
zscaler-mcp --disabled-tools "zcc_*,zdx_list_devices"
# Exclude entire services
zscaler-mcp --disabled-services zcc,zdx
# Combine: keep all services but exclude specific tools
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（包含列表）。同时匹配包含列表和排除列表的工具将被排除。
其他命令行选项
# Enable write operations (create, update, delete)
zscaler-mcp --enable-write-tools
# Enable debug logging
zscaler-mcp --debug
# Combine multiple options
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：要启用的工具集 ID，以逗号分隔（例如：zia_url_filtering,zpa_app_segments）。特殊值：default（精心挑选的默认启用子集）、all（所有工具集）。未指定时，将加载所有已启用服务对应的工具集。参见 docs/guides/toolsets.md。--no-entitlement-filter：跳过 OneAPI 权限过滤器，该过滤器会将工具集限制为已配置的ZSCALER_CLIENT_ID有权使用的产品。仅用于紧急情况的覆盖选项——默认情况下，此过滤器不会导致致命错误。--enable-write-tools：启用写入操作（出于安全考虑，默认禁用）--write-tools：写入工具模式的强制允许列表（例如："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：显示服务版本并退出
支持的 Agent
Zscaler API 凭据与身份验证
Zscaler Integrations MCP Server 仅使用 OneAPI 身份验证。一组凭据即可让服务通过身份验证，访问所有 Zscaler 产品（ZIA、ZPA、ZCC、ZDX、Zscaler Cellular、ZTW、ZIdentity、ZMS、Z-Insights、EASM）。
Zscaler Cellular（ZCell） 需要一个额外的凭据——通过
ZCELL_CUSTOMER_ID提供 Zscaler Cellular 客户 ID。该 ID 与ZSCALER_CUSTOMER_ID（用于 ZPA）不同。请参阅下方的环境变量表。
OneAPI 身份验证
前提条件
- 在 ZIdentity platform 中创建 API 客户端。
- 获取
clientId、clientSecret（或用于 JWT 的privateKey）、customerId和vanityDomain。 - 了解更多：了解 OneAPI。
快速设置
在项目根目录（或启动 MCP 服务的位置）创建 .env 文件：
# 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) tools
ZCELL_CUSTOMER_ID=your_zscaler_cellular_customer_id
# Optional: only required when targeting the Beta tenant
ZSCALER_CLOUD=beta
⚠️ 安全提示：不要将 .env 提交到源代码管理中。请将其添加到 .gitignore。
OneAPI 环境变量
| 环境变量 | 必填 | 描述 |
|---|---|---|
ZSCALER_CLIENT_ID | 是 | ZIdentity 控制台中的 OneAPI 客户端 ID |
ZSCALER_CLIENT_SECRET | 是（或 ZSCALER_PRIVATE_KEY） | OneAPI 客户端密钥 |
ZSCALER_CUSTOMER_ID | 是（用于 ZPA 工具） | Zscaler 客户/租户 ID |
ZCELL_CUSTOMER_ID | 是（用于 Zscaler Cellular 工具） | Zscaler Cellular 客户 ID（不同于 ZSCALER_CUSTOMER_ID；也可作为 zcellCustomerId 配置键使用） |
ZSCALER_VANITY_DOMAIN | 是 | 组织的自定义域名（例如 acme） |
ZSCALER_CLOUD | 否 | 云环境覆盖值（例如 beta、zscalertwo）；生产环境请省略 |
ZSCALER_PRIVATE_KEY | 否 | PEM 编码的私钥，用于 JWT 身份验证（替代 ZSCALER_CLIENT_SECRET） |
验证
在填好 .env 后，启动服务：
zscaler-mcp
如果凭据有效，服务会正常启动。Zscaler SDK 客户端会在首次调用工具时延迟创建，因此缺失或轮换中的凭据会在调用时显示清晰的错误消息，而不会阻止服务启动。
身份验证故障排查
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
Zscaler SDK failed to initialize due to missing OneAPI credentials: [...] | ZSCALER_CLIENT_ID、ZSCALER_VANITY_DOMAIN 中有一项或多项未设置或为空；用于 ZPA 时，ZSCALER_CUSTOMER_ID 也可能未设置或为空。 | 在 .env 或 shell 中设置列出的环境变量。 |
You must provide either ZSCALER_CLIENT_SECRET or ZSCALER_PRIVATE_KEY for the OneAPI client. | 两种身份验证凭据都未提供。 | 设置 ZSCALER_CLIENT_SECRET 或 ZSCALER_PRIVATE_KEY。 |
| 调用工具时，Zscaler API 返回 401/403 | API 客户端缺少该产品所需的范围，或凭据已被撤销。 | 在 ZIdentity 控制台中检查 OneAPI 客户端的权限；必要时轮换凭据。 |
MCP 服务配置
以下环境变量用于控制 MCP 服务行为（而非身份验证）：
| 环境变量 | 默认值 | 说明 |
|---|---|---|
ZSCALER_MCP_TRANSPORT | stdio | 使用的传输协议（stdio、sse 或 streamable-http） |
ZSCALER_MCP_SERVICES | "" | 要启用的服务列表，以逗号分隔（空值 = 所有服务）。支持的值：zcc、zdx、zia、zid、zpa、ztw |
ZSCALER_MCP_TOOLS | "" | 要启用的特定工具列表，以逗号分隔（空值 = 所有工具） |
ZSCALER_MCP_DISABLED_SERVICES | "" | 要排除的服务列表，以逗号分隔（例如，zcc,zdx）。优先级高于 ZSCALER_MCP_SERVICES。 |
ZSCALER_MCP_DISABLED_TOOLS | "" | 要排除的工具列表，以逗号分隔。支持通配符（例如，zcc_*,zia_list_devices）。优先级高于 ZSCALER_MCP_TOOLS。 |
ZSCALER_MCP_WRITE_ENABLED | false | 启用写入操作（true/false）。设为 false 时，仅提供只读工具。设为 true 或使用 --enable-write-tools 标志可解锁写入模式。 |
ZSCALER_MCP_WRITE_TOOLS | "" | 必需的可用写入工具允许列表（支持 zpa_* 等通配符）。需要设置 ZSCALER_MCP_WRITE_ENABLED=true。启用写入模式时若此项为空，则不会注册任何写入工具。 |
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 | 在 EC2/公网 IP 上公开服务时禁用 Host 标头验证（true/false）。也可使用 --host 0.0.0.0，该选项会自动禁用验证。 |
ZSCALER_MCP_ALLOWED_HOSTS | "" | 远程部署允许的 Host 值列表，以逗号分隔（例如，34.201.19.115:*,localhost:*）。生产环境中建议使用此选项，而非禁用验证。 |
ZSCALER_MCP_TLS_CERTFILE | "" | HTTPS 使用的 TLS 证书文件路径（PEM 格式）。 |
ZSCALER_MCP_TLS_KEYFILE | "" | HTTPS 使用的 TLS 私钥文件路径（PEM 格式）。 |
ZSCALER_MCP_TLS_KEYFILE_PASSWORD | "" | 加密 TLS 私钥的密码（如适用）。 |
ZSCALER_MCP_TLS_CA_CERTS | "" | 双向 TLS 或自定义 CA 链使用的 CA 证书包路径。 |
ZSCALER_MCP_ALLOW_HTTP | false | 允许在非 localhost 接口上使用明文 HTTP。默认情况下，远程部署必须使用 HTTPS。仅当 TLS 在上游终止时（反向代理、ZPA、VPN）才设为 true。 |
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 回退令牌的有效期，单位为秒。不适用于具有 elicitation 能力的客户端使用的密封 requestState（SDK 信封 TTL，默认 600s）。没有任何变量可以跳过确认本身。 |
ZSCALER_MCP_REQUEST_STATE_KEYS | （未设置） | SEP-2322 requestState 的共享密钥环。格式为 JSON 数组或逗号分隔列表；每个密钥长度须 ≥32 字节（python -c "import secrets; print(secrets.token_hex(32))"）。启用写入工具的多副本 HTTP 部署必需——未设置时使用进程级密钥，因此某个副本签发的确认无法由另一个副本验证。第一个密钥用于密封，所有密钥均可用于解封（按 [old,new] → [new,old] → [new] 的顺序轮换）。 |
ZSCALER_MCP_DISABLE_OUTPUT_SANITIZATION | false | 禁用纵深防御输出清理（剥除 BiDi / 零宽字符 / HTML / Markdown / 代码围栏）。默认启用清理；仅在诊断时设置此项——禁用后会移除一层提示词注入防御。 |
ZSCALER_MCP_USER_AGENT_COMMENT | "" | 要包含在 User-Agent 注释部分的附加信息 |
User-Agent 标头
MCP 服务会在所有发往 Zscaler 服务的 API 请求中自动添加自定义 User-Agent 标头。格式如下：
User-Agent: zscaler-mcp-server/<version> python/<python_version> <os>/<architecture>
示例：
User-Agent: zscaler-mcp-server/0.3.1 python/3.11.8 darwin/arm64
添加自定义注释：
你可以使用 ZSCALER_MCP_USER_AGENT_COMMENT 环境变量或 --user-agent-comment CLI 标志，附加其他信息（例如 AI Agent 详细信息）：
# Via environment variable
export ZSCALER_MCP_USER_AGENT_COMMENT="Claude Desktop 1.2024.10.23"
# Via CLI flag
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 识别来自 MCP 服务的 API 流量，并可用于支持、分析和调试。
作为库使用
你可以在自己的应用程序中将 Zscaler Integrations MCP Server 用作 Python 库：
from zscaler_mcp.server import ZscalerMCPServer
# Create server with read-only mode (default - safe)
server = ZscalerMCPServer(
debug=True, # Optional, enable debug logging
enabled_services={"zia", "zpa", "zdx"}, # Optional, defaults to all services
enabled_tools={"zia_list_rule_labels", "zpa_list_application_segments"}, # Optional, defaults to all tools
disabled_services={"zcc"}, # Optional, exclude entire services
disabled_tools={"zcc_*", "zdx_list_devices"}, # Optional, exclude tools by name or wildcard
user_agent_comment="My Custom App", # Optional, additional User-Agent info
enable_write_tools=False # Optional, defaults to False (read-only mode)
)
# Run with stdio transport (default)
server.run()
# Or run with SSE transport
server.run("sse")
# Or run with streamable-http transport
server.run("streamable-http")
# Or run with streamable-http transport on custom host/port
server.run("streamable-http", host="0.0.0.0", port=8080)
启用写入操作的示例：
from zscaler_mcp.server import ZscalerMCPServer
# Create server with write operations enabled
server = ZscalerMCPServer(
debug=True,
enabled_services={"zia", "zpa"},
enable_write_tools=True # Enable create/update/delete operations
)
# Run the server
server.run("stdio")
可用服务：zcc、zdx、zcell、zia、zid、zeasm、zins、zms、zpa、ztw
使用环境变量的示例：
from zscaler_mcp.server import ZscalerMCPServer
import os
# Load from environment variables
server = ZscalerMCPServer(
debug=True,
enabled_services={"zia", "zpa"}
)
# Run the server
server.run("stdio")
运行示例
# Run with stdio transport
python examples/basic_usage.py
# Run with SSE transport
python examples/sse_usage.py
# Run with streamable-http transport
python examples/streamable_http_usage.py
容器用法
Zscaler Integrations MCP Server 提供预构建的容器镜像，便于部署：
使用预构建镜像（推荐）
# Pull the latest pre-built image
docker pull zscaler/zscaler-mcp-server:latest
# Run with .env file (recommended)
docker run --rm --env-file /path/to/.env zscaler/zscaler-mcp-server:latest
# Run with .env file and SSE transport
docker run --rm -p 8000:8000 --env-file /path/to/.env \
zscaler/zscaler-mcp-server:latest --transport sse --host 0.0.0.0
# Run with .env file and streamable-http transport
docker run --rm -p 8000:8000 --env-file /path/to/.env \
zscaler/zscaler-mcp-server:latest --transport streamable-http --host 0.0.0.0
# Run with .env file and custom port
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
# Run with .env file and specific services
docker run --rm --env-file /path/to/.env \
zscaler/zscaler-mcp-server:latest --services zia,zpa,zdx
# Use a specific version instead of latest
docker run --rm --env-file /path/to/.env \
zscaler/zscaler-mcp-server:1.2.3
# Alternative: Individual environment variables
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
本地构建（开发）
出于开发或自定义目的，你可以在本地构建镜像：
# Build the Docker image
docker build -t zscaler-mcp-server .
# Run the locally built image
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
注意：在 Docker 中使用 HTTP 传输时，务必设置 --host 0.0.0.0，以允许外部连接到容器。
编辑器/助手集成
你可以将 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 等）
在远程主机（EC2、VM、内部服务器）上部署 MCP 服务，让客户端从另一台计算机通过 HTTP 连接时：
服务端设置：
-
如果使用可编辑安装（
uv pip install -e .），运行前必须激活项目虚拟环境，否则可能会运行较旧或不同的安装版本：cd /path/to/zscaler-mcp-server source .venv/bin/activate zscaler-mcp --transport streamable-http --host 0.0.0.0 --port 8000 -
使用
--host 0.0.0.0绑定所有网络接口。这会自动禁用 Host 标头验证（当客户端在 Host 标头中发送服务器的公网 IP 时，这是必需的）。在生产环境中，可考虑在.env中使用ZSCALER_MCP_ALLOWED_HOSTS限制为已知主机名。 -
确保防火墙允许所选端口（例如 8000）的入站流量。
客户端配置（Claude Desktop）：
Claude Desktop 需要通过 command 启动进程。对于远程 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 上，路径中包含空格（例如 C:\Program Files\...）时，直接调用 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：连接到非 localhost 的 HTTP 端点时必须使用。对于非 localhost URL，mcp-remote默认强制使用 HTTPS。通过 HTTPS 或连接到localhost时，请省略此标志。
使用 Zscaler 身份验证模式（基本身份验证）：
将 Authorization 标头替换为基本身份验证凭据。其值为 client_id:client_secret 的 Base64 编码：
# Generate the Base64 value
echo -n "your-client-id:your-client-secret" | base64
然后使用 "Authorization: Basic <base64_value>" 替代上面的 Bearer 标头。
**客户端前提条件：**必须安装 Node.js（用于运行 npx）。
📖 远程部署完整详情（虚拟环境用法、421 故障排除、安全性、TLS）：远程部署 · 421 错误请求目标 · 故障排除
Azure Container Apps / Virtual Machine / AKS（预览版）
将 Zscaler MCP Server 部署到 Azure，并选择所需的部署目标：
| 目标 | 描述 | 运行时 | 状态 |
|---|---|---|---|
| Container Apps | 托管式无服务器 | Docker Hub 镜像 | GA |
| Virtual Machine | Ubuntu 22.04，自行管理 | Python 库（PyPI） | GA |
| Azure Kubernetes Service (AKS) | Kubernetes Deployment + LoadBalancer | Docker Hub 镜像 | 预览版 |
# Interactive guided deployment — no .env file required
cd integrations/azure
python azure_mcp_operations.py deploy
# MCP Server management
python azure_mcp_operations.py status # check health
python azure_mcp_operations.py logs # stream logs
python azure_mcp_operations.py ssh # SSH into VM (VM only)
python azure_mcp_operations.py destroy # tear down all resources
# Azure AI Foundry Agent (optional — wraps MCP server as an AI agent)
pip install azure-ai-projects azure-identity
python azure_mcp_operations.py agent_create # create Foundry agent
python azure_mcp_operations.py agent_chat # interactive CLI chat
python azure_mcp_operations.py agent_status # show agent info
python azure_mcp_operations.py agent_destroy # delete agent
脚本会提示你输入：
- 部署目标：Container Apps、Virtual Machine 或 Azure Kubernetes Service（预览版）
- 凭据来源：
.env文件路径或手动输入 - 身份验证模式：OIDC（OAuth 2.1）、JWT、API Key、Zscaler 或 None（AKS 尚不支持 OIDC）
- Azure 选项：资源组、区域、Key Vault（新建或现有）；对于 AKS：集群生命周期（新建或使用现有集群）、节点数量/规格、命名空间
Container Apps 和 VM 会将所有机密存储在 Azure Key Vault 中（强制要求），并自动配置 Claude Desktop / Cursor。AKS 预览版会将凭据作为 Kubernetes 环境变量注入 Deployment；计划集成 Workload Identity Federation 和 Key Vault CSI driver。
Foundry Agent：可选创建一个由 Azure 托管、封装 MCP 服务的 AI Agent。可通过 CLI 聊天（带有加载动画、令牌跟踪和计时）、Azure AI Foundry 门户游乐场、REST API 或 Microsoft 365 Copilot 集成访问该 Agent。
📖 Azure 部署完整指南：integrations/azure/README.md
Google Cloud（Cloud Run / GKE / VM / ADK Agent）
Google Cloud 部署涵盖独立 MCP 服务和由 Gemini 驱动的 ADK Agent。完整的视频演示请见：
Zscaler Integration MCP Server in GCP — 视频演示
两个交互式 Python 脚本可管理所有五种 Google Cloud 部署目标：
| 脚本 | 部署目标 |
|---|---|
integrations/google/gcp/gcp_mcp_operations.py | Cloud Run、GKE、Compute Engine VM（独立 MCP 服务） |
integrations/google/adk/adk_agent_operations.py | 本地、Cloud Run、Vertex AI Agent Engine、Agentspace（ADK Agent） |
独立 MCP 服务 — 自动化部署：
cd integrations/google/gcp
python gcp_mcp_operations.py deploy # guided deployment (prompts for target)
python gcp_mcp_operations.py status # check health
python gcp_mcp_operations.py logs # stream logs
python gcp_mcp_operations.py ssh # SSH into VM (VM target only)
python gcp_mcp_operations.py destroy # tear down
脚本会提示选择部署目标、凭据和身份验证模式。它会：
- 提示输入 GCP 项目/区域（或从
.env读取） - 可选择将凭据存储在 GCP Secret Manager 中
- 使用
zscaler身份验证模式将容器部署到 Cloud Run - 根据你的 Zscaler OneAPI 凭据生成
Authorization: Basic标头 - 自动配置 Claude Desktop（
claude_desktop_config.json）和 Cursor（~/.cursor/mcp.json） - 写入部署状态文件（
.gcp-deploy-state.json），供后续status/logs/destroy操作使用
ADK Agent — 交互式部署：
cd integrations/google/adk
python adk_agent_operations.py deploy # guided deployment (local, Cloud Run, Agent Engine, Agentspace)
python adk_agent_operations.py status
python adk_agent_operations.py logs
python adk_agent_operations.py destroy
手动部署：
# Deploy with credentials as env vars
gcloud run deploy zscaler-mcp-server \
--image=zscaler/zscaler-mcp-server:latest \
--set-env-vars="ZSCALER_CLIENT_ID=...,ZSCALER_CLIENT_SECRET=...,ZSCALER_VANITY_DOMAIN=...,ZSCALER_CUSTOMER_ID=...,ZSCALER_CLOUD=production,ZSCALER_MCP_ALLOW_HTTP=true,ZSCALER_MCP_DISABLE_HOST_VALIDATION=true,ZSCALER_MCP_AUTH_ENABLED=true,ZSCALER_MCP_AUTH_MODE=zscaler" \
--args="--transport,streamable-http,--host,0.0.0.0,--port,8000" \
--port=8000 --region=us-central1 --allow-unauthenticated
使用 GCP Secret Manager（生产环境推荐）：
Docker 镜像内置了 GCP Secret Manager 加载器。将凭据分别存储为独立的密钥（例如 zscaler-client-id、zscaler-client-secret），然后设置一个环境变量即可启用：
gcloud run deploy zscaler-mcp-server \
--image=zscaler/zscaler-mcp-server:latest \
--set-env-vars="ZSCALER_MCP_GCP_SECRET_MANAGER=true,GCP_PROJECT_ID=your-project,ZSCALER_MCP_ALLOW_HTTP=true,ZSCALER_MCP_DISABLE_HOST_VALIDATION=true,ZSCALER_MCP_AUTH_ENABLED=true,ZSCALER_MCP_AUTH_MODE=zscaler" \
--args="--transport,streamable-http,--host,0.0.0.0,--port,8000" \
--port=8000 --region=us-central1 --allow-unauthenticated
该加载器也适用于 GKE 和 Compute Engine 等可使用 GCP Application Default Credentials 的环境。
📖 完整的 Google Cloud 部署指南（所有五种部署目标、IAM 角色、身份验证模式、企业模式）：integrations/google/README.md
📖 Secret Manager 深入指南（GKE 清单、凭据轮换、加载器内部机制）：GCP Secret Manager Integration
Kubernetes（Helm Chart）
通过 Helm 将 Zscaler MCP 服务部署到任何 Kubernetes 集群，包括 EKS、GKE、AKS、OpenShift、Rancher、k3s、Talos，或用于本地开发的 kind / minikube。该 chart 与集群供应商无关，且不会调用 aws、az 或 gcloud。如果集群已就绪，且你的运维模式将每个工作负载都视为 Helm 发布版本，请使用此方案；如果你需要从头搭建云基础设施，请使用上文的 Azure / GCP / AWS 部署章节。
# Interactive guided install — same pattern as the Azure / GCP scripts
python integrations/helm-chart/helm_mcp_operations.py deploy
# Lifecycle subcommands
python integrations/helm-chart/helm_mcp_operations.py status # release + pods + Service + port-forward
python integrations/helm-chart/helm_mcp_operations.py logs # tail Deployment logs
python integrations/helm-chart/helm_mcp_operations.py configure # re-write Cursor / Claude configs
python integrations/helm-chart/helm_mcp_operations.py test # run `helm test` smoke probe
python integrations/helm-chart/helm_mcp_operations.py destroy # uninstall + optional ns deletion
部署脚本会根据现有的 .env 创建 Kubernetes Secret（无需转换为 values.yaml），运行 helm upgrade --install，并等待部署完成，同时实时显示各 Pod 的状态（检测 ImagePullBackOff / CreateContainerConfigError / CrashLoopBackOff，并提供针对性的恢复建议后退出）；如果未配置 Ingress，则会在后台启动 kubectl port-forward，并使用正确的 Authorization: Basic 标头自动配置 Claude Desktop 和 Cursor。
支持五种凭据配置方式（交互式脚本、kubectl create secret --from-env-file、内联 --set、供 GitOps 使用的现有 Secret，以及 External Secrets Operator）。这五种方式最终都遵循相同的 chart 约定——Deployment 使用 envFrom: secretRef:，因此密钥中的所有 ZSCALER_MCP_* / ZSCALER_* 键都会原样传入容器。
完整的 chart 参考（values.yaml 键、Ingress / HTTPRoute / cert-manager / HPA / PDB 开关、ExternalSecret 示例）请参阅 integrations/helm-chart/README.md。
Amazon Bedrock AgentCore
重要
同一个镜像，无需 AWS 分支。 Bedrock AgentCore 过去使用单独构建的镜像。现在不再如此——标准镜像可直接在 AgentCore 上运行，完全通过环境变量进行配置。AgentCore 的
containerConfiguration仅接受 ECR URI（Docker Hub 不是有效值），且要求linux/arm64，因此仍需将已发布的多架构镜像复制到 ECR——或者从 AWS Marketplace 商品页面拉取；该页面提供的就是已为你存入 ECR 的同一个镜像。
🚀 通过 AWS Marketplace 快速开始：
通过 AWS Marketplace 商品页面部署 Zscaler Integrations MCP Server 到 Amazon Bedrock AgentCore，是最简单的方式。通过此方式可获得：
- ✅ 托管在 ECR 中的
linux/arm64镜像——AgentCore 会验证的两项内容 - ✅ 内置 AWS Secrets Manager 加载器：设置
ZSCALER_SECRET_NAME，凭证就不会以环境变量的形式出现 - ✅ 通过
ZSCALER_MCP_TRANSPORT/_HOST/_PORT控制传输方式，因为ContainerConfiguration不支持命令覆盖 - ✅ 默认只读；只有在允许列表中添加写入工具后，这些工具才会启用
- ✅ 与其他所有部署方式具有相同的工具清单、工具集和身份验证模式
📚 完整部署指南：
有关详细的部署说明、IAM 配置和故障排除，请参阅完整的 Amazon Bedrock AgentCore 部署指南。
部署指南涵盖：
- 先决条件和 AWS VPC 要求
- IAM 角色和信任策略配置
- 逐步部署说明
- 环境变量配置
- 写入模式配置（用于 CREATE/UPDATE/DELETE 操作）
- 故障排除和验证步骤
🔐 AWS Secrets Manager（内置）：
该镜像包含 AWS Secrets Manager 加载器，因此无需在运行时将凭证作为环境变量。将凭证存储为一个 JSON 密钥，并让部署指向该密钥：
aws secretsmanager create-secret \
--name zscaler/mcp/credentials \
--secret-string '{"ZSCALER_CLIENT_ID":"...","ZSCALER_CLIENT_SECRET":"...","ZSCALER_VANITY_DOMAIN":"acme","ZSCALER_CUSTOMER_ID":"123456"}'
然后在运行时设置 ZSCALER_SECRET_NAME=zscaler/mcp/credentials——设置该变量本身就是完整的启用操作，无需第二个标志。为执行角色授予 secretsmanager:GetSecretValue 权限（如果密钥使用客户自主管理的密钥，还需授予 kms:Decrypt）。密钥中的值会覆盖容器环境变量，因此轮换密钥优先于任务定义中的过期值；如果读取密钥失败，服务器会在启动时停止，而不会等到之后才显示不透明的 Zscaler API 错误。ECS Fargate、EKS 和 EC2 均可采用相同方式运行。对于 PyPI（非容器）安装，boto3 包含在可选扩展中：pip install 'zscaler-mcp[aws]'。
ZSCALER_MCP_TRUST_PLATFORM_AUTH=true 是 AgentCore 专用的应急选项：它允许 api-key / zscaler 身份验证模式接受未携带凭证的请求，并回退使用容器自身的凭证。只有在经过身份验证的入口之后使用时才安全（AgentCore 的 customJwtAuthorizer 会使用 Authorization 标头传递自身的令牌，因此不会为我们的令牌留下传递空间）。容器可被直接访问时，绝不要设置此选项。
说明
早期版本曾提供单独的 Bedrock 镜像，其中带有 FastAPI 封装层（
web_server.py），会绕过 MCP 会话初始化。该封装层现已移除：服务器使用原生的streamable-http协议，而使用2026-07-28修订版的客户端会发送独立的 POST 请求，无需会话握手。推荐使用 Marketplace 镜像，纯粹是因为它开箱即满足 AgentCore 对 ECR 和 arm64 的要求——而不是因为它运行了不同的代码。
将 MCP 服务与 Agent 配合使用
本节介绍如何将 Zscaler Integrations MCP 服务配置为与常用 AI Agent 配合使用。开始前，请确保已完成以下事项：
Claude Desktop
你可以通过以下任一方式在 Claude Desktop 中安装 Zscaler MCP 服务：
Windows 用户：一键扩展包含 macOS/Linux 二进制文件，无法在 Windows 上运行。请改用选项 2：手动配置——该方式使用
uvx在运行时安装适用于相应平台的软件包。详情请参阅故障排查：Windows。
选项 1：安装为扩展（macOS / Linux）
最简单的入门方式——只需一键安装，即可在 Claude Desktop 中使用友好的用户界面，且门槛低。
**先决条件：**必须安装 uv（提供 uvx）。该扩展使用 uvx 在运行时从 PyPI 运行服务——无需手动执行 pip install zscaler-mcp。安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh
- 打开 Claude Desktop
- 前往设置 → 扩展 → 浏览扩展
- 在搜索框中输入
zscaler - 在搜索结果中选择 Zscaler MCP Server
- 点击安装或添加
- 按提示配置
.env文件路径（或在安装后编辑配置） - 完全重启 Claude Desktop（退出后重新打开）
- 向 Claude 询问“有哪些 Zscaler 工具可用？”，以验证是否配置成功
选项 2：手动配置（所有平台，Windows 上推荐）
- 打开 Claude Desktop
- 前往设置 → 开发者 → 编辑配置
- 添加以下配置：
{
"mcpServers": {
"zscaler-mcp-server": {
"command": "uvx",
"args": ["--env-file", "/absolute/path/to/your/.env", "zscaler-mcp"]
}
}
}
重要：将
/absolute/path/to/your/.env替换为.env文件的绝对路径。在 Windows 上，使用类似C:\Users\You\.env的路径。相对路径不可用。
- 保存配置文件
- 完全重启 Claude Desktop（退出后重新打开）
- 向 Claude 询问“有哪些 Zscaler 工具可用？”，以验证是否配置成功
故障排查：
- “未找到 MCP 服务”：确认
.env文件路径是正确的绝对路径 - “身份验证失败”：检查
.env文件是否包含有效凭据 - 未显示工具：检查 Claude Desktop 日志（帮助 > 查看日志）中是否有错误
- 未找到扩展：确保在“桌面扩展”选项卡中搜索，而不是在“Web”选项卡中搜索
- Windows：
ModuleNotFoundError（rpds、pydantic_core 等）：该扩展包含 macOS/Linux 二进制文件。请改用选项 2（手动配置）。请参阅故障排查指南。
Cursor
- 打开 Cursor
- 前往设置 → Cursor 设置 → 工具与 MCP → 新建 MCP 服务
- 配置将保存到
~/.cursor/mcp.json。添加以下配置：
{
"mcpServers": {
"zscaler-mcp-server": {
"command": "uvx",
"args": ["--env-file", "/absolute/path/to/your/.env", "zscaler-mcp"]
}
}
}
替代方案：也可以使用 Docker 代替
uvx：{ "mcpServers": { "zscaler-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "--env-file", "/absolute/path/to/your/.env", "zscaler/zscaler-mcp-server:latest" ] } } }
- 保存配置文件
- 完全重启 Cursor（退出后重新打开）
- 询问“列出我的 ZIA 规则标签”，以验证是否配置成功
故障排查：
- 检查 Cursor 的 MCP 日志（查看 > 输出 > MCP）中是否有连接错误
- 确认
.env文件路径是绝对路径，且凭据正确 - 配置文件位于
~/.cursor/mcp.json（Windows 上为%USERPROFILE%\.cursor\mcp.json）
平台集成
Zscaler MCP Server 内置了与多个 AI 开发平台的集成。每项集成都包含特定于平台的配置文件、19 个引导式技能和设置说明。
| 平台 | 类型 | 快速入门 | 详情 |
|---|---|---|---|
| Claude Code | 插件 | claude plugin install zscaler | integrations/claude-code-plugin/ |
| Cursor | 插件 | 设置 → 工具与 MCP → 新建 MCP 服务 | integrations/cursor-plugin/ |
| Gemini CLI | 扩展 | 注册 gemini-extension.json | integrations/gemini-extension/ |
| Kiro IDE | Power | Powers 面板 → 添加自定义 Power | integrations/kiro/ |
| Azure（Container Apps / VM） | 部署 + Agent | python azure_mcp_operations.py deploy | integrations/azure/ |
| Google Cloud（Cloud Run / GKE / VM） | 部署 | python gcp_mcp_operations.py deploy | integrations/google/ |
| Google ADK Agent | Agent | python adk_agent_operations.py deploy | integrations/google/adk/ |
| Kubernetes（Helm Chart） | 部署 | python helm_mcp_operations.py deploy | integrations/helm-chart/ |
| GitHub MCP Registry | 注册表 | mcp-publisher publish | integrations/github/ |
如需所有集成的完整文档，请参阅平台集成指南。
所有 Agent 的常见故障排查
常见问题：
-
“找不到命令：uvx”
- 安装
uv：curl -LsSf https://astral.sh/uv/install.sh | sh - 或使用 Docker：将
uvx替换为docker run --rm --env-file /path/to/.env zscaler/zscaler-mcp-server:latest
- 安装
-
“找不到 .env 文件”
- 使用绝对路径，而不是相对路径
- 确认指定路径下存在该文件
- 检查文件权限（应可读取）
-
“身份验证失败”
- 确认
.env中包含所有必需的 OneAPI 环境变量 - 检查凭据是否正确且未过期
- 确认
-
“未显示工具”
- 某些 Agent 要求你在其界面中启用工具
- 检查 Agent 日志中是否有连接错误
- 确认 MCP 服务正在运行（检查 Agent 的 MCP 状态）
-
“服务连接超时”
- 确保 MCP 服务能够成功启动
- 手动测试：
uvx --env-file /absolute/path/to/.env zscaler-mcp - 如果使用 HTTP 传输方式，请检查端口冲突
-
Windows：
ModuleNotFoundError: No module named 'rpds.rpds'（Claude Desktop 扩展）- 该扩展捆绑了 macOS/Linux 二进制文件。请改用
uvx zscaler-mcp进行手动配置。 - 请参阅故障排查：Windows。
- 该扩展捆绑了 macOS/Linux 二进制文件。请改用
-
Windows：
'C:\Program' is not recognized（使用npx的远程 MCP）- 直接调用
npx时，包含空格的路径会导致问题。请改用"command": "cmd"和"args": ["/c", "npx", ...]。 - 请参阅故障排查：Windows npx 路径问题。
- 直接调用
-
Non-HTTPS URLs are only allowed for localhost（mcp-remote）- 默认情况下，
mcp-remote会强制要求非 localhost URL 使用 HTTPS。请在args数组中、--header之前添加"--allow-http"。 - 请参阅故障排查：mcp-remote 强制使用 HTTPS。
- 默认情况下，
-
self-signed certificate/DEPTH_ZERO_SELF_SIGNED_CERT（使用 TLS 的 mcp-remote）- 使用自签名证书时，请在客户端配置中的 MCP 服务条目添加
"env": { "NODE_TLS_REJECT_UNAUTHORIZED": "0" }。 - 请参阅故障排查：自签名证书。
- 使用自签名证书时，请在客户端配置中的 MCP 服务条目添加
获取帮助：
- 查看 Agent 专属日志（通常位于 Help/View 菜单中）
- 手动测试服务，以区分 Agent 与服务的问题
- 查看故障排查部分，了解更多详情
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。