Manage Zscaler Zero Trust Exchange via 400+ tools — ZPA, ZIA, ZDX, ZCC, ZTW, ZMS, EASM, and more.
This MCP server manages Zscaler Zero Trust Exchange using 400+ tools covering multiple Zscaler products, including ZPA, ZIA, ZDX, ZCC, ZTW, ZMS, and EASM. The repository is published on PyPI and includes GitHub Pages documentation for integrations.
🛠️ Key Features
Provides management capabilities for Zscaler Zero Trust Exchange
zscaler-mcp-server is a Model Context Protocol (MCP) server that connects AI agents with the Zscaler Zero Trust Exchange platform. By default, the server operates in read-only mode for security, requiring explicit opt-in to enable write operations.
Support Disclaimer
-> Disclaimer: Please refer to our General Support Statement before proceeding with the use of this provider. You can also refer to our troubleshooting guide for guidance on typical problems.
IMPORTANT
🚧 Public Preview: This project is currently in public preview and under active development. Features and functionality may change before the stable 1.0 release. While we encourage exploration and testing, please avoid production deployments. We welcome your feedback through GitHub Issues to help shape the final release.
The Zscaler Integrations MCP Server brings context to your agents. Try prompts like:
"List my ZPA Application segments"
"List my ZPA Segment Groups"
"List my ZIA Rule Labels"
WARNING
🔒 READ-ONLY BY DEFAULT: For security, this MCP server operates in read-only mode by default. Only list_* and get_* operations are available. To enable tools that can CREATE, UPDATE, or DELETE Zscaler resources, you must explicitly enable write mode using the --enable-write-tools flag or by setting ZSCALER_MCP_WRITE_ENABLED=true. See the Security & Permissions section for details.
TIP
Writing effective prompts: This server exposes 402 tools across multiple Zscaler services. Most MCP clients (Claude Desktop, Cursor, etc.) use deferred tool loading and will search for relevant tools based on your prompt. For best results, be specific about the service and action in your prompts:
Good: "List my ZPA application segments" — targets the right service and tool directly
Good: "Show ZIA firewall rules" — clear service (zia) and action (list)
Less effective: "Show me my devices" — ambiguous; multiple services expose device-related tools
When a service is disabled, its tools are fully removed from the server. However, the AI agent may still attempt to find related tools in other services. If you get unexpected results, refine your prompt with the specific service name (e.g. zpa, zia, zdx, zcc, zcell, zms).
🔒 Security & Permissions
The Zscaler MCP Server implements a security-first design with granular permission controls and safe defaults:
Read-Only Mode (Default - Always Available)
By default, the server operates in read-only mode, exposing only tools that list or retrieve information:
✅ ALWAYS AVAILABLE - Read-only tools are registered by the server
✅ Safe to use with AI agents autonomously
✅ No risk of accidental resource modification or deletion
✅ All list_* and get_* operations are available (110+ read-only tools)
❌ All create_*, update_*, and delete_* operations are disabled by default
💡 Note: You may need to enable read-only tools in your AI agent's UI settings
bash
# Read-only mode (default - safe)
zscaler-mcp
When the server starts in read-only mode, you'll see:
text
🔒 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 tools are ALWAYS registered by the server regardless of any flags. You never need to enable them server-side. Note: Your AI agent UI (like Claude Desktop) may require you to enable individual tools before use.
Write Mode (Explicit Opt-In - Allowlist REQUIRED)
To enable tools that can create, modify, or delete Zscaler resources, you must provide BOTH flags:
✅ --enable-write-tools - Global unlock for write operations
🔐 SECURITY: Allowlist is MANDATORY - If you set --enable-write-tools without --write-tools, 0 write tools will be registered. This ensures you consciously choose which write operations to enable.
bash
# ❌ 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_*"
When you try to enable write mode without an allowlist:
text
⚠️ 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'
Write Tools Allowlist (MANDATORY)
The allowlist provides two-tier security:
✅ First Gate: --enable-write-tools must be set (global unlock)
✅ Second Gate: Explicit allowlist determines which write tools are registered (MANDATORY)
Allowlist Examples:
bash
# 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_*"
This design allows AI assistants (Claude, Cursor, GitHub Copilot) to:
Allow-list read-only tools for autonomous exploration
Require explicit user confirmation for write operations
Clearly understand the intent of each tool from its name
Responses: the API record, verbatim
A read tool returns the Zscaler API record unchanged. The server does not
trim, rename, or re-declare a resource's attributes — that attribute set belongs
to the API, so a field Zscaler adds in future reaches you with no server upgrade.
To keep responses small, you control what comes back rather than the server
guessing. Two levers:
--toolsets — load only the slice of tools you need, so the tool catalog
stays small (see Toolsets).
query — every list tool accepts an optional JMESPath
expression applied to the results, so the agent projects exactly what it wants:
text
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
Field names are exactly what the Zscaler API returns. Omit query to get the
full records.
Security Layers
The server implements multiple layers of security (defense-in-depth). The first nine apply on every transport, including stdio — they govern which tools are exposed and how dangerous calls are confirmed. The remaining HTTP-only layers (TLS, host-header validation, source-IP ACL, MCP client authentication) are described in the Network-Level Controls section further down.
Read-Only Tools Always Enabled: Safe list_* and get_* operations are always available (254 tools).
Default Write Mode Disabled: Write tools are disabled unless explicitly enabled via --enable-write-tools.
OneAPI Entitlement Filter: At startup, toolsets for products the OneAPI credentials cannot call are silently dropped (see OneAPI Entitlement Filter below).
Toolset Selection: Optionally narrow the registered tool surface to a specific slice (e.g. --toolsets zia_url_filtering,zpa_app_segments). See the Toolsets section below.
Verb-Based Tool Naming: Each tool clearly indicates its purpose (list, get, create, update, delete).
Tool Metadata Annotations: All tools are annotated with readOnlyHint or destructiveHint for AI agent frameworks.
AI Agent Confirmation: All write tools marked with destructiveHint=True trigger permission dialogs in AI assistants.
Human Confirmation for DELETE: Delete operations are gated by a server-initiated confirmation. On clients that support MCP elicitation (Claude Desktop, Cursor), the server asks the client to prompt a human and the answer arrives as a protocol field — so a hijacked agent cannot author the approval, and a failed round trip fails closed. Clients without that capability fall back to a cryptographic confirmation token (HMAC-SHA256, single-use, 5-minute TTL, bound to the exact tool and parameters), which stops an approval being spent on another resource, replayed or reused — but is not by itself an anti-prompt-injection control, since a hijacked agent receives and can redeem it. The fallback is also single-process; elicitation-capable clients are unaffected. See MCP protocol posture — confirmation threat model for the full analysis.
Environment Variable Control: ZSCALER_MCP_WRITE_ENABLED, ZSCALER_MCP_WRITE_TOOLS, ZSCALER_MCP_TOOLSETS, ZSCALER_MCP_DISABLE_ENTITLEMENT_FILTER, and the disable lists can all be managed centrally without code changes.
Output Sanitization: Every string in every tool result is run through a three-stage sanitizer before reaching the agent — invisible/control characters (BiDi overrides, zero-width chars, BOM, soft hyphen) are stripped, raw HTML and HTML comments are removed (via bleach), Markdown link/image syntax is neutralised so embedded URLs cannot be smuggled to the agent, and Markdown code-fence info-strings containing role-impersonation tokens (system, assistant, tool, ignore, …) are collapsed to a neutral text tag. This defends against prompt-injection payloads that an attacker — or a careless admin — might embed in editable Zscaler resources (rule descriptions, location names, label descriptions, etc.). On by default. Opt-out with ZSCALER_MCP_DISABLE_OUTPUT_SANITIZATION=true (use only for diagnostics).
Audit Logging: When --log-tool-calls / ZSCALER_MCP_LOG_TOOL_CALLS=true is set, every tool invocation is logged with its arguments (sensitive values redacted), duration, and a result summary.
This multi-layered approach ensures that even if one security control is bypassed, others remain in place to prevent unauthorized operations. Layers 1-12 above apply equally to stdio, sse, and streamable-http.
Toolsets
Tools are grouped into 63 named toolsets so you can load only the slice an agent actually needs (e.g. zia_url_filtering (5 tools) instead of every tool from every service (402)). Toolsets reduce the agent's context cost and improve tool-selection accuracy.
bash
# 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 variableexport ZSCALER_MCP_TOOLSETS="zia_url_filtering,zpa_app_segments"
When --toolsets is unspecified, every toolset whose service is enabled is loaded (preserves the historical default).
The agent can also enable additional toolsets at runtime through the always-on zscaler_list_toolsets, zscaler_get_toolset_tools, and zscaler_enable_toolset tools.
For the full catalog (29 toolsets across all services), filter precedence rules, per-toolset agent guidance, and the complete reference, see docs/guides/toolsets.md.
OneAPI Entitlement Filter
After your toolset selection resolves, the server reads the product entitlements from the OneAPI bearer token issued for your ZSCALER_CLIENT_ID and silently drops toolsets for products the credentials cannot call. If your OneAPI client is only entitled to ZIA and ZPA, every zdx_* / zcc_* / ztw_* / zid_* / zeasm_* / zins_* / zms_* toolset is filtered out at startup — even with --toolsets all.
This prevents an agent from discovering tools whose first call would only ever return 401 Unauthorized. The filter applies on every transport, including stdio.
When the filter runs you'll see one log line at startup, for example:
The filter is non-fatal. If credentials are missing, the token endpoint is unreachable, the token doesn't decode, or the token has no recognizable product entitlements, the server logs a single WARN line and starts normally with the user-selected toolsets unchanged.
To bypass the filter (for example, while diagnosing an unusual token shape):
Only product entitlement is honoured — not role names. The server defers per-action permission enforcement to the live API; the entitlement filter only ensures we don't advertise tools for products the client has zero access to.
Cryptographic Confirmation for Destructive Actions
Delete operations are never executed on the first call. What happens instead depends on the client:
Clients that support MCP elicitation get an interactive prompt naming the resource, answered by a human. The AI agent never handles the approval.
Every other client gets a cryptographic confirmation token (HMAC-SHA256) it must pass back to proceed. The token is bound to the specific operation and its parameters, is single-use, and expires after 5 minutes — so it can't be forged, replayed, or reused for a different resource.
There is no way to turn this off. Deletes are irreversible against a live tenant, so the server ships no flag or environment variable that skips the gate. If you don't want an agent deleting anything, don't allowlist the delete tools: write tools are off by default and --write-tools takes explicit patterns (see Write Mode).
Network-Level Controls (HTTP only)
The next four subsections — TLS, source-IP allowlist, host-header validation, and the .env plaintext-secret scanner — apply only to the HTTP transports (sse, streamable-http). They control who can reach the server over the network. They are independent of the tool-level controls listed in Security Layers above (read-only mode, write allowlist, toolsets, entitlement filter, HMAC confirmations), which apply on every transport including stdio.
The corresponding MCP client authentication (Bearer / Basic / OAuth 2.1) is a fifth network-level layer covered in detail in the MCP Client Authentication section further below.
HTTPS/TLS Support
HTTPS is required by default for non-localhost deployments. The server will refuse to start on a non-localhost interface without TLS certificates unless you explicitly set ZSCALER_MCP_ALLOW_HTTP=true.
When running with HTTP transports (sse or streamable-http), provide TLS certificates:
env
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
When TLS is configured, the server automatically starts with HTTPS. This works with both public (CA-signed) and private (self-signed) certificates. Generate a self-signed certificate for testing:
You can restrict which client IPs are allowed to connect using ZSCALER_MCP_ALLOWED_SOURCE_IPS. When unset (the default), source IP filtering is disabled and deferred to upstream controls (firewall rules, AWS Security Groups, etc.).
env
# 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
Supports individual IPv4/IPv6 addresses, CIDR notation, and the wildcard 0.0.0.0/0. Health-check endpoints (/health, /healthz, /ready) are exempt so load-balancer probes continue to work. Requests from disallowed IPs receive 403 Forbidden.
.env File Security Warning
When starting with HTTP transports, the server automatically scans any .env file in the working directory for plaintext secrets (values containing SECRET, PASSWORD, KEY, or TOKEN). If detected, a security warning is logged recommending the use of a secrets manager or environment variables instead.
Security Posture Banner
On startup, the server logs a consolidated Security Posture Banner summarizing the active security configuration — transport mode, host validation status, authentication mode, TLS status, and any active warnings. This makes it easy to verify the security state at a glance.
Key Security Principles:
No "enable all write tools" backdoor exists - allowlist is mandatory
AI agents must request permission before executing any write operation (destructiveHint)
Every destructive action requires explicit user approval through the AI agent's permission framework
Destructive confirmations are cryptographically bound to prevent prompt injection bypass
Best Practices
Read-Only by Default: No configuration needed for safe operations - read-only tools are always available
Mandatory Allowlist: Always provide explicit --write-tools allowlist when enabling write mode
Development/Testing: Use narrow allowlists (e.g., --write-tools "zpa_create_application_segment")
Production/Agents: Keep server in read-only mode (default) for AI agents performing autonomous operations
CI/CD: Never set ZSCALER_MCP_WRITE_ENABLED=true without a corresponding ZSCALER_MCP_WRITE_TOOLS allowlist
Least Privilege: Use narrowest possible allowlist patterns for your use case
Wildcard Usage: Use wildcards for service-level control (e.g., zpa_create_*) or operation-level control (e.g., *_create_*)
Audit Review: Regularly review which write tools are allowlisted and remove unnecessary ones
Specific Prompts: With 402 tools and deferred loading, AI agents match prompts to tools by relevance. Use service-specific prompts (e.g., "List ZPA segments" instead of "Show my segments") for accurate tool selection
When running the MCP server over HTTP (sse or streamable-http transports), you can enable authentication to control who is allowed to connect to the server. This is independent from the Zscaler API credentials, which control how the server authenticates to Zscaler APIs.
For HTTP transports, the server auto-detects and enables authentication when auth-related environment variables are present. For stdio transport, authentication is not applicable (the operating system's process isolation provides security).
Authentication Modes
The server supports four authentication modes, configured via environment variables:
Environments already using Zscaler API credentials
oidc
OAuth 2.1 against your own IdP — the server is an OAuth 2.0 protected resource (RFC 9728) and clients authenticate with the IdP directly
Browser-based login for human operators, any OIDC provider
Quick Start
Enable authentication by setting these environment variables in your .env file:
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
Then start the server with an HTTP transport:
bash
zscaler-mcp --transport streamable-http
Clients must include the key in the Authorization header:
text
Authorization: Bearer sk-your-secret-key-here
How It Works
Authentication is implemented as ASGI middleware that wraps the HTTP transport layer:
text
MCP Client Request
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Auth │────▶│ MCP │────▶│ Zscaler │
│ Middleware │ │ Server │ │ APIs │
└──────────────┘ └──────────────┘ └──────────────┘
Layer 1: WHO MCP Protocol Layer 2: HOW
can connect? Processing server talks
to Zscaler
Layer 1 (MCP Client Auth): Controlled by ZSCALER_MCP_AUTH_* variables — validates the incoming request
Layer 2 (Zscaler API Auth): Controlled by ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET, etc. — authenticates the server to Zscaler APIs
These two layers are completely independent. You can enable one, both, or neither.
ZSCALER_MCP_AUTH_ENABLED=true
ZSCALER_MCP_AUTH_MODE=zscaler
# Uses ZSCALER_VANITY_DOMAIN and ZSCALER_CLOUD from your existing config
Clients authenticate with Basic Auth (client_id:client_secret) or custom headers (X-Zscaler-Client-ID / X-Zscaler-Client-Secret).
Authentication Defaults
For HTTP transports (sse, streamable-http), the server auto-detects and enables authentication if auth-related environment variables are present (e.g., ZSCALER_MCP_AUTH_JWKS_URI, ZSCALER_MCP_AUTH_API_KEY, or ZSCALER_VANITY_DOMAIN). If no auth configuration is detected and ZSCALER_MCP_AUTH_ENABLED is not explicitly set, the server logs a security warning but continues without authentication.
To explicitly disable authentication, set:
env
ZSCALER_MCP_AUTH_ENABLED=false
Authentication does not apply to stdio transport (process isolation provides security).
OAuth 2.1 (oidc mode)
oidc mode makes the server an OAuth 2.0 protected resource (RFC 9728). The server publishes /.well-known/oauth-protected-resource naming your Identity Provider; the client reads that, runs the OAuth flow against the IdP directly, and presents the resulting token. The server's only job is verifying the token signature against the IdP's published public keys.
It is configured entirely through environment variables — no code, no extra packages:
env
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
Notes:
No client secret. Verifying a signature needs the IdP's public keys, not a credential of ours. OIDCPROXY_CLIENT_SECRET is ignored if set.
OIDCPROXY_BASE_URL is this server's public URL, which clients use as the resource identifier — not the IdP's.
OIDCPROXY_AUDIENCE defaults to OIDCPROXY_CLIENT_ID. Entra ID puts the client ID in aud; Auth0 uses the API identifier.
The issuer and JWKS URI are read from the IdP's discovery document at startup, so they always match what the IdP actually signs with.
The server serves no /authorize, /token or /register — clients need a client ID issued by the IdP and cannot self-register.
Works with any OIDC-compliant provider (Auth0, Okta, Microsoft Entra ID, Keycloak, Google, AWS Cognito, PingOne).
All other security layers (TLS, source-IP ACL, host validation) remain active.
IdP requirements: an application with the callback URL your client uses (http://localhost:3334/oauth/callback for mcp-remote, with the port pinned) registered, and an API/resource identifier matching OIDCPROXY_AUDIENCE.
Note: All write operations require the --enable-write-tools flag and an explicit --write-tools allowlist. See the Security & Permissions section for details.
Copy the example environment file and configure your credentials:
bash
cp .env.example .env
Then edit .env with your Zscaler API credentials:
Required Configuration (OneAPI):
ZSCALER_CLIENT_ID: Your Zscaler OAuth client ID
ZSCALER_CLIENT_SECRET: Your Zscaler OAuth client secret
ZSCALER_CUSTOMER_ID: Your Zscaler customer ID
ZSCALER_VANITY_DOMAIN: Your Zscaler vanity domain
Optional Configuration:
ZSCALER_CLOUD: (Optional) Zscaler cloud environment (e.g., beta) - Required when interacting with Beta Tenant ONLY.
ZSCALER_PRIVATE_KEY: (Optional) PEM-encoded private key for JWT-based OneAPI auth, used in place of ZSCALER_CLIENT_SECRET.
ZSCALER_MCP_SERVICES: Comma-separated list of services to enable (default: all services)
ZSCALER_MCP_TRANSPORT: Transport method - stdio, sse, or streamable-http (default: stdio)
ZSCALER_MCP_DEBUG: Enable debug logging - true or false (default: false)
ZSCALER_MCP_HOST: Host for HTTP transports (default: 127.0.0.1)
ZSCALER_MCP_PORT: Port for HTTP transports (default: 8000)
Alternatively, you can set these as environment variables instead of using a .env file.
Important: Ensure your API client has the necessary permissions for the services you plan to use. You can always update permissions later in the Zscaler console.
Installation
Install with VS Code (Quick Setup)
Note: This will open VS Code and prompt you to configure the MCP server. You'll need to replace the placeholder values (<YOUR_CLIENT_ID>, etc.) with your actual Zscaler credentials.
Install using uv (recommended)
bash
uv tool install zscaler-mcp
Install from source using uv (development)
bash
uv pip install -e .
Remote deployment: When running on EC2/VM, activate the project venv before starting: source .venv/bin/activate. See Remote MCP Deployment.
Install from source using pip
bash
pip install -e .
Install using make (convenience)
bash
make install-dev
TIP
If zscaler-mcp-server isn't found, update your shell PATH.
Default Security Mode: All examples below run in read-only mode by default (only list_* and get_* operations). To enable write operations (create_*, update_*, delete_*), add the --enable-write-tools flag to any command, or set ZSCALER_MCP_WRITE_ENABLED=true in your environment.
Command Line
Run the server with default settings (stdio transport, read-only mode):
bash
zscaler-mcp
Run the server with write operations enabled:
bash
zscaler-mcp --enable-write-tools
Run with SSE transport:
bash
zscaler-mcp --transport sse
Run with streamable-http transport:
bash
zscaler-mcp --transport streamable-http
Run with streamable-http transport on custom port:
When you want to keep most tools available but exclude a few, use --disabled-tools or --disabled-services instead of listing every tool you want to include.
Both flags support wildcards via fnmatch patterns.
bash
# 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"
Precedence:--disabled-tools takes precedence over --tools (include list). A tool that matches both the include list and the exclude list will be excluded.
--transport: Transport protocol (stdio, sse, streamable-http)
--services: Comma-separated list of services to enable
--disabled-services: Comma-separated list of services to exclude (e.g., zcc,zdx)
--tools: Comma-separated list of specific tools to enable
--disabled-tools: Comma-separated list of tools to exclude, supports wildcards (e.g., zcc_*,zdx_list_devices)
--toolsets: Comma-separated toolset ids to enable (e.g. zia_url_filtering,zpa_app_segments). Special values: default (curated default-on subset), all (every toolset). When unspecified, every toolset whose service is enabled is loaded. See docs/guides/toolsets.md.
--no-entitlement-filter: Skip the OneAPI entitlement filter that trims toolsets to the products the configured ZSCALER_CLIENT_ID is entitled to. Emergency override only — the filter is non-fatal by default.
--enable-write-tools: Enable write operations (disabled by default for safety)
--write-tools: Mandatory allowlist of write tool patterns (e.g., "zpa_create_*,zpa_delete_*")
The Zscaler Integrations MCP Server uses OneAPI authentication exclusively. A single set of credentials authenticates the server to every Zscaler product (ZIA, ZPA, ZCC, ZDX, Zscaler Cellular, ZTW, ZIdentity, ZMS, Z-Insights, EASM).
Zscaler Cellular (ZCell) needs one extra credential — your Zscaler Cellular customer ID via ZCELL_CUSTOMER_ID — which is separate from ZSCALER_CUSTOMER_ID (used by ZPA). See the environment-variable table below.
Create a .env file in your project root (or wherever you start the MCP server):
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
⚠️ Security: Do not commit .env to source control. Add it to your .gitignore.
OneAPI Environment Variables
Environment Variable
Required
Description
ZSCALER_CLIENT_ID
Yes
OneAPI client ID from the ZIdentity console
ZSCALER_CLIENT_SECRET
Yes (or ZSCALER_PRIVATE_KEY)
OneAPI client secret
ZSCALER_CUSTOMER_ID
Yes (for ZPA tools)
Zscaler customer/tenant ID
ZCELL_CUSTOMER_ID
Yes (for Zscaler Cellular tools)
Zscaler Cellular customer ID (distinct from ZSCALER_CUSTOMER_ID; also accepted as the zcellCustomerId config key)
ZSCALER_VANITY_DOMAIN
Yes
Your organization's vanity domain (e.g., acme)
ZSCALER_CLOUD
No
Cloud override (e.g., beta, zscalertwo); omit for production
ZSCALER_PRIVATE_KEY
No
PEM-encoded private key for JWT auth (used in place of ZSCALER_CLIENT_SECRET)
Verification
After populating .env, start the server:
bash
zscaler-mcp
If credentials are valid, the server starts cleanly. The Zscaler SDK client is created lazily on the first tool call, so missing or rotating credentials surface as a clear error message at call time rather than blocking server startup.
Authentication Troubleshooting
Symptom
Likely cause
Fix
Zscaler SDK failed to initialize due to missing OneAPI credentials: [...]
One or more of ZSCALER_CLIENT_ID, ZSCALER_VANITY_DOMAIN, or (for ZPA) ZSCALER_CUSTOMER_ID is unset or empty.
Set the listed env vars in .env or your shell.
You must provide either ZSCALER_CLIENT_SECRET or ZSCALER_PRIVATE_KEY for the OneAPI client.
Both auth materials are absent.
Set one of ZSCALER_CLIENT_SECRET or ZSCALER_PRIVATE_KEY.
401/403 from a Zscaler API at tool-call time
API client lacks the scope for that product, or credentials are revoked.
Verify the OneAPI client's permissions in the ZIdentity console; rotate credentials if necessary.
MCP Server Configuration
The following environment variables control MCP server behavior (not authentication):
Environment Variable
Default
Description
ZSCALER_MCP_TRANSPORT
stdio
Transport protocol to use (stdio, sse, or streamable-http)
ZSCALER_MCP_SERVICES
""
Comma-separated list of services to enable (empty = all services). Supported values: zcc, zdx, zia, zid, zpa, ztw
ZSCALER_MCP_TOOLS
""
Comma-separated list of specific tools to enable (empty = all tools)
ZSCALER_MCP_DISABLED_SERVICES
""
Comma-separated list of services to exclude (e.g., zcc,zdx). Takes precedence over ZSCALER_MCP_SERVICES.
ZSCALER_MCP_DISABLED_TOOLS
""
Comma-separated list of tools to exclude. Supports wildcards (e.g., zcc_*,zia_list_devices). Takes precedence over ZSCALER_MCP_TOOLS.
ZSCALER_MCP_WRITE_ENABLED
false
Enable write operations (true/false). When false, only read-only tools are available. Set to true or use --enable-write-tools flag to unlock write mode.
ZSCALER_MCP_WRITE_TOOLS
""
MANDATORY comma-separated allowlist of write tools (supports wildcards like zpa_*). Requires ZSCALER_MCP_WRITE_ENABLED=true. If empty when write mode enabled, 0 write tools registered.
ZSCALER_MCP_DEBUG
false
Enable debug logging (true/false)
ZSCALER_MCP_HOST
127.0.0.1
Host to bind to for HTTP transports
ZSCALER_MCP_PORT
8000
Port to listen on for HTTP transports
ZSCALER_MCP_DISABLE_HOST_VALIDATION
false
Disable Host header validation when exposing on EC2/public IP (true/false). Alternatively, use --host 0.0.0.0 which auto-disables.
ZSCALER_MCP_ALLOWED_HOSTS
""
Comma-separated allowed Host values for remote deployment (e.g. 34.201.19.115:*,localhost:*). Preferred over disable for production.
ZSCALER_MCP_TLS_CERTFILE
""
Path to TLS certificate file (PEM format) for HTTPS.
ZSCALER_MCP_TLS_KEYFILE
""
Path to TLS private key file (PEM format) for HTTPS.
ZSCALER_MCP_TLS_KEYFILE_PASSWORD
""
Password for encrypted TLS private key (if applicable).
ZSCALER_MCP_TLS_CA_CERTS
""
Path to CA certificate bundle for mutual TLS or custom CA chains.
ZSCALER_MCP_ALLOW_HTTP
false
Allow plaintext HTTP on non-localhost interfaces. HTTPS is required by default for remote deployments. Set to true only when TLS is terminated upstream (reverse proxy, ZPA, VPN).
ZSCALER_MCP_ALLOWED_SOURCE_IPS
""
Comma-separated list of allowed client IPs/CIDRs (e.g. 10.0.0.0/8,172.16.0.5). When unset, source IP filtering is disabled (defer to firewall/security groups). Set to 0.0.0.0/0 to allow all.
ZSCALER_MCP_CONFIRMATION_TTL
300
HMAC fallback token lifetime in seconds. Does not apply to the sealed requestState used by elicitation-capable clients (SDK envelope TTL, default 600s). There is no variable that skips the confirmation itself.
ZSCALER_MCP_REQUEST_STATE_KEYS
(unset)
Shared key ring for the SEP-2322 requestState. JSON array or comma-separated; each key ≥32 bytes (python -c "import secrets; print(secrets.token_hex(32))"). Required for multi-replica HTTP deployments with write tools enabled — unset uses a per-process key, so a confirmation issued by one replica cannot be validated by another. First key seals, all unseal (rotate [old,new] → [new,old] → [new]).
ZSCALER_MCP_DISABLE_OUTPUT_SANITIZATION
false
Disable defense-in-depth output sanitization (BiDi / zero-width / HTML / Markdown / code-fence stripping). Sanitization is on by default; only set this for diagnostics — disabling it removes a prompt-injection defense layer.
ZSCALER_MCP_USER_AGENT_COMMENT
""
Additional information to include in User-Agent comment section
User-Agent Header
The MCP server automatically includes a custom User-Agent header in all API requests to Zscaler services. The format is:
You can append additional information (such as the AI agent details) using the ZSCALER_MCP_USER_AGENT_COMMENT environment variable or the --user-agent-comment CLI flag:
bash
# Via environment variableexport 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"
This results in:
sh
User-Agent: zscaler-mcp-server/0.3.1 python/3.11.8 darwin/arm64 Claude Desktop 1.2024.10.23
The User-Agent helps Zscaler identify API traffic from the MCP server and can be useful for support, analytics, and debugging purposes.
As a Library
You can use the Zscaler Integrations MCP Server as a Python library in your own applications:
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)
Example with write operations enabled:
python
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")
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")
Running Examples
bash
# 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
Container Usage
The Zscaler Integrations MCP Server is available as a pre-built container image for easy deployment:
Using Pre-built Image (Recommended)
bash
# 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
Building Locally (Development)
For development or customization purposes, you can build the image locally:
bash
# 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
Note: When using HTTP transports in Docker, always set --host 0.0.0.0 to allow external connections to the container.
Editor/Assistant Integration
You can integrate the Zscaler Integrations MCP server with your editor or AI assistant. Here are configuration examples for popular MCP clients:
Note: The published PyPI package is zscaler-mcp (not zscaler-mcp-server). When integrating as a Claude Code plugin, use ${CLAUDE_PLUGIN_ROOT}/.env instead of an absolute path; for Gemini extensions, use ${extensionPath}${pathSeparator}.env.
Additional Deployment Options
Remote MCP Deployment (EC2, VM, etc.)
When deploying the MCP server on a remote host (EC2, VM, internal server) so clients connect over HTTP from another machine:
If using an editable install (uv pip install -e .), you must activate the project venv before running—otherwise an older or different installation may run:
Use --host 0.0.0.0 to bind on all interfaces. This automatically disables Host header validation (required when clients send the server's public IP in the Host header). For production, consider ZSCALER_MCP_ALLOWED_HOSTS in .env to restrict to known hostnames.
Ensure the firewall allows inbound traffic on the chosen port (e.g. 8000).
Client configuration (Claude Desktop):
Claude Desktop expects a command that spawns a process. For remote HTTP, use mcp-remote which supports custom authentication headers.
--allow-http: Required when connecting to a non-localhost HTTP endpoint. mcp-remote enforces HTTPS by default for non-localhost URLs. Omit this flag when connecting over HTTPS or to localhost.
Using Zscaler auth mode (Basic Auth):
Replace the Authorization header with Basic Auth credentials. The value is the Base64 encoding of client_id:client_secret:
bash
# Generate the Base64 valueecho -n "your-client-id:your-client-secret" | base64
Then use "Authorization: Basic <base64_value>" in place of the Bearer header above.
Prerequisites on the client: Node.js (for npx) must be installed.
Azure Container Apps / Virtual Machine / AKS (Preview)
Deploy the Zscaler MCP Server to Azure with your choice of deployment target:
Target
Description
Runtime
Status
Container Apps
Managed, serverless
Docker Hub image
GA
Virtual Machine
Ubuntu 22.04, self-managed
Python library (PyPI)
GA
Azure Kubernetes Service (AKS)
Kubernetes Deployment + LoadBalancer
Docker Hub image
Preview
bash
# Interactive guided deployment — no .env file requiredcd 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
The script will prompt you for:
Deployment target: Container Apps, Virtual Machine, or Azure Kubernetes Service (Preview)
Credential source: .env file path or manual entry
Auth mode: OIDC (OAuth 2.1), JWT, API Key, Zscaler, or None (OIDC not yet supported on AKS)
Azure options: resource group, region, Key Vault (new or existing); for AKS: cluster lifecycle (create new or use existing), node count/size, namespace
Container Apps and VM store all secrets in Azure Key Vault (mandatory) and auto-configure Claude Desktop / Cursor. AKS Preview injects credentials as Kubernetes environment variables on the Deployment — Workload Identity Federation + Key Vault CSI driver integration is planned.
Foundry Agent: Optionally create an Azure-hosted AI agent that wraps the MCP server. The agent is accessible via CLI chat (with spinner, token tracking, and timing), the Azure AI Foundry portal playground, REST APIs, or Microsoft 365 Copilot integrations.
# 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
With GCP Secret Manager (recommended for production):
The Docker image includes a built-in GCP Secret Manager loader. Store credentials as individual secrets (e.g., zscaler-client-id, zscaler-client-secret) and enable with a single env var:
Deploy the Zscaler MCP Server to any Kubernetes cluster via Helm — EKS, GKE, AKS, OpenShift, Rancher, k3s, Talos, or kind / minikube for local dev. The chart is cluster-vendor-agnostic and never calls aws, az, or gcloud. Use this when the cluster is already a fact and your operating model treats every workload as a Helm release; if you instead need to stand up brand-new cloud infra, use the Azure / GCP / AWS deployment sections above.
bash
# 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
The deployment script materialises a Kubernetes Secret from your existing .env (no translation into values.yaml), runs helm upgrade --install, waits for the rollout with live per-pod feedback (detects ImagePullBackOff / CreateContainerConfigError / CrashLoopBackOff and exits with a tailored recovery hint), starts a background kubectl port-forward when no Ingress is configured, and auto-configures Claude Desktop + Cursor with the right Authorization: Basic header.
Five credential-setup paths are supported (interactive script, kubectl create secret --from-env-file, inline --set, pre-existing Secret for GitOps, and External Secrets Operator). All five converge on the same chart contract — the Deployment does envFrom: secretRef: so every ZSCALER_MCP_* / ZSCALER_* key in your secret flows into the container untouched.
For the full chart reference (values.yaml keys, Ingress / HTTPRoute / cert-manager / HPA / PDB toggles, ExternalSecret examples), see integrations/helm-chart/README.md.
Amazon Bedrock AgentCore
IMPORTANT
One image, no AWS fork. Bedrock AgentCore used to be served by a separate build. It no longer is — the standard image runs on AgentCore as-is, configured entirely through environment variables. AgentCore's containerConfiguration accepts only an ECR URI (Docker Hub is not a legal value) and requires linux/arm64, so the published multi-arch image still needs to be copied into ECR — or pulled from the AWS Marketplace listing, which is the same image already in ECR for you.
🚀 Quick Start with AWS Marketplace:
The easiest way to deploy the Zscaler Integrations MCP Server to Amazon Bedrock AgentCore is through the AWS Marketplace listing. What you get on this path:
✅ ECR-hosted linux/arm64 image — the two things AgentCore validates
✅ Built-in AWS Secrets Manager loader: set ZSCALER_SECRET_NAME and credentials never appear as environment variables
✅ Transport steered by ZSCALER_MCP_TRANSPORT / _HOST / _PORT, because ContainerConfiguration has no command override
✅ Read-only by default; write tools stay off until you allowlist them
✅ Identical tool inventory, toolsets, and auth modes to every other deployment
The image includes an AWS Secrets Manager loader, so credentials never have to appear as environment variables on the runtime. Store them as one JSON secret and point the deployment at it:
Then set ZSCALER_SECRET_NAME=zscaler/mcp/credentials on the runtime — its presence is the entire opt-in, there is no second flag. Grant the execution role secretsmanager:GetSecretValue (and kms:Decrypt if the secret uses a customer-managed key). Values from the secret override the container environment, so rotating the secret beats a stale value in a task definition, and a failure to read it stops the server at startup rather than surfacing later as an opaque Zscaler API error. Works the same on ECS Fargate, EKS and EC2. For a PyPI (non-container) install, boto3 rides the optional extra: pip install 'zscaler-mcp[aws]'.
ZSCALER_MCP_TRUST_PLATFORM_AUTH=true is an AgentCore-specific escape hatch: it lets api-key / zscaler auth modes accept a request carrying no credential, falling back to the container's own. It is safe only behind an authenticating ingress (AgentCore's customJwtAuthorizer consumes the Authorization header for its own token, leaving no envelope for ours). Never set it where the container is directly reachable.
NOTE
Earlier releases shipped a separate Bedrock image with a FastAPI wrapper (web_server.py) that bypassed MCP session initialization. That wrapper is gone: the server speaks vanilla streamable-http, and clients on the 2026-07-28 revision are self-contained POSTs with no session handshake at all. The Marketplace image is recommended purely because it satisfies AgentCore's ECR + arm64 requirements out of the box — not because it runs different code.
Using the MCP Server with Agents
This section provides instructions for configuring the Zscaler Integrations MCP Server with popular AI agents. Before starting, ensure you have:
You can install the Zscaler MCP Server in Claude Desktop using either method:
Windows users: The one-click extension bundles macOS/Linux binaries and will not work on Windows. Use Option 2: Manual Configuration instead—it uses uvx to install platform-appropriate packages at runtime. See Troubleshooting: Windows for details.
Option 1: Install as Extension (macOS / Linux)
The easiest way to get started—one-click install with a user-friendly UI in Claude Desktop and low barrier to entry.
Prerequisites:uv must be installed (provides uvx). The extension uses uvx to run the server from PyPI at runtime—no manual pip install zscaler-mcp required. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
Open Claude Desktop
Go to Settings → Extensions → Browse Extensions
In the search box, type zscaler
Select Zscaler MCP Server from the results
Click Install or Add
Configure your .env file path when prompted (or edit the configuration after installation)
Restart Claude Desktop completely (quit and reopen)
Verify by asking Claude: "What Zscaler tools are available?"
Option 2: Manual Configuration (All platforms, recommended on Windows)
Important: Replace /absolute/path/to/your/.env with the absolute path to your .env file. On Windows, use a path like C:\Users\You\.env. Relative paths will not work.
Save the configuration file
Restart Claude Desktop completely (quit and reopen)
Verify by asking Claude: "What Zscaler tools are available?"
Troubleshooting:
"MCP server not found": Verify the .env file path is absolute and correct
"Authentication failed": Check that your .env file contains valid credentials
Tools not appearing: Check Claude Desktop logs (Help > View Logs) for errors
Extension not found: Ensure you're searching in the "Desktop extensions" tab, not "Web"
Windows: ModuleNotFoundError (rpds, pydantic_core, etc.): The extension bundles macOS/Linux binaries. Use Option 2 (Manual Configuration) instead. See Troubleshooting guide.
Cursor
Open Cursor
Go to Settings → Cursor Settings → Tools & MCP → New MCP Server
The configuration will be saved to ~/.cursor/mcp.json. Add the following configuration:
Verify the .env file path is absolute and credentials are correct
The configuration file is located at ~/.cursor/mcp.json (or %USERPROFILE%\.cursor\mcp.json on Windows)
Platform Integrations
The Zscaler MCP Server ships with native integrations for several AI development platforms. Each integration includes platform-specific configuration files, 19 guided skills, and setup instructions.
