Prisma SD-WAN MCP v2

August 10, 2026 · View on GitHub

Registry-first MCP server for Palo Alto Networks Prisma SD-WAN.

How it's built

AI / operator
     |
26 semantic MCP tools -----------------------+
     |                                       |
name/ID resolver + workflow logic     run_commands (ION CLI over SSH)
     |                                       |
registry-driven capability executor   command policy -> address resolution
     |                                  -> reachability probe -> Netmiko
308 generated registry actions               |
+ 8 clearly labeled curated additions       ION device
     |
Prisma SASE SDK

The source registry is not rewritten. It's loaded as the API source of truth, with a small override file layered on top for human aliases and response-safety rules.

AI-visible tool count: 27

The aim is not one tool per API. The aim is one tool per common operator intent, with a controlled escape hatch for rare APIs.

Discovery / resolution (6): find_site, find_element, find_resource, list_capabilities, read_capability, resolve_path
Core network operations (5): get_inventory, get_device_health, get_interfaces, get_topology, get_wan
Routing / diagnostics / monitoring (3): get_routing, get_device_diagnostics, get_monitoring
Policy / security (2): get_policies, get_security
Service/domain families (9): get_network_services, get_multicast, get_ipfix, get_cellular, get_software, get_identity, get_service_connections, get_prisma_access, get_platform
Local automation output (1): generate_site_config
ION CLI passthrough (1): run_commands — the one tool that is not read-only; see below

read_capability provides guarded access to every source-registry action, so an API does not need a dedicated MCP tool to remain available.

Core design principles

Human name -> controller ID resolution.
Exact match preferred over substring match.
Multiple matches are returned; the server never silently picks one.
Element records can supply site_id automatically.
Workflow tools can combine several API calls.
resolve_path never invents a circuit mapping.
Authentication refresh and bounded 429/5xx retries.
Cursor pagination and response byte limits.
Full tool descriptions are shipped to the model.
Compact list output; richer single-object/workflow output.
Local site-config generation remains separate from network mutation.

Every registry-executed response passes through recursive redaction. Keys containing password, secret, token, session ID, private key, passphrase, SNMP community string, and similar values are replaced with [REDACTED].

This is important because the source registry includes schemas that can expose authentication material.

Expert capability gate

The generated registry contains 308 read-only actions. read_capability can execute them by action_id, but it validates:

capability exists;
required path parameters are present;
unknown path parameters are rejected;
POST body is checked against normalized registry schema hints;
response is redacted and size-limited.

Curated registry additions

Eight useful SDK calls are not represented in the generated 308-action registry:

topology
event query
flow monitor
bandwidth monitor metrics
LQM point metrics
probe point metrics
VPN-link status
VPN-link state

They are stored in prisma_sdwan_mcp/data/curated_capabilities.json rather than hidden in tool code. All eight were validated against a live tenant, so read_capability executes them directly. A future curated action added without live validation is blocked by default until it is verified.

See docs/LIVE_VALIDATION.md.

ION CLI passthrough (`run_commands`)

The one tool that reaches the device instead of the controller API, over SSH — and the one tool that is not annotated read-only, because the ping/tcpping/dig diagnostics it permits send real packets from the ION. Everything else it permits (dump, inspect) is display-only; everything not explicitly matched is denied fail-closed, with no deny list. See docs/ION_CLI_RESEARCH.md and the prisma-cli://policy resource for the exact allowed forms.

This is a second, materially different network requirement. The rest of this server only needs outbound HTTPS to the Prisma SASE controller. run_commands additionally needs outbound SSH connectivity from wherever this server runs to each ION's management address. A deployment that has one does not necessarily have the other — a container with no route to branch management networks will get a fast, explicit device_unreachable error rather than a hang or a misleading auth failure.

SSH host-key checking is always strict. The target device's host key must already be present in the known_hosts file before run_commands is called — e.g. via one prior interactive ssh login, or ssh-keyscan. There is no auto-trust, ever, including as a retry after failure.

Credentials are configuration-only. The tool signature is:

run_commands(commands, element=None, host=None, site=None)

Credentials, SSH port and the known_hosts path are read from the server's environment and can never be passed as tool arguments. That is deliberate: a tool argument is authored by the model and lands in the conversation transcript. Set ION_USERNAME plus one of ION_PASSWORD / ION_PRIVATE_KEY; with neither set, every call fails closed with configuration_error before any resolution, probe, or connection is attempted.

Everything else — SSH port, probe/connect/read timeouts, output byte ceiling, commands per batch — has a working default. See docs/CONFIGURATION.md to change one. The older PRISMA_ION_* spellings still work; the short ION_* names are canonical.

Install

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
cp .env.example .env

.env is five settings and no more:

PAN_CLIENT_ID          # controller
PAN_CLIENT_SECRET
PAN_TSG_ID
ION_USERNAME           # device SSH (run_commands); blank disables the tool
ION_PASSWORD

Every other setting has a working default in code. docs/CONFIGURATION.md is the full list if you ever need to change one.

Run

stdio:

prisma-sdwan-mcp --transport stdio

streamable HTTP:

prisma-sdwan-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Docker:

docker build -t prisma-sdwan-mcp .
docker run --rm --env-file .env prisma-sdwan-mcp

Tests included

Dependency-free core tests validate:

registry load/counts;
action references;
name/ID resolution and ambiguity behavior;
generic GET/POST dispatch;
registry schema normalization;
recursive secret redaction;
cursor pagination.

Run (251 tests, no live tenant needed):

PYTHONPATH=. python -m pytest -q

Live tenant/API validation is intentionally separate. Follow docs/LIVE_VALIDATION.md before production cutover.

Device behavior, tested without a device

tests/fixtures/ion/direct_*.txt holds bytes captured verbatim from a live ION 1200 running 6.3.6-b9 — the real ANSI escapes and the doubled command echo included. tests/test_ion_replay.py replays them through the real code path with no device attached, so read-termination and parsing bugs are reproduced and fixed without another trip to the lab.

It needs no marker and no hardware: it runs in the ordinary suite above.

Files to read first

docs/ARCHITECTURE.md
docs/CONFIGURATION.md
docs/TOOL_CATALOG.md
docs/LIVE_VALIDATION.md