Servidor MCP de Vectra AI

Este proyecto implementa un servidor MCP para la Plataforma Vectra AI.

¿Qué es Vectra AI MCP?

Un servidor MCP que conecta asistentes de IA a su plataforma de seguridad Vectra AI, permitiendo el análisis inteligente de datos de detección de amenazas, información de seguridad y flujos de trabajo automatizados de respuesta a incidentes. Compatible con Claude, ChatGPT, Cursor, VS Code y otras herramientas de IA habilitadas para MCP.

¿Qué puede hacer con Vectra AI MCP?

• Investigar amenazas en lenguaje natural

• Tomar medidas de respuesta en Vectra directamente desde su agente de IA

• Correlacionar y analizar datos de seguridad mediante prompts

• Crear dinámicamente visualizaciones avanzadas para el análisis

• Generar informes de investigación a partir de lenguaje natural

Configuración - Hospedaje local

Requisitos previos

1. Instalar Python Consulte el archivo .python-version para conocer la versión requerida

2. Instalar uv - Gestor de paquetes de Python

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv

Pasos de configuración

1. Clonar/Descargar el proyecto en su máquina local

2. Navegar al directorio del proyecto:

cd your-project-directory

3. Configurar credenciales:

Opción A: Inquilino único (archivo .env)

# Copy the example environment file
cp .env.example .env

Luego, edite el archivo .env con sus credenciales reales de la Plataforma Vectra AI. Variables requeridas a actualizar:

• VECTRA_BASE_URL: La URL de su portal de Vectra

• VECTRA_CLIENT_ID: Su ID de cliente de Vectra

• VECTRA_CLIENT_SECRET: Su secreto de cliente de Vectra

Opción B: Múltiples inquilinos (configuración YAML)

Si tiene varios inquilinos de Vectra, utilice un archivo de configuración YAML en su lugar:

cp tenants.yaml.example tenants.yaml

Luego, edite tenants.yaml con los detalles de sus inquilinos:

tenants:
  - name: prod
    base_url: https://prod-tenant.uw2.portal.vectra.ai
    client_id: "<prod-client-id>"
    client_secret: "<prod-client-secret>"

  - name: staging
    base_url: https://staging-tenant.uw2.portal.vectra.ai
    client_id: "<staging-client-id>"
    client_secret: "<staging-client-secret>"

Cada inquilino obtiene su propio conjunto de herramientas con el prefijo del nombre del inquilino (por ejemplo, prod_list_detections, staging_list_detections). También se añade una meta-herramienta list_tenants para descubrir los inquilinos disponibles.

Los valores por inquilino se pueden sobrescribir mediante variables de entorno utilizando el patrón VECTRA_TENANT_<NAME>_<FIELD> (por ejemplo, VECTRA_TENANT_PROD_CLIENT_SECRET). Esto es útil para Docker/Kubernetes donde los secretos no deben almacenarse en archivos.

4. Crear y activar un entorno virtual:

uv venv

# Activate it:
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

5. Instalar dependencias:

uv sync

Esto instalará todas las dependencias especificadas en pyproject.toml utilizando las versiones exactas de uv.lock.

6. Ejecutar la aplicación:

El servidor admite múltiples protocolos de transporte:

# Run with stdio transport (default, for Claude Desktop)
python server.py
python server.py --transport stdio

# Run with SSE transport (for HTTP-based MCP clients)
python server.py --transport sse --host 0.0.0.0 --port 8000

# Run with streamable-http transport (for production HTTP deployments)
python server.py --transport streamable-http --host 0.0.0.0 --port 8000

# Run with multi-tenant YAML config
python server.py --config tenants.yaml
python server.py -c tenants.yaml --transport sse

# Enable debug logging
python server.py --debug

Opciones de transporte:

• stdio: Comunicación de entrada/salida estándar (predeterminado, utilizado por Claude Desktop)

• sse: Eventos enviados por el servidor (Server-Sent Events) sobre HTTP (bueno para clientes basados en web)

• streamable-http: Transporte HTTP transmitible (recomendado para despliegues HTTP en producción)

Variables de entorno: También puede configurar el servidor utilizando variables de entorno:

export VECTRA_MCP_TRANSPORT=streamable-http
export VECTRA_MCP_HOST=0.0.0.0
export VECTRA_MCP_PORT=8000
export VECTRA_MCP_DEBUG=true
python server.py

Configuración de MCP para Claude Desktop

7. Añadir el servidor MCP a Claude Desktop:

# On macOS:
# Open Claude Desktop configuration file
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# On Windows:
# Open Claude Desktop configuration file
notepad %APPDATA%/Claude/claude_desktop_config.json

Añada la siguiente configuración a la sección mcpServers (actualice las rutas para que coincidan con su configuración):

Inquilino único:

{
  "mcpServers": {
    "vectra-ai-mcp": {
      "command": "/path/to/your/uv/binary",
      "args": [
        "--directory",
        "/path/to/your/project/directory",
        "run",
        "server.py"
      ]
    }
  }
}

Multi-inquilino:

{
  "mcpServers": {
    "vectra-ai-mcp": {
      "command": "/path/to/your/uv/binary",
      "args": [
        "--directory",
        "/path/to/your/project/directory",
        "run",
        "server.py",
        "--config",
        "tenants.yaml"
      ]
    }
  }
}

8. Depuración - Encontrar la ruta de instalación de uv:

# Find where uv is installed
which uv
# or
where uv

9. Depuración - Obtener la ruta absoluta de su proyecto:

# From your project directory, run:
pwd

10. Reiniciar Claude Desktop para cargar la nueva configuración del servidor MCP.

Configuración de otros clientes MCP

Una vez configurado, debería poder utilizar las capacidades de la Plataforma Vectra AI directamente dentro de Claude Desktop u otros clientes MCP a través de este servidor MCP.

Para otros clientes MCP además de Claude Desktop, consulte los enlaces de documentación a continuación:

Para otros clientes MCP, consulte su documentación respectiva. El patrón general es similar: deberá especificar el comando y los argumentos para ejecutar el servidor MCP con la misma estructura de configuración.

Configuración - Despliegue con Docker

Para despliegues en producción o una configuración más sencilla, puede ejecutar el servidor MCP de Vectra AI utilizando Docker. Ofrecemos dos opciones:

Opción 1: Uso de imágenes preconstruidas (Recomendado)

La forma más fácil de empezar es utilizar nuestras imágenes de Docker preconstruidas desde el Registro de Contenedores de GitHub.

Requisitos previos

• Docker Desktop o Docker Engine

Pasos de inicio rápido

1. Configurar variables de entorno:

# Copy the example environment file
cp .env.example .env

Luego, edite el archivo .env con sus credenciales reales de la Plataforma Vectra AI.

2. Ejecutar con la imagen preconstruida:

Transporte HTTP transmitible (Recomendado para producción)

docker run -d \
  --name vectra-mcp-server-http \
  --env-file .env \
  -e VECTRA_MCP_TRANSPORT=streamable-http \
  -e VECTRA_MCP_HOST=0.0.0.0 \
  -e VECTRA_MCP_PORT=8000 \
  -p 8000:8000 \
  --restart unless-stopped \
  ghcr.io/vectra-ai-research/vectra-ai-mcp-server:latest

Transporte SSE (Eventos enviados por el servidor)

docker run -d \
  --name vectra-mcp-server-sse \
  --env-file .env \
  -e VECTRA_MCP_TRANSPORT=sse \
  -e VECTRA_MCP_HOST=0.0.0.0 \
  -e VECTRA_MCP_PORT=8000 \
  -p 8000:8000 \
  --restart unless-stopped \
  ghcr.io/vectra-ai-research/vectra-ai-mcp-server:latest

Transporte Stdio (Para clientes MCP locales)

docker run -d \
  --name vectra-mcp-server-stdio \
  --env-file .env \
  -e VECTRA_MCP_TRANSPORT=stdio \
  --restart unless-stopped \
  ghcr.io/vectra-ai-research/vectra-ai-mcp-server:latest

3. O utilizar Docker Compose (Alternativa):

Cree un archivo docker-compose.yml:

version: '3.8'
services:
  vectra-mcp-server:
    image: ghcr.io/vectra-ai-research/vectra-ai-mcp-server:latest
    container_name: vectra-mcp-server
    env_file: .env
    environment:
      - VECTRA_MCP_TRANSPORT=streamable-http
      - VECTRA_MCP_HOST=0.0.0.0
      - VECTRA_MCP_PORT=8000
    ports:
      - "8000:8000"
    restart: unless-stopped

Luego ejecute:

docker-compose up -d

Etiquetas disponibles:

• latest: Última compilación estable de la rama principal

• main: Última compilación de la rama principal (igual que latest)

• v*: Etiquetas de versión específica (por ejemplo, v1.0.0)

💡 Consejo: Las imágenes preconstruidas se compilan y publican automáticamente a través de GitHub Actions cada vez que se envía código a la rama principal o cuando se etiquetan versiones. Esto garantiza que siempre obtenga la última versión probada sin necesidad de compilar localmente.

Opción 2: Compilar desde el código fuente

Para desarrollo o personalización, puede compilar la imagen de Docker desde el código fuente.

Requisitos previos

1. Instalar Docker y Docker Compose

   • Docker Desktop (incluye Docker Compose)

   • O instale Docker Engine y Docker Compose por separado en Linux

Pasos para compilar desde el código fuente

1. Clonar/Descargar el proyecto en su máquina local

2. Navegar al directorio del proyecto:

cd your-project-directory

3. Configurar variables de entorno:

# Copy the example environment file
cp .env.example .env

Luego, edite el archivo .env con sus credenciales reales de la Plataforma Vectra AI.

4. Compilar y ejecutar con Docker:

# Build the image
docker build -t vectra-mcp-server .

5. Ejecutar la imagen compilada localmente:

Elija su modo de transporte y ejecute con la imagen compilada localmente:

Transporte HTTP transmitible

docker run -d \
  --name vectra-mcp-server-http \
  --env-file .env \
  -e VECTRA_MCP_TRANSPORT=streamable-http \
  -e VECTRA_MCP_HOST=0.0.0.0 \
  -e VECTRA_MCP_PORT=8000 \
  -p 8000:8000 \
  --restart unless-stopped \
  vectra-mcp-server

Transporte SSE

docker run -d \
  --name vectra-mcp-server-sse \
  --env-file .env \
  -e VECTRA_MCP_TRANSPORT=sse \
  -e VECTRA_MCP_HOST=0.0.0.0 \
  -e VECTRA_MCP_PORT=8000 \
  -p 8000:8000 \
  --restart unless-stopped \
  vectra-mcp-server

Transporte Stdio

docker run -d \
  --name vectra-mcp-server-stdio \
  --env-file .env \
  -e VECTRA_MCP_TRANSPORT=stdio \
  --restart unless-stopped \
  vectra-mcp-server

Configuración multi-inquilino en Docker

Para ejecutar el servidor en modo multi-inquilino con Docker:

1. Cree un archivo tenants.yaml (consulte tenants.yaml.example).

2. Móntelo en el contenedor y establezca VECTRA_CONFIG_FILE:

docker run -d \
  --name vectra-mcp-server \
  -e VECTRA_CONFIG_FILE=/app/tenants.yaml \
  -e VECTRA_MCP_TRANSPORT=streamable-http \
  -e VECTRA_MCP_HOST=0.0.0.0 \
  -e VECTRA_MCP_PORT=8000 \
  -v ./tenants.yaml:/app/tenants.yaml:ro \
  -p 8000:8000 \
  --restart unless-stopped \
  ghcr.io/vectra-ai-research/vectra-ai-mcp-server:latest

Puede inyectar secretos por inquilino a través de variables de entorno en lugar de almacenarlos en el archivo YAML:

docker run -d \
  --name vectra-mcp-server \
  -e VECTRA_CONFIG_FILE=/app/tenants.yaml \
  -e VECTRA_TENANT_PROD_CLIENT_SECRET=<secret> \
  -e VECTRA_TENANT_STAGING_CLIENT_SECRET=<secret> \
  -v ./tenants.yaml:/app/tenants.yaml:ro \
  -p 8000:8000 \
  ghcr.io/vectra-ai-research/vectra-ai-mcp-server:latest

Variables de entorno de Docker

El contenedor Docker admite todas las mismas variables de entorno que la configuración local, además de la configuración adicional del servidor MCP:

Configuración del servidor MCP

• VECTRA_MCP_TRANSPORT: Protocolo de transporte (stdio, sse o streamable-http) - predeterminado: stdio

• VECTRA_MCP_HOST: Host al que vincularse para transportes HTTP - predeterminado: 0.0.0.0

• VECTRA_MCP_PORT: Puerto para transportes HTTP - predeterminado: 8000

• VECTRA_MCP_DEBUG: Habilitar registro de depuración - predeterminado: false

• VECTRA_CONFIG_FILE: Ruta al archivo de configuración YAML para el modo multi-inquilino (opcional)

Variables de sobrescritura multi-inquilino

Al utilizar un archivo de configuración YAML, la configuración por inquilino se puede sobrescribir mediante variables de entorno:

• VECTRA_TENANT_<NAME>_BASE_URL

• VECTRA_TENANT_<NAME>_CLIENT_ID

• VECTRA_TENANT_<NAME>_CLIENT_SECRET

• VECTRA_TENANT_<NAME>_API_VERSION

• VECTRA_TENANT_<NAME>_REQUEST_TIMEOUT

Donde <NAME> es el nombre del inquilino en mayúsculas (por ejemplo, VECTRA_TENANT_PROD_CLIENT_SECRET).

Acceso al servidor HTTP

Al ejecutar con transportes HTTP (sse o streamable-http), el servidor MCP estará disponible en:

• Streamable HTTP: http://localhost:8000/mcp

• SSE: http://localhost:8000/sse

Configuración del cliente MCP para Docker

Para clientes MCP basados en HTTP que se conectan al servidor Dockerizado, utilice el endpoint apropiado:

{
  "mcpServers": {
    "vectra-ai-mcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8000/"
      }
    }
  }
}

Comprobaciones de estado de Docker

El contenedor Docker incluye comprobaciones de estado que verificarán que el servidor se esté ejecutando correctamente:

• Para transporte stdio: Siempre informa como saludable (no hay endpoint HTTP para verificar)

• Para transportes HTTP: Verifica la disponibilidad del endpoint HTTP

Nota: MCP (Model Context Protocol) es una tecnología emergente y en rápida evolución. Tenga precaución al utilizar este servidor y siga las mejores prácticas de seguridad, incluida la gestión adecuada de credenciales y las medidas de seguridad de red.