Palo Alto Networks MCP Security Relay

A security-enhanced Model Context Protocol (MCP) relay server that acts as an intermediary between clients and downstream MCP servers, providing security scanning and centralized orchestration capabilities.

• Palo Alto Networks MCP Security Relay
• Overview
• Installation and Setup
• Configuration
  • Environment Variables
  • Server Configuration
  • Transport Options
• Usage
  • pan-mcp-relay CLI Usage
  • Running the Relay Server
    • stdio transport (default)
    • SSE transport
    • Command Line Arguments
• Examples
  • Stdio Client Example
  • SSE Client Example Configuration
• Legal

Overview

The MCP Security Relay provides a security-enhanced intermediary layer for Model Context Protocol communications

• Security scanning of tool requests and responses using integrated AI security services
• Tool registry management with deduplication, caching, and state management
• Multiserver orchestration supporting multiple downstream MCP servers
• Hidden mode support for bypassing security scans on trusted servers
• Automatic tool discovery and registration from configured downstream servers

Installation and Setup

This project uses uv.

1. Install or Update uv https://docs.astral.sh/uv/getting-started/installation/
2. Update uv if already installed: uv self update
3. Clone this repository.
4. Install the project dependencies using uv sync
5. Create the MCP Relay Configuration File
6. Run the MCP Relay Server

git clone https://github.com/paloaltonetworks/aisecurity-mcp-relay.git

cd aisecurity-mcp-relay

uv sync

# .local/ directory is git-ignored, you may use it for your custom configuration
cp examples/config/config-example.json .local/config.json

Configuration

Environment Variables

Create a .env file in the git repo root with the following variables:

# Required for Palo Alto Networks AI Security scanning
PANW_AI_PROFILE_NAME=YOUR_AI_PROFILE_NAME
PANW_AI_SEC_API_KEY=YOUR_API_KEY
PANW_AI_SEC_API_ENDPOINT=YOUR_API_ENDPOINT

Server Configuration

Copy or create a new config.json file. Configure downstream MCP servers in config.json:

{
  "mcpServers": {
    "example-server": {
      "command": "node",
      "args": ["path/to/server/index.js"]
    },
    "another-server": {
      "command": "python",
      "args": ["path/to/another/server.py"]
    }
  }
}

Note:

• MCP Relay only supports local MCP servers currently.

Transport Options

The relay supports two transport mechanisms:

• STDIO Transport: For local process communication (default)
• SSE Transport: For HTTP-based communication using Server-Sent Events

Usage

pan-mcp-relay CLI Usage

usage: pan-mcp-relay [-h] --config-file CONFIG_FILE [--transport {stdio,sse}] [--host HOST] [--port PORT]
                     [--tool-registry-cache-expiry-in-seconds TOOL_REGISTRY_CACHE_EXPIRY_IN_SECONDS] [--max-mcp-servers MAX_MCP_SERVERS]
                     [--max-mcp-tools MAX_MCP_TOOLS]

options:
  -h, --help            show this help message and exit
  --config-file CONFIG_FILE
                        Path to config file
  --transport {stdio,sse}
                        Transport protocol to use
  --host HOST           Host for SSE server
  --port PORT           Port for SSE server
  --tool-registry-cache-expiry-in-seconds TOOL_REGISTRY_CACHE_EXPIRY_IN_SECONDS
                        Downsteam mcp tool registry cache expiry
  --max-mcp-servers MAX_MCP_SERVERS
                        Max number of downstream servers
  --max-mcp-tools MAX_MCP_TOOLS
                        Max number of MCP tool

Running the Relay Server

stdio transport (default)

# Run with STDIO transport (default)
uv run pan-mcp-relay \
  --config-file=config.json

SSE transport

# Run with SSE transport
uv run pan-mcp-relay \
  --config-file=config.json \
  --transport=sse \
  --host=127.0.0.1 \
  --port=8000

Command Line Arguments

Argument	Required	Default	Description
--config-file	✅	-	Path to the JSON configuration file containing MCP server definitions
--transport	❌	stdio	Transport protocol to use. Options: stdio (local process communication) or sse (HTTP Server-Sent Events)
--host	❌	127.0.0.1	Host address for SSE transport server (only used when --transport=sse)
--port	❌	8000	Port number for SSE transport server (only used when --transport=sse)
--tool-registry-cache-expiry-in-seconds	❌	300	Cache expiry time in seconds for the downstream MCP tool registry. Tools are re-scanned when cache expires
--max-mcp-servers	❌	32	Maximum number of downstream MCP servers that can be configured. Prevents resource exhaustion
--max-mcp-tools	❌	64	Maximum total number of MCP tools across all downstream servers. Enforces tool registry limits

Examples

Stdio Client Example

This example demonstrates how to run the interactive client to communicate with the relay server using stdio.

1. Run the Interactive Client:

Run the pan_security_relay_stdio_client.py script. This script connects to the running relay and provides an interactive command prompt.

python examples/clients/stdio/pan_security_relay_stdio_client.py \
  --relay-module=pan_aisecurity_mcp_relay.main \
  --config-file=config.json

2. Interact with the Client:

Once the client starts, you can use the following commands to interact with the downstream MCP servers through the relay:

• list: Displays all available tools from the downstream servers.
• call <tool_name> [json_arguments]: Executes a specific tool with the provided arguments. For example, call list_downstream_servers_info.
• servers: Shows a list of all configured downstream servers and their tools.
• quit: Exits the interactive client.

Using these commands, you can test and debug the MCP relay and its connected downstream servers.

SSE Client Example Configuration

To connect a client to the relay server when it's running in SSE mode, you need to first start the relay server with the transport set to sse.

1. Start the Relay Server in SSE Mode:

uv run pan-mcp-relay \
  --config-file=config/config-example.json \
  --transport=sse \
  --host=127.0.0.1 \
  --port=8000

2. Configure Your Client:

Then, in your client's configuration (for example, in a config.json or a similar file), add the following to connect to the SSE endpoint of the relay:

{
  "mcpServers": {
    "pan_security_relay_SSE": {
      "type": "sse",
      "baseUrl": "http://127.0.0.1:8000/sse"
    }
  }
}

This configuration tells your client how to find and communicate with the MCP Security Relay using the SSE protocol.

Legal

Copyright (c) 2025, Palo Alto Networks

Licensed under the Polyform Internal Use License 1.0.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at:

https://polyformproject.org/licenses/internal-use/1.0.0

(or)

https://github.com/polyformproject/polyform-licenses/blob/76a278c4/PolyForm-Internal-Use-1.0.0.md

As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.