Zscaler MCP Server

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.

📄 Table of contents

• 📺 Overview
• 🔒 Security & Permissions
• 🔐 MCP Client Authentication
• Supported Tools
• Installation & Setup
  • Prerequisites
  • Environment Configuration
  • Installation
• Usage
  • Command Line
  • Service Configuration
  • Additional Command Line Options
• Zscaler API Credentials & Authentication
  • OneAPI Authentication
  • Authentication Troubleshooting
  • MCP Server Configuration
• As a Library
• Container Usage
  • Using Pre-built Image (Recommended)
  • Building Locally (Development)
• Editor/Assistant Integration
  • Using uvx (recommended)
  • With Service Selection
  • Using Individual Environment Variables
  • Docker Version
• Additional Deployment Options
  • Remote MCP Deployment (EC2, VM, etc.)
  • Azure Container Apps / Virtual Machine / AKS (Preview)
  • Google Cloud (Cloud Run / GKE / VM / ADK Agent)
  • Kubernetes (Helm Chart)
  • Amazon Bedrock AgentCore
• Using the MCP Server with Agents
  • Claude Desktop
  • Cursor
  • Visual Studio Code + GitHub Copilot
• Platform Integrations
• Troubleshooting
• License

📺 Overview

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 300+ 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

# Read-only mode (default - safe)
zscaler-mcp

When the server starts in read-only mode, you'll see:

🔒 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:

1. ✅ --enable-write-tools - Global unlock for write operations
2. ✅ --write-tools "pattern" - MANDATORY explicit allowlist

🔐 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.

# ❌ 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:

⚠️  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:

1. ✅ First Gate: --enable-write-tools must be set (global unlock)
2. ✅ Second Gate: Explicit allowlist determines which write tools are registered (MANDATORY)

Allowlist Examples:

# 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_*"

Or via environment variable:

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

Wildcard patterns supported:

• zpa_create_* - Allow all ZPA creation tools
• zpa_delete_* - Allow all ZPA deletion tools
• zpa_* - Allow all ZPA write tools
• *_application_segment - Allow all operations on application segments
• zpa_create_application_segment - Exact match (no wildcard)

When using a valid allowlist, you'll see:

⚠️  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

Tool Design Philosophy

Each operation is a separate, single-purpose tool with explicit naming that makes its intent clear:

✅ Good (Verb-Based - Current Design)

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

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

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.

1. Read-Only Tools Always Enabled: Safe list_* and get_* operations are always available (110+ tools).
2. Default Write Mode Disabled: Write tools are disabled unless explicitly enabled via --enable-write-tools.
3. Mandatory Allowlist: Write operations require explicit --write-tools allowlist (wildcard support).
4. OneAPI Entitlement Filter: At startup, toolsets for products the OneAPI credentials cannot call are silently dropped (see OneAPI Entitlement Filter below).
5. 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.
6. Verb-Based Tool Naming: Each tool clearly indicates its purpose (list, get, create, update, delete).
7. Tool Metadata Annotations: All tools are annotated with readOnlyHint or destructiveHint for AI agent frameworks.
8. AI Agent Confirmation: All write tools marked with destructiveHint=True trigger permission dialogs in AI assistants.
9. Double Confirmation for DELETE: Delete operations require both the agent's permission dialog AND a server-side cryptographic confirmation token (HMAC-SHA256, single-use, 5-minute TTL). This makes prompt-injection attacks against destructive actions ineffective.
10. 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.
11. 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).
12. 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 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 (~280)). Toolsets reduce the agent's context cost and improve tool-selection accuracy. The meta toolset (server discovery) is always loaded.

# 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"

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:

entitlement filter applied: entitled services=['zia', 'zpa'], kept 12 toolset(s), removed 17 toolset(s)

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):

zscaler-mcp --no-entitlement-filter
# or
export ZSCALER_MCP_DISABLE_ENTITLEMENT_FILTER=true

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 use a cryptographic confirmation token (HMAC-SHA256) instead of a simple confirmed=true boolean. This prevents prompt injection attacks where a malicious prompt could trick the AI agent into confirming a destructive action. The token is bound to the specific operation parameters and expires after 5 minutes.

This mechanism is transparent to end users — the AI agent handles the confirmation flow automatically through its standard permission dialog.

To bypass confirmations in automated testing or CI/CD environments:

export ZSCALER_MCP_SKIP_CONFIRMATIONS=true

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:

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:

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

Source IP Access Control

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.).

# 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 300+ 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

🔐 MCP Client Authentication

📖 Full Documentation: Authentication & Deployment Guide

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:

Mode	Description	Best For
api-key	Simple shared secret — client sends Authorization: Bearer <key>	Quick setup, internal environments, development
jwt	External Identity Provider via JWKS — tokens validated locally using public keys	Enterprise SSO, multi-tenant deployments (Auth0, Okta, Azure AD, Keycloak, AWS Cognito, PingOne, Google)
zscaler	Zscaler OneAPI credential validation — client sends Basic Auth with client_id:client_secret	Environments already using Zscaler API credentials
auth= param	Full MCP-spec OAuth 2.1 with DCR via fastmcp AuthProvider (e.g. OIDCProxy)	Library consumers, programmatic OAuth 2.1, any OIDC provider

Quick Start

Enable authentication by setting these environment variables in your .env file:

# 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:

zscaler-mcp --transport streamable-http

Clients must include the key in the Authorization header:

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

How It Works

Authentication is implemented as ASGI middleware that wraps the HTTP transport layer:

MCP Client Request
      │
      ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Auth         │────▶│  FastMCP      │────▶│  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.

Configuration by Mode

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 via 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 (default: RS256,ES256)

Zscaler OneAPI Credentials

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:

ZSCALER_MCP_AUTH_ENABLED=false

Authentication does not apply to stdio transport (process isolation provides security).

Library-Level OAuth 2.1 (auth= Parameter)

When using ZscalerMCPServer as a Python library, you can pass a fastmcp.server.auth.AuthProvider instance (such as OIDCProxy or OAuthProxy) directly to the constructor. This provides full MCP-spec-compliant OAuth 2.1 with Dynamic Client Registration (DCR), and is the recommended approach for programmatic OAuth integration.

import os
from fastmcp.server.auth.oidc_proxy import OIDCProxy
from zscaler_mcp.server import ZscalerMCPServer

auth = OIDCProxy(
    config_url="https://your-tenant.auth0.com/.well-known/openid-configuration",
    client_id=os.getenv("OIDCPROXY_CLIENT_ID"),
    client_secret=os.getenv("OIDCPROXY_CLIENT_SECRET"),
    base_url="http://localhost:8000",
    audience="zscaler-mcp-server",
)

# Allow standard OIDC scopes for Dynamic Client Registration
if auth.client_registration_options:
    auth.client_registration_options.valid_scopes = [
        "openid", "profile", "email",
    ]

server = ZscalerMCPServer(auth=auth)
server.run("streamable-http", host="0.0.0.0", port=8000)

When auth= is provided:

• The server delegates authentication entirely to the AuthProvider
• The env-var-based auth middleware (ZSCALER_MCP_AUTH_*) is automatically skipped
• OAuth routes (.well-known/oauth-protected-resource, /register, /authorize, /token) are handled by the provider
• All other security features (TLS, Source IP ACL, host validation) remain active
• Works with any OIDC-compliant Identity Provider (Auth0, Okta, Azure AD, Keycloak, Google, AWS Cognito, PingOne, etc.)

IdP requirements: Your Identity Provider must have a Regular Web Application (not M2M) with the callback URL http://localhost:8000/auth/callback registered, and an API/resource server with identifier matching the audience value.

📖 For detailed setup instructions — including OIDCProxy setup with Auth0/Okta/Azure AD, Microsoft Entra ID step-by-step guide, IdP-specific JWKS configuration, Docker deployment examples, client configuration for Claude/Cursor/VS Code, and troubleshooting — see the Authentication & Deployment Guide.

Supported Tools

The Zscaler Integrations MCP Server provides 402 tools for all major Zscaler services:

Service	Description	Tools
ZIA	Zscaler Internet Access — Security policies	166 read/write
ZPA	Zscaler Private Access — Application access	109 read/write
ZDX	Zscaler Digital Experience — Monitoring & analytics	31 read/write
ZCell	Zscaler Cellular — SIM inventory, usage analytics & anomaly policies	20 read-only
ZMS	Zscaler Microsegmentation — Agents, resources, policies	20 read-only
ZTW	Zscaler Workload Segmentation	19 read/write
Z-Insights	Z-Insights analytics — Web traffic, cyber incidents, shadow IT	16 read-only
ZIdentity	ZIdentity — Identity & access management	10 read-only
EASM	External Attack Surface Management	7 read-only
ZCC	Zscaler Client Connector — Device management	4 read-only

📖 View Complete Tools Reference →

Note: All write operations require the --enable-write-tools flag and an explicit --write-tools allowlist. See the Security & Permissions section for details.

Installation & Setup

Prerequisites

• Python 3.11 or higher
• uv or pip
• Zscaler API credentials (see below)

Environment Configuration

Copy the example environment file and configure your credentials:

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)

uv tool install zscaler-mcp

Install from source using uv (development)

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

pip install -e .

Install using make (convenience)

make install-dev

[!TIP] If zscaler-mcp-server isn't found, update your shell PATH.

For installation via code editors/assistants, see the Using the MCP Server with Agents section below.

Usage

[!NOTE] 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):

zscaler-mcp

Run the server with write operations enabled:

zscaler-mcp --enable-write-tools

Run with SSE transport:

zscaler-mcp --transport sse

Run with streamable-http transport:

zscaler-mcp --transport streamable-http

Run with streamable-http transport on custom port:

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

Service Configuration

The Zscaler Integrations MCP Server supports multiple ways to specify which services to enable:

1. Command Line Arguments (highest priority)

Specify services using comma-separated lists:

# Enable specific services
zscaler-mcp --services zia,zpa,zdx

# Enable only one service
zscaler-mcp --services zia

2. Environment Variable (fallback)

Set the ZSCALER_MCP_SERVICES environment variable:

# Export environment variable
export ZSCALER_MCP_SERVICES=zia,zpa,zdx
zscaler-mcp

# Or set inline
ZSCALER_MCP_SERVICES=zia,zpa,zdx zscaler-mcp

3. Default Behavior (all services)

If no services are specified via command line or environment variable, all available services are enabled by default.

Service Priority Order:

1. Command line --services argument (overrides all)
2. ZSCALER_MCP_SERVICES environment variable (fallback)
3. All services (default when none specified)

Excluding Services and Tools

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.

# 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"

Environment variables:

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

Precedence: --disabled-tools takes precedence over --tools (include list). A tool that matches both the include list and the exclude list will be excluded.

Additional Command Line Options

# 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

For all available options:

zscaler-mcp --help

Available command-line flags:

• --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_*")
• --log-tool-calls: Enable per-tool-call audit logging (tool name, redacted arguments, duration, result summary)
• --debug: Enable debug logging
• --host: Host for HTTP transports (default: 127.0.0.1)
• --port: Port for HTTP transports (default: 8000)
• --user-agent-comment: Additional text appended to User-Agent header
• --generate-auth-token: Generate a client auth token snippet and exit
• --list-tools: List all available tools and exit
• --version: Show server version and exit

Supported Agents

• Claude
• Cursor
• VS Code or VS Code Insiders

Zscaler API Credentials & Authentication

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.

OneAPI Authentication

Prerequisites

1. Create an API Client in the ZIdentity platform.
2. Obtain your clientId, clientSecret (or privateKey for JWT), customerId, and vanityDomain.
3. Learn more: Understanding OneAPI.

Quick Setup

Create a .env file in your project root (or wherever you start the MCP server):

# 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_