# Zscaler AI Guard Control Plane MCP

An unofficial Model Context Protocol (MCP) server that provides AI agents (Gemini, Claude, Cursor) with programmatic, REST-based access to the **Zscaler AI Guard (Zseclipse)** ecosystem.

This MCP server allows your AI assistants to autonomously list, create, update, and delete Detection Policies, Match Rules, LLM Applications, and LLM Providers.

## Overview

The server wraps the Zscaler AI Guard Public API (https://api.zsapi.net/aiguard/v1). It handles secure OAuth 2.0 client_credentials authentication natively, meaning your AI agent simply calls high-level tools like create_policy or list_llm_apps, and the server manages the Bearer token lifecycle and REST payloads.

---

## Prerequisites & Authentication

To use this MCP server, you must provide three pieces of information from your Zscaler tenant. 

### How to obtain your API Credentials:
1. Log in to your Zscaler AI Guard (or ZIdentity) administration portal.
2. Navigate to the **API Clients** page.
3. Click **Add API Client** (or generate a new credential). 
4. Ensure the client is granted the necessary scopes (all:read, all:write, all:delete).
5. **Copy the Client Secret immediately**, as it is only shown once at creation.

### Environment Variables
The MCP server reads these credentials directly from your environment variables:

*   **ZSCALER_CLIENT_ID**: The OAuth Client ID generated in Step 3.
*   **ZSCALER_CLIENT_SECRET**: The OAuth Client Secret generated in Step 3.
*   **ZSCALER_VANITY_DOMAIN**: Your Zscaler organization's login domain (e.g., if you log in at https://mycompany.zslogin.net, your vanity domain is mycompany).

---

## Available MCP Tools

This server maps directly to the Zscaler AI Guard API Reference. All tools expect and return standard JSON payloads.

### Detection Policies
Manage AI guard detection policies that inspect and act on prompts and responses.
*   list_policy_summaries: Returns a lightweight list of all detection policies (IDs, names, versions, timestamps).
*   list_policies: Returns all detection policies with full detector configuration.
*   get_policy: Fetch a specific policy by its numeric ID.
*   get_policy_by_name: Fetch a specific policy by its exact name.
*   create_policy: Creates a new detection policy (requires JSON payload).
*   update_policy: Replaces a detection policy completely.
*   enable_policy_controls: Partially updates the enabled/disabled state of individual policy controls.
*   delete_policy: Permanently deletes a detection policy.
*   check_policy_references: Checks if a policy is actively referenced by match rules or LLM applications.

### Detection Policy Match Rules
Manage match rules that define the conditions under which a detection policy triggers.
*   list_match_rules: Returns all match rules for the tenant.
*   get_match_rule / get_match_rule_by_name
*   create_match_rule
*   update_match_rule
*   delete_match_rule

### LLM Applications
Manage the LLM applications registered with AI Guard.
*   list_llm_applications
*   get_llm_application / get_llm_application_by_name
*   create_llm_application
*   update_llm_application
*   delete_llm_application
*   check_application_references

### LLM Providers
Manage the LLM providers configured for the tenant.
*   list_llm_providers
*   get_llm_provider / get_llm_provider_by_name
*   create_llm_provider
*   update_llm_provider
*   delete_llm_provider
*   check_provider_references

---

## Installation & Usage

### 1. Gemini CLI (Native Integration)

The fastest way to install this MCP server into your Gemini CLI is to use the native command.

First, clone this repository:
```bash
git clone https://github.com/hshen-ai/zscaler-aiguard-control-plane-mcp.git
cd zscaler-aiguard-control-plane-mcp
```

Then, run the simplified MCP installation command (ensure you replace the placeholder credentials with your actual ZIdentity keys):
```bash
gemini mcp add zscaler-aiguard-control-plane-mcp --env ZSCALER_CLIENT_ID=your_client_id --env ZSCALER_CLIENT_SECRET=your_client_secret --env ZSCALER_VANITY_DOMAIN=your_vanity_domain -- uv run --manifest-path ./pyproject.toml fastmcp run ./server.py
```

### 2. Claude Desktop / Claude Code
Add the server to your claude_desktop_config.json or .claude/mcp-servers.json:

{
  "mcpServers": {
    "zscaler-aiguard-control-plane-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "/path/to/Zscaler-AI-Guard-Control-Plane-MCP/server.py"],
      "env": {
        "ZSCALER_CLIENT_ID": "...",
        "ZSCALER_CLIENT_SECRET": "...",
        "ZSCALER_VANITY_DOMAIN": "..."
      }
    }
  }
}

### 3. Cursor IDE
In Cursor Settings > Features > MCP, add a new server:
*   Name: zscaler-aiguard-control-plane-mcp
*   Type: command
*   Command: uv run fastmcp run /path/to/Zscaler-AI-Guard-Control-Plane-MCP/server.py