Prisma AIRS MCP Security Relay

By Palo Alto Networks

• Prisma AIRS MCP Security Relay
• Overview
• Prerequisites
• Requirements for Prisma AIRS API Usage
• Installation
• Standalone installer
• Quickstart: Install and Run via pypi.org
• Standard Install
• Install the bleeding edge development version
• Upgrade
• Configuration
• MCP Relay Server Configuration
  • Configuration Precedence
  • Configuration File Format
• Environment Variables
• MCP Client Configuration
• Transport Options
• Usage
• pan-mcp-relay CLI Usage
• Running the Relay Server
  • stdio transport (default)
  • Streamable HTTP transport
  • SSE transport
• Legal

Overview

pan-mcp-relay is a security-enhanced Model Context Protocol (MCP) Relay (Proxy) Server providing real-time AI threat protection for MCP Clients, built with the [Prisma AIRS AI Runtime API Intercept].

pan-mcp-relay will help protect MCP Clients such as IDE's, LLM Chat Clients, and AI Agents from harmful MCP Server Tools by automatically scanning and blocking various threats, including prompt injections, malicious URLs, insecure outputs, AI agentic threats, sensitive data loss, and more.

The MCP Relay scans all MCP Server tool descriptions, tool call parameters, and tool call responses.

For licensing, onboarding, activation, and to obtain an API authentication key and profile name, refer to the [Prisma AIRS AI Runtime: API Intercept Overview] administration documentation.

Prerequisites

Follow the following Activation and Onboarding guides:

1. Create and associate a deployment profile for Prisma AIRS AI Runtime API intercept in your Customer Support Portal.
2. Onboard Prisma AIRS AI Runtime API intercept in Strata Cloud Manager.
3. Manage applications, API keys, security profiles, and custom topics in Strata Cloud Manager.

Requirements for Prisma AIRS API Usage

1. API Key: Generate an API Key during the onboarding process in Strata Cloud Manager (see the onboarding prerequisite step above).
2. Specify the API Key via configuration flag, environment variable or configuration file.
3. AI Security Profile Name: This is the API security profile you created during the onboarding process in Strata Cloud Manager (see the prerequisite step on creating an API security profile above).
4. Specify the profile name or the profile ID via configuration flag, environment variable, or configuration file.

[!NOTE] You can manage API keys and AI security profiles in Strata Cloud Manager.

1. Log in to [Strata Cloud Manager].
2. Navigate to Insights > Prisma AIRS > Prisma AIRS AI Runtime: API Intercept.

3. In the top right corner, click:

4. Manage > API Keys to copy, regenerate, or rotate the API key token.

5. Manage > Security Profiles to fetch details or update AI security profiles.
6. Manage > Custom Topics create or update custom topics for custom topic guardrails threat detections.

For complete details, refer to the Activation and Onboarding guides on how to [Manage Applications, API Keys, Security Profiles, and Custom Topics].

Installation

We highly recommend using [uv] over pip or pipx. Try it! You'll love it.

Installing uv

See more installation methods at https://docs.astral.sh/uv/getting-started/installation/.

Standalone installer

uv provides a standalone installer to download and install uv:

=== "macOS and Linux"

Use `curl` to download the script and execute it with `sh`:

```console
$ curl -LsSf https://astral.sh/uv/install.sh | sh
```

If your system doesn't have `curl`, you can use `wget`:

```console
$ wget -qO- https://astral.sh/uv/install.sh | sh
```

Request a specific version by including it in the URL:

```console
$ curl -LsSf https://astral.sh/uv/0.8.13/install.sh | sh
```

=== "Windows"

Use `irm` to download the script and execute it with `iex`:

```pwsh-session
PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Changing the [execution policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4#powershell-execution-policies) allows running a script from the internet.

Request a specific version by including it in the URL:

```pwsh-session
PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.8.13/install.ps1 | iex"
```

!!! tip

The installation script may be inspected before use:

=== "macOS and Linux"

    ```console
    $ curl -LsSf https://astral.sh/uv/install.sh | less
    ```

=== "Windows"

    ```pwsh-session
    PS> powershell -c "irm https://astral.sh/uv/install.ps1 | more"
    ```

Alternatively, the installer or binaries can be downloaded directly from [GitHub](#github-releases).

Update uv if already installed - uv releases updates frequently, so make sure you're on the latest.

uv self update

Quickstart: Install and Run via pypi.org

Install and run pan-mcp-relay in one line, showing the CLI help:

uvx pan-mcp-relay@latest --help

[!NOTE] While this makes it easy to get started, you can get faster startup times by following the Standard Install

Standard Install

uv installs to a standard location, which automatically added to your $PATH during uv installation.

On macOS and Linux, this is usually ~/.local/bin.

# Installs to $(uv tool dir)/pan-mcp-relay
uv tool install pan-mcp-relay@latest

# Executable symlinked to $(uv tool dir --bin)/pan-mcp-relay
pan-mcp-relay --help

Install the bleeding edge development version

uv tool install https://github.com/PaloAltoNetworks/aisecurity-mcp-relay.git
pan-mcp-relay --help

Upgrade

If you're using uvx pan-mcp-relay@latest, you're already using the latest version.

Update the installed version with

uv tool install --upgrade pan-mcp-relay

1. Install or Upgrade pan-mcp-relay using uv: uv tool install --upgrade pan-mcp-relay
2. Create an mcp-relay.yaml configuration file containing:
3. Prisma AIRS API Configuration
   • Prisma AIRS API Key
   • Prisma AIRS AI Profile
   • [Prisma AIRS API Endpoint] (Optional, defaults to United States Prisma AIRS API Endpoint.)
4. MCP Servers
   • Supports stdio, SSE, and Streamable HTTP MCP Servers.
5. Run the MCP Relay Server

Configuration

MCP Relay Server Configuration

Configuration Precedence

1. CLI Flags
2. Environment Variables
3. .env file variables
4. Configuration File

pan-mcp-relay supports loading a configuration file via --config-file flag, MCP_RELAY_CONFIG_FILE environment variable, or detecting a configuration file on a set of pre-determined locations:

• --config-file (-c) CLI flag
• MCP_RELAY_CONFIG_FILE environment variable
• ./mcp-relay.yaml
• ~/.mcp-relay.yaml
• ~/.config/pan-mcp-relay/mcp-relay.yaml
• ./mcp-relay.json
• ~/.mcp-relay.json
• ~/.config/pan-mcp-relay/mcp-relay.json

Configuration File Format

An example MCP Relay Server configuration is available in the repository in examples/config/mcp-relay.yaml

Copy or create a new mcp-relay.yaml file. The only required section is mcpServers: {}.

# mcpRelay section is optional.
# Specify API Key, AI Profile and API Endpoint via CLI flags or environment variables.
mcpRelay:
  # Prisma AIRS API Key (required), environment variables supported
  apiKey: |
    ${PRISMA_AIRS_API_KEY}
  # Prisma AIRS AI Profile Name or ID (required), environment variables supported
  aiProfile: |
    your-ai-profile-name-or-id
  # Endpoint Optional, default shown
  # endpoint: |
  #  https://service.api.aisecurity.paloaltonetworks.com

# mcpServers section requires at least one MCP Server.
mcpServers:
  # Example / demo MCP Servers
  homebrew:
    command: brew
    args:
      - mcp-server
    # Optional working directory, supports environment variables
    cwd: "${HOMEBREW_PREFIX}"
    # optional environment variables, inherited from the parent shell
    env:
      HOMEBREW_NO_ENV_HINTS: 1
  fetch:
    command: uvx
    args:
      - mcp-server-fetch

  # filesystem:
  #   command: npx
  #   args:
  #     - -y
  #     - '@modelcontextprotocol/server-filesystem'
  #     - /var/tmp/change/this/path
  #     # Command line arguments support environment variables
  #     - "${XDG_PICTURES_DIR}"

Environment Variables

In addition to CLI flags and the configuration file, pan-mcp-relay supports setting configuration through the following environment variables:

# Required for Prisma AIRS API
PRISMA_AIRS_API_KEY=YOUR_API_KEY
# Required for Prisma AIRS API
PRISMA_AIRS_AI_PROFILE=YOUR_AI_PROFILE_NAME

# Optional, default is https://service.api.aisecurity.paloaltonetworks.com
PRISMA_AIRS_API_ENDPOINT=https://service.api.aisecurity.paloaltonetworks.com
# See https://pan.dev/prisma-airs/scan/api/#scan-api-endpoints for additional regional API endpoints

# Defaults shown for all other Environment Variables
MCP_RELAY_CONFIG_FILE=~/.config/pan-mcp-relay/mcp-relay.yaml
MCP_RELAY_TRANSPORT=stdio
# Host For SSE Transport Mode
MCP_RELAY_HOST=127.0.0.1
# Port for SSE Transport Mode
MCP_RELAY_TOOL_CACHE_TTL=86400
MCP_RELAY_MAX_SERVERS=32
MCP_RELAY_MAX_TOOLS=256
# Path to optional .env file
MCP_RELAY_DOTENV=
# Supports $PATH-style colon-separated list and environment variables. Directory entries will search for a file named `.env`
# MCP_RELAY_DOTENV=$HOME/.env:~/.config/pan-mcp-relay:$PWD

MCP_RELAY_LOG_LEVEL=INFO

MCP Client Configuration

Create a new config file mcp-relay.json to use with your MCP Client (IDE, Chat Client, or Agent).

{
  "mcpServers": {
    "pan-mcp-relay": {
      "command": "uvx",
      "args": [
        "pan-mcp-relay@latest"
      ]
    }
  }
}

For faster startup times, install/upgrade pan-mcp-relay using uv tool install --upgrade pan-mcp-relay, and use the command name directly:

{
  "mcpServers": {
    "pan-mcp-relay": {
      "command": "pan-mcp-relay"
    }
  }
}

[!CAUTION]

pan-mcp-relay should be the only MCP Server listed in your MCP Client configuration file.

Any other MCP Servers listed here will NOT be visible to the security capabilities of the MCP Relay.

Optionally, specify additional environment variables or CLI flags:

{
  "mcpServers": {
    "pan-mcp-relay": {
      "command": "uvx",
      "args": [
        "pan-mcp-relay",
        "--config-file",
        "~/.config/pan-mcp-relay/mcp-relay.yaml"
      ],
      "env": {
        "PRISMA_AIRS_AI_PROFILE": "your-ai-profile",
        "MCP_RELAY_LOG_LEVEL": "WARNING"
      }
    }
  }
}

Transport Options

The MCP Relay Server supports the standard MCP transport mechanisms:

• stdio Transport: For local process communication (default)
• Streamable Transport: For HTTP-based communication, supporting SSE (Server-Sent Events).
• SSE Transport: For backwards compatibility with SSE-only MCP Clients.

Usage

pan-mcp-relay CLI Usage

```terminaloutput pan-mcp-relay --help Usage: pan-mcp-relay [OPTIONS] COMMAND [ARGS]...

Run the MCP Relay Server.

Options: -k, --api-key TEXT Prisma AIRS API Key [PRISMA_AIRS_API_KEY=] -e, --api-endpoint TEXT Prisma AIRS API Endpoint [PRISMA_AIRS_API_ENDPOINT=] -p, --ai-profile TEXT Prisma AIRS AI Profile Name or ID [PRISMA_AIRS_AI_PROFILE=] -c, --config-file FILE Path to configuration file (yaml, json) [MCP_RELAY_CONFIG_FILE=] -t, --transport [stdio|sse|http] Transport protocol to use [MCP_RELAY_TRANSPORT=] [default: stdio] -h, --host TEXT