cortex-mcp

Servidor MCP (Model Context Protocol) para Cortex XDR de Palo Alto Networks. Permite que un asistente como Claude Code / Claude Desktop consulte y opere tu tenant de Cortex en lenguaje natural: casos, incidentes, alertas, endpoints, vulnerabilidades, XQL, threat hunting, IOCs y políticas.

Toda la API REST de Cortex XDR está cubierta a través de la herramienta cortex_send_request (path + request_data). El servidor también expone el recurso cortex-xdr://reference/rest-api con el índice de endpoints oficiales y las reglas de oro de la API.

⚡ Requisitos previos

• Python 3.12 o superior — comprueba con python --version.

• Claude Code instalado (claude --version).

• Git.

• Una API Key de Cortex XDR (más abajo se explica cómo obtenerla).

Related MCP server: Purple AI MCP Server

1. Clona el repositorio

git clone https://github.com/Larkfen/cortex-mcp-clean.git
cd cortex-mcp-clean

🤖 2. Instalación automática con Claude Code (recomendado)

La forma más simple: deja que Claude lo instale y configure por ti mientras miras. Abre Claude Code dentro de la carpeta del repo y pégale este prompt — Claude te irá pidiendo lo que necesite (credenciales, etc.):

Quiero que instales y configures este MCP de Cortex XDR (estás en la raíz del repo) para usarlo desde Claude Code. Haz esto paso a paso:

1. Verifica que tengo Python 3.12+ (python --version). Si no, avísame.
2. Crea un entorno virtual .venv en esta carpeta e instala las dependencias con "pip install ." (o "poetry install" si detectas Poetry). Detecta si estoy en Windows o Linux/macOS y usa los comandos correctos.
3. Pídeme estos tres datos de mi tenant de Cortex XDR (no los inventes):
   - URL base del tenant, formato https://api-<tenant>.xdr.<region>.paloaltonetworks.com
   - API Key ID (el número de la key)
   - API Key (el secreto)
   Recomiéndame usar una key "Advanced" por seguridad; asume Advanced salvo que te diga explícitamente que es Standard.
4. Registra el servidor MCP llamado "cortex-xdr" con `claude mcp add`, donde:
   - command = el python del .venv que creaste
   - args = <ruta-al-repo>/src/main.py
   - cwd = la raíz del repo
   - env = CORTEX_MCP_PAPI_URL, CORTEX_MCP_PAPI_AUTH_ID, CORTEX_MCP_PAPI_AUTH_HEADER, CORTEX_MCP_AUTH_TYPE=advanced y MCP_TRANSPORT=stdio.
   - Si te confirmo que mi key es Standard, usa CORTEX_MCP_AUTH_TYPE=standard.
5. Verifica con /mcp que "cortex-xdr" quede como connected y lístame las tools disponibles.

Reglas: nunca muestres ni subas mi API Key en texto plano fuera de la configuración local del MCP. Si algo falla, muéstrame el error exacto y cómo corregirlo.

Eso es todo: Claude crea el entorno, te pide las credenciales, registra el MCP y verifica que quede conectado. 👉 ¿Aún no tienes la API Key de Cortex? Míralo en el Paso 2 de la instalación manual. Si prefieres hacerlo tú a mano, sigue la sección de abajo.

🔧 Instalación manual (paso a paso)

Si prefieres control total, o quieres entender qué hace el prompt, estos son los mismos pasos a mano. El MCP corre como un proceso local de Python (transport stdio); no necesitas Docker.

Paso 1 — Crear el entorno virtual e instalar dependencias

Un entorno virtual (.venv) es una carpeta aislada con su propio Python y sus librerías, para que las dependencias de este MCP no choquen con el resto de tu sistema. Se crea una sola vez.

Windows (PowerShell):

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install .

Linux / macOS:

python3 -m venv .venv
source .venv/bin/activate
pip install .

Alternativa con Poetry (si lo usas): poetry install en vez de pip install ..

Al terminar, la ruta del intérprete de Python del entorno será:

• Windows: <ruta-al-repo>\.venv\Scripts\python.exe

• Linux/macOS: <ruta-al-repo>/.venv/bin/python

Guarda esa ruta; la usarás en el Paso 3.

Paso 2 — Obtener las credenciales de la API de Cortex XDR

En la consola de Cortex XDR:

1. Ve al menú de configuración: Settings (⚙️) → Configurations → Integrations → API Keys.

2. Haz clic en + New Key.

3. Elige el tipo de key:

   • Advanced ✅ (recomendado, por seguridad) — cada petición se firma con un nonce + timestamp y un hash SHA-256, de modo que la API Key nunca viaja en texto plano y se protege contra ataques de replay.

   • Standard — envía la key directamente en el header. Úsala solo si no puedes usar Advanced.

4. Asigna un Role con los permisos que necesites y guarda.

5. Cortex te mostrará la API Key (secreto) — cópiala ahora, solo se muestra una vez.

6. En la tabla de API Keys, anota el ID de la key (un número, p. ej. 1, 6, …).

También necesitas la URL base (FQDN) de tu tenant. La encuentras en el botón "Copy examples" al crear la key, o en la misma página de API Keys. Tiene esta forma:

https://api-<tu-tenant>.xdr.<region>.paloaltonetworks.com

(el prefijo api- es obligatorio; <region> suele ser us, eu, etc.)

En resumen, del Paso 2 sacas estos datos:

Recomendación de seguridad: usa siempre una key Advanced y configura CORTEX_MCP_AUTH_TYPE=advanced. Solo si usas una key Standard cambia este valor a standard.

Paso 3 — Registrar el MCP en Claude Code

Tienes dos formas equivalentes. Usa una.

Opción A — Comando claude mcp add (rápido)

Ejecuta esto reemplazando las rutas y credenciales por las tuyas. En Windows usa \ en las rutas.

claude mcp add cortex-xdr \
  --env CORTEX_MCP_PAPI_URL=https://api-<tu-tenant>.xdr.us.paloaltonetworks.com \
  --env CORTEX_MCP_PAPI_AUTH_ID=<tu_api_key_id> \
  --env CORTEX_MCP_PAPI_AUTH_HEADER=<tu_api_key> \
  --env CORTEX_MCP_AUTH_TYPE=advanced \
  --env MCP_TRANSPORT=stdio \
  -- <ruta-al-repo>/.venv/bin/python <ruta-al-repo>/src/main.py

Opción B — Editar el archivo de configuración MCP

Añade este bloque a tu configuración MCP (el .mcp.json del proyecto, o la config de usuario de Claude Code):

{
  "mcpServers": {
    "cortex-xdr": {
      "command": "<ruta-al-repo>/.venv/bin/python",
      "args": ["<ruta-al-repo>/src/main.py"],
      "cwd": "<ruta-al-repo>",
      "env": {
        "CORTEX_MCP_PAPI_URL": "https://api-<tu-tenant>.xdr.us.paloaltonetworks.com",
        "CORTEX_MCP_PAPI_AUTH_ID": "<tu_api_key_id>",
        "CORTEX_MCP_PAPI_AUTH_HEADER": "<tu_api_key>",
        "CORTEX_MCP_AUTH_TYPE": "advanced",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Windows: el command es <ruta-al-repo>\.venv\Scripts\python.exe y las rutas llevan \\ (doble) o /. Importante: incluye siempre cwd apuntando a la raíz del repo, para que se carguen también las tools custom (XQL, block list, etc.).

Paso 4 — Verificar que funciona

1. Abre Claude Code en la carpeta del proyecto y ejecuta el comando /mcp.

2. Debe aparecer cortex-xdr como connected.

3. Prueba pidiéndole algo simple, por ejemplo:

   "Usa la tool de Cortex para traer la información del tenant (get_tenant_info)."

4. Si conecta pero no ves las tools custom, revisa que el cwd apunte a la raíz del repo (Paso 3).

En los logs del servidor deberías ver algo como OpenAPI spec loaded with N path(s).

🧠 Skill incluida — investigación + dashboard

El repo trae un skill de Claude Code en .claude/skills/cortex-xdr-triage/ que le enseña a Claude cómo usar el MCP bien y con pocos tokens, sin tener que explicárselo cada vez.

Con el skill activo, puedes pedir en lenguaje natural cosas como "revisa los casos abiertos y dime qué requiere atención" y Claude:

1. Lista y prioriza los incidentes/casos abiertos (por score y severidad).

2. Investiga cada caso prioritario: usuario, equipo/host, qué lo gatilló, qué ha pasado (timeline + MITRE ATT&CK) y cómo mitigarlo (con las tools reales).

3. Si lo pides, genera un dashboard SOC oscuro (Artifact) estilo consola de Palo Alto, usando la plantilla incluida en assets/.

Guardas de seguridad del skill: las tools de lectura corren libres; cualquier acción de contención o cambio (aislar, bloquear, cuarentena, cerrar casos) se confirma contigo antes de ejecutarse.

Cómo activar el skill

• Dentro del repo: al abrir Claude Code en esta carpeta, el skill se detecta automáticamente (.claude/skills/).

• Para usarlo en cualquier proyecto: copia la carpeta a tu config de usuario:

# Linux/macOS
cp -r .claude/skills/cortex-xdr-triage ~/.claude/skills/

# Windows
Copy-Item -Recurse .claude\skills\cortex-xdr-triage "$env:USERPROFILE\.claude\skills\"

Instalación automática vs Skill: la instalación automática (el prompt de arriba) sirve para dejar el MCP funcionando; el skill es para usarlo (investigar y generar dashboards). Son complementarios.

🧰 Tools que expone este MCP

El servidor une automáticamente las especificaciones OpenAPI de:

• builtin_components/ — herramientas base: get_issues, get_cases, get_assets, get_filtered_endpoints, get_vulnerabilities, get_tenant_info, etc.

• custom_components/ — herramientas añadidas en este repo: block_list_add_files, xql_run_query, xql_get_results, get_policy_list, además de casos/incidentes/alertas, endpoint actions, threat hunting, IOCs, wildfire y políticas.

• remote_components/ — componentes descargados con el comando de actualización del CLI (opcional).

Para que se vean las tools custom, el servidor debe arrancarse desde el directorio del proyecto (por eso el cwd en la config).

🩺 Solución de problemas

🛠️ Desarrollo

Estructura del proyecto

src/
├── cli.py                  # Interfaz de línea de comandos
├── main.py                 # Punto de entrada del servidor MCP
├── config/                 # Configuración
├── entities/               # Modelos de datos y recursos
├── pkg/                    # Utilidades internas y cliente PAPI
├── service/                # Capa de servicio (servidor MCP)
└── usecase/                # Lógica de negocio (tools)
    ├── builtin_components/ # Tools base (con OpenAPI)
    ├── custom_components/  # Tools añadidas en este repo
    └── remote_components/  # Tools distribuidas/actualizadas por Cortex

Comandos

poetry run pytest          # tests
poetry run black .         # formato
poetry run isort .         # orden de imports

Para depurar un MCP, lo mejor es el MCP inspector.

🐳 Docker (opcional)

Solo si prefieres contenedor en vez del método local. Crea un .env (copia .env.example) y:

docker build -t cortex-mcp .

Registro en el cliente MCP:

{
  "mcpServers": {
    "cortex-xdr": {
      "command": "docker",
      "args": ["run", "--env-file", "/ruta/a/.env", "-i", "--rm", "cortex-mcp"]
    }
  }
}

📄 Licencia

Ver LICENSE. Este proyecto se basa en la implementación oficial de Palo Alto Networks; revisa los términos antes de redistribuir.