xsiam-mcp

A Model Context Protocol server for the Palo Alto Cortex XSIAM REST API.

It exposes the entire XSIAM REST API (129 operations across 26 categories — Incidents, Alerts, Endpoints, Response Actions, XQL, Scripts, IOCs/BIOCs, Assets, Datasets, Dashboards, Playbooks, Correlation Rules, and more) as MCP tools, auto-generated from the official OpenAPI spec so coverage stays complete and accurate. On top of that it adds a few composite tools designed for how AI agents actually work.

• No Docker. Pure Python, launched over stdio by your MCP client.
• Full coverage. One tool per API operation, with resolved JSON Schemas and a ready-to-use request example baked into every tool description.
• Agent-friendly. xsiam_health to sanity-check auth, xsiam_list_operations to discover tools by category, and xql_query that runs an XQL query and polls to completion in a single call.

Install

Using uv (recommended — zero global install):

git clone <this-repo> xsiam-mcp && cd xsiam-mcp
uv venv && uv pip install -e .

Or with pip:

pip install -e .

Verify the tool catalog was generated (no credentials needed):

uv run xsiam-mcp --count      # e.g. "129 generated XSIAM tools (+3 composite)."
uv run xsiam-mcp --list       # print all tools grouped by category

Configuration

All configuration is via environment variables.

Variable	Required	Description
XSIAM_API_KEY	✅	The API key secret.
XSIAM_API_KEY_ID	✅	The numeric key ID (sent as x-xdr-auth-id).
XSIAM_FQDN	✅*	Tenant FQDN, e.g. myco.xdr.us.paloaltonetworks.com. Base URL becomes https://api-<fqdn>.
XSIAM_BASE_URL	✅*	Full API gateway URL; overrides XSIAM_FQDN.
XSIAM_AUTH_TYPE		standard (default) or advanced.
XSIAM_TOOLSETS		Comma-separated tag names to expose (default: all). e.g. Incidents,XQL query,Response Action.
XSIAM_TIMEOUT		Per-request timeout in seconds (default 60).
XSIAM_VERIFY_TLS		false to disable TLS verification (default true).

* Provide either XSIAM_FQDN or XSIAM_BASE_URL.

Getting credentials

In the XSIAM console go to Settings → Configurations → Integrations → API Keys, click New Key, choose Standard or Advanced, assign a role, and save. Copy the API Key (secret) and its ID, and grab the FQDN from the same page.

• Standard key → set XSIAM_AUTH_TYPE=standard (default). The key is sent directly in the Authorization header.
• Advanced key → set XSIAM_AUTH_TYPE=advanced. The server generates a nonce + timestamp and sends Authorization as the SHA-256 of api_key + nonce + timestamp, per XSIAM's advanced auth scheme.

The API key's assigned role determines which operations succeed. A read-only key will get 403 on write operations — that's expected.

MCP client configuration

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json)

{
  "mcpServers": {
    "xsiam": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/xsiam-mcp", "run", "xsiam-mcp"],
      "env": {
        "XSIAM_API_KEY": "your-api-key-secret",
        "XSIAM_API_KEY_ID": "42",
        "XSIAM_FQDN": "myco.xdr.us.paloaltonetworks.com",
        "XSIAM_AUTH_TYPE": "standard"
      }
    }
  }
}

To scope the toolset down (fewer tools = easier for the agent), add e.g. "XSIAM_TOOLSETS": "Incidents,Response Action,XQL query" to env.

XSIAM_TOOLSETS is a visibility filter — it controls which tools are advertised to the agent to reduce noise. It is not a security boundary: the API key's assigned role is what authorises each call server-side. Scope permissions with the key's role, not this variable.

Usage tips for agents

1. Call xsiam_health first to confirm connectivity and auth.
2. Use xsiam_list_operations (optionally with a tag filter like "incident" or "endpoint") to find the right tool.
3. For data investigation, prefer xql_query — it starts the query and polls for results in one shot.
4. Every generated tool's description contains a concrete example body. Most list/read endpoints accept {"request_data": {}} to return everything.

Development

uv pip install -e ".[dev]"
uv run pytest -q

The API surface is defined by src/xsiam_mcp/data/openapi.json. To update coverage when the XSIAM spec changes, drop in a new spec file — tools regenerate automatically, no code changes required.