zscaler/zscaler-mcp-server

zscaler-mcp-server is a Model Context Protocol (MCP) server that connects AI agents with the Zscaler Zero Trust Exchange platform.

Support Disclaimer

-> Disclaimer: Please refer to our before proceeding with the use of this provider. You can also refer to our 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
• ⚙️ Supported Tools
  • ZCC Features
  • ZDX Features
  • ZIdentity Features
  • ZIA Features
  • ZPA Features
  • ZTW Features
• Installation & Setup
  • Prerequisites
  • Environment Configuration
  • Installation
• Usage
  • Command Line
  • Service Configuration
  • Additional Command Line Options
• Zscaler API Credentials & Authentication
  • Zscaler OneAPI Authentication
  • Using Legacy Mode with Environment Variable
  • Zscaler Legacy API Login
    • ZIA Legacy Authentication
    • ZPA Legacy Authentication
    • ZCC Legacy Authentication
    • ZDX Legacy Authentication
• Internal Environment Variables
  • MCP Server Configuration
  • OneAPI Authentication
  • Legacy Authentication
• 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
  • Amazon Bedrock AgentCore
• 🔦 Using the MCP Server with Agents
  • 🧠 Claude
  • 💻 Cursor
  • Visual Studio Code + GitHub Copilot
• 📝 Troubleshooting
• 🤝 Contributing
  • Getting Started for Contributors
  • Running Tests
• 📄 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"

⚙️ Supported Tools

The Zscaler Integrations MCP Server provides tools for all major Zscaler services. Each service offers specific functionality for managing and querying Zscaler resources.

ZCC Features

ZDX Features

ZIdentity Features

ZIA Features

ZPA Features

ZTW Features

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_USE_LEGACY: Enable legacy API mode (true/false, default: false)
• 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 using uv (recommended)

uv tool install zscaler-mcp-server

Note: This method requires the package to be published to PyPI. Currently, this package is in development and not yet published. Use one of the source installation methods below.

Install from source using uv (development)

uv pip install -e .

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

Command Line

Run the server with default settings (stdio transport):

zscaler-mcp

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)

Additional Command Line Options

For all available options:

zscaler-mcp --help

Supported Agents

• Claude
• Cursor
• VS Code or VS Code Insiders

Zscaler API Credentials & Authentication

The Zscaler Integrations MCP Server supports two authentication methods: OneAPI (recommended) and Legacy API. Choose the method that best fits your setup.

Zscaler OneAPI Authentication

Before using the Zscaler Integrations MCP Server, you need to create API credentials in your Zidentity console. The Zscaler Integrations MCP Server supports Zscaler's OneAPI authentication via OAuth2.0 as the default and preferred method.

• OneAPI: If you are using the OneAPI entrypoint you must have a API Client created in the Zidentity platform

Create a .env file in your project root with the following:

ZSCALER_CLIENT_ID=your_client_id
ZSCALER_CLIENT_SECRET=your_client_secret
ZSCALER_CUSTOMER_ID=your_customer_id
ZSCALER_VANITY_DOMAIN=your_vanity_domain
ZSCALER_CLOUD=beta

⚠️ Do not commit .env to source control. Add it to your .gitignore.

You can provide credentials via the ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET, ZSCALER_VANITY_DOMAIN, ZSCALER_CLOUD environment variables, representing your Zidentity OneAPI credentials clientId, clientSecret, vanityDomain and cloud respectively.

Using Legacy Mode with Environment Variable

To enable legacy API mode for all tools, set the ZSCALER_USE_LEGACY environment variable:

# Enable legacy mode for all tools
ZSCALER_USE_LEGACY=true

# Legacy ZPA credentials
ZPA_CLIENT_ID=your_zpa_client_id
ZPA_CLIENT_SECRET=your_zpa_client_secret
ZPA_CUSTOMER_ID=your_zpa_customer_id
ZPA_CLOUD=BETA

# Legacy ZIA credentials
ZIA_USERNAME=your_zia_username
ZIA_PASSWORD=your_zia_password
ZIA_API_KEY=your_zia_api_key
ZIA_CLOUD=beta

# Legacy ZCC credentials
ZCC_CLIENT_ID=your_zcc_client_id
ZCC_CLIENT_SECRET=your_zcc_client_secret
ZCC_CLOUD=beta

# Legacy ZDX credentials
ZDX_CLIENT_ID=your_zdx_client_id
ZDX_CLIENT_SECRET=your_zdx_client_secret
ZDX_CLOUD=beta

When ZSCALER_USE_LEGACY=true is set, all tools will use legacy API clients by default. You can still override this per tool call by explicitly setting use_legacy: false in the tool parameters.

Note: When using legacy mode, the MCP server will initialize without creating a client during startup. Clients are created on-demand when individual tools are called, which allows the server to work with different legacy services (ZPA, ZIA, ZDX) without requiring a specific service to be specified during initialization.

Important: Legacy credentials are only loaded when ZSCALER_USE_LEGACY=true is set. In OneAPI mode, legacy credentials are ignored to prevent conflicts.

Zscaler Legacy API Login

ZIA Legacy Authentication

You can provide credentials via the ZIA_USERNAME, ZIA_PASSWORD, ZIA_API_KEY, ZIA_CLOUD environment variables, representing your ZIA username, password, api_key and cloud respectively.

ZIA_USERNAME=username
ZIA_PASSWORD=password
ZIA_API_KEY=api_key
ZIA_CLOUD=cloud

⚠️ Do not commit .env to source control. Add it to your .gitignore.

The following cloud environments are supported:

• zscaler
• zscalerone
• zscalertwo
• zscalerthree
• zscloud
• zscalerbeta
• zscalergov
• zscalerten
• zspreview

ZPA Legacy Authentication

You can provide credentials via the ZPA_CLIENT_ID, ZPA_CLIENT_SECRET, ZPA_CUSTOMER_ID, ZPA_CLOUD environment variables, representing your ZPA clientId, clientSecret, customerId and cloud of your ZPA account, respectively.

ZPA_CLIENT_ID=client_id
ZPA_CLIENT_SECRET=client_secret
ZPA_CUSTOMER_ID=customer_id
ZPA_CLOUD=cloud

⚠️ Do not commit .env to source control. Add it to your .gitignore.

ZCC Legacy Authentication

You can provide credentials via the ZCC_CLIENT_ID, ZCC_CLIENT_SECRET, ZCC_CLOUD environment variables, representing your ZIA api_key, secret_key, and cloud respectively.

~> NOTE ZCC_CLOUD environment variable is required, and is used to identify the correct API gateway where the API requests should be forwarded to.

ZCC_CLIENT_ID=api_key
ZCC_CLIENT_SECRET=secret_key
ZCC_CLOUD=cloud

⚠️ Do not commit .env to source control. Add it to your .gitignore.

The following cloud environments are supported:

• zscaler
• zscalerone
• zscalertwo
• zscalerthree
• zscloud
• zscalerbeta
• zscalergov
• zscalerten
• zspreview

ZDX Legacy Authentication

You can provide credentials via the ZDX_CLIENT_ID, ZDX_CLIENT_SECRET environment variables, representing your ZDX key_id, key_secret of your ZDX account, respectively.

ZDX_CLIENT_ID=api_key
ZDX_CLIENT_SECRET=secret_key
ZDX_CLOUD=cloud

⚠️ Do not commit .env to source control. Add it to your .gitignore.

Internal Environment Variables

The Zscaler Integrations MCP Server uses the following internal environment variables for configuration:

MCP Server Configuration

OneAPI Authentication

Legacy Authentication (when ZSCALER_USE_LEGACY=true)

ZPA Legacy:

ZIA Legacy:

ZCC Legacy:

ZDX Legacy:

As a Library

You can use the Zscaler Integrations MCP Server as a Python library in your own applications:

from zscaler_mcp.server import ZscalerMCPServer

# Create and run the server
server = ZscalerMCPServer(
    debug=True,  # Optional, enable debug logging
    enabled_services={"zia", "zpa", "zdx"},  # Optional, defaults to all services
    enabled_tools={"zia_rule_labels", "zpa_application_segments"},  # Optional, defaults to all tools
    user_agent_comment="My Custom App"  # Optional, additional User-Agent info
)

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

Available Services: zcc, zdx, zia, zidentity, zpa

Example with Environment Variables:

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

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

# Pull the latest pre-built image
docker pull quay.io/zscaler/zscaler-mcp-server:latest

# Run with .env file (recommended)
docker run --rm --env-file /path/to/.env quay.io/zscaler/zscaler-mcp-server:latest

# Run with .env file and SSE transport
docker run --rm -p 8000:8000 --env-file /path/to/.env \
  quay.io/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 \
  quay.io/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 \
  quay.io/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 \
  quay.io/zscaler/zscaler-mcp-server:latest --services zia,zpa,zdx

# Use a specific version instead of latest
docker run --rm --env-file /path/to/.env \
  quay.io/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 \
  quay.io/zscaler/zscaler-mcp-server:latest

Building Locally (Development)

For development or customization purposes, you can build the image locally:

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

Using uvx (recommended)

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

With Service Selection

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

Using Individual Environment Variables

{
  "mcpServers": {
    "zscaler-mcp-server": {
      "command": "uvx",
      "args": ["zscaler-mcp-server"],
      "env": {
        "ZSCALER_CLIENT_ID": "your-client-id",
        "ZSCALER_CLIENT_SECRET": "your-client-secret",
        "ZSCALER_CUSTOMER_ID": "your-customer-id",
        "ZSCALER_VANITY_DOMAIN": "your-vanity-domain"
      }
    }
  }
}

Docker Version

{
  "mcpServers": {
    "zscaler-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/full/path/to/.env",
        "quay.io/zscaler/zscaler-mcp-server:latest"
      ]
    }
  }
}

Additional Deployment Options

Amazon Bedrock AgentCore

To deploy the MCP Server as a tool in Amazon Bedrock AgentCore, please refer to the .

🔦 Using the MCP Server with Agents

Once your server is running (via Docker or source), you can access its tools through AI-integrated editors or platforms.

🧠 Claude

1. Open Claude
2. In Chat, select the "Search & Tools"
3. The server appears in the tools list zscaler-mcp-server
4. Try prompts like "List ZPA Segment Groups" or "List ZIA Rule Labels"
5. Select the tool and click "Submit"

💻 Cursor

1. Open Cursor, then settings
2. In Curos Settings, select "Tools & Integrations"
3. In the MCP Tools section, turn on zscaler-mcp-server
4. Select View and Command Palette and Chat: Open Chat Agent
5. In chat, switch to Agent Mode.
6. Try prompts like "List ZPA Segment Groups" or "List ZIA Rule Labels"
7. Click "Submit"

Visual Studio Code + GitHub Copilot

Install

After installation, select GitHub Copilot Agent Mode and refresh the tools list. Learn more about Agent Mode in the VS Code Documentation.

1. Open VS Code and launch GitHub Copilot
2. Switch to Agent Mode (via the gear menu)
3. Start the MCP Server
4. Refresh the tools list
5. Try a prompt like: Create a ZPA segment group named "DevServices"

📚 Learn more about Agent Mode in the VS Code Copilot documentation

📝 Troubleshooting

See the for help with common issues and logging.

Contributing

Getting Started for Contributors

1. Clone the repository:

   git clone https://github.com/zscaler/zscaler-mcp-server.git
   cd zscaler-mcp-server
   

2. Install in development mode:

   # Create .venv and install dependencies
   uv sync --all-extras
   
   # Activate the venv
   source .venv/bin/activate
   

[!IMPORTANT] This project uses Conventional Commits for automated releases and semantic versioning. Please follow the commit message format outlined in our when submitting changes.

Running Tests

# Run all tests
pytest

# Run end-to-end tests
pytest --run-e2e tests/e2e/

# Run end-to-end tests with verbose output (note: -s is required to see output)
pytest --run-e2e -v -s tests/e2e/

License

Copyright (c) 2025 Zscaler

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.