Vectra AI MCP-Server

Dieses Projekt implementiert einen MCP-Server für die Vectra AI-Plattform.

Was ist Vectra AI MCP?

Ein MCP-Server, der KI-Assistenten mit Ihrer Vectra AI-Sicherheitsplattform verbindet und eine intelligente Analyse von Bedrohungserkennungsdaten, Sicherheitseinblicken und automatisierten Workflows zur Reaktion auf Vorfälle ermöglicht. Kompatibel mit Claude, ChatGPT, Cursor, VS Code und anderen MCP-fähigen KI-Tools.

Was können Sie mit Vectra AI MCP tun?

• Bedrohungen in natürlicher Sprache untersuchen

• Reaktionsmaßnahmen in Vectra direkt von Ihrem KI-Agenten aus ergreifen

• Sicherheitsdaten mithilfe von Prompts korrelieren und analysieren

• Dynamisch erweiterte Visualisierungen für die Analyse erstellen

• Untersuchungsberichte aus natürlicher Sprache generieren

Einrichtung - Lokal hosten

Voraussetzungen

1. Python installieren Überprüfen Sie die Datei .python-version auf die erforderliche Version

2. uv installieren - Python-Paketmanager

# 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

Einrichtungsschritte

1. Projekt klonen/herunterladen auf Ihren lokalen Computer

2. In das Projektverzeichnis navigieren:

cd your-project-directory

3. Anmeldedaten konfigurieren:

Option A: Einzelner Mandant (.env-Datei)

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

Bearbeiten Sie anschließend die .env-Datei mit Ihren tatsächlichen Anmeldedaten für die Vectra AI-Plattform. Erforderliche Variablen, die aktualisiert werden müssen:

• VECTRA_BASE_URL: Ihre Vectra-Portal-URL

• VECTRA_CLIENT_ID: Ihre Client-ID von Vectra

• VECTRA_CLIENT_SECRET: Ihr Client-Geheimnis von Vectra

Option B: Mehrere Mandanten (YAML-Konfiguration)

Wenn Sie mehrere Vectra-Mandanten haben, verwenden Sie stattdessen eine YAML-Konfigurationsdatei:

cp tenants.yaml.example tenants.yaml

Bearbeiten Sie anschließend tenants.yaml mit Ihren Mandantendetails:

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>"

Jeder Mandant erhält seinen eigenen Satz an Tools, die mit dem Mandantennamen versehen sind (z. B. prod_list_detections, staging_list_detections). Ein list_tenants-Meta-Tool wird ebenfalls hinzugefügt, um verfügbare Mandanten zu entdecken.

Werte pro Mandant können über Umgebungsvariablen mit dem Muster VECTRA_TENANT_<NAME>_<FIELD> überschrieben werden (z. B. VECTRA_TENANT_PROD_CLIENT_SECRET). Dies ist nützlich für Docker/Kubernetes, wo Geheimnisse nicht in Dateien gespeichert werden sollten.

4. Virtuelle Umgebung erstellen und aktivieren:

uv venv

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

# On Windows:
.venv\Scripts\activate

5. Abhängigkeiten installieren:

uv sync

Dies installiert alle in pyproject.toml angegebenen Abhängigkeiten unter Verwendung der exakten Versionen aus uv.lock.

6. Anwendung ausführen:

Der Server unterstützt mehrere Transportprotokolle:

# 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

Transportoptionen:

• stdio: Standard-Eingabe/Ausgabe-Kommunikation (Standard, wird von Claude Desktop verwendet)

• sse: Server-Sent Events über HTTP (gut für webbasierte Clients)

• streamable-http: Streamable HTTP-Transport (empfohlen für produktive HTTP-Bereitstellungen)

Umgebungsvariablen: Sie können den Server auch über Umgebungsvariablen konfigurieren:

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

MCP-Konfiguration für Claude Desktop

7. MCP-Server zu Claude Desktop hinzufügen:

# 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

Fügen Sie die folgende Konfiguration zum Abschnitt mcpServers hinzu (aktualisieren Sie die Pfade, damit sie zu Ihrer Einrichtung passen):

Einzelner Mandant:

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

Mehrere Mandanten:

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

8. Debug - Ihren uv-Installationspfad finden:

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

9. Debug - Den absoluten Pfad Ihres Projekts abrufen:

# From your project directory, run:
pwd

10. Claude Desktop neu starten, um die neue MCP-Serverkonfiguration zu laden.

Einrichtung anderer MCP-Clients

Sobald die Konfiguration abgeschlossen ist, sollten Sie die Funktionen der Vectra AI-Plattform direkt innerhalb von Claude Desktop oder anderen MCP-Clients über diesen MCP-Server nutzen können!

Für andere MCP-Clients als Claude Desktop finden Sie unter den folgenden Links weitere Informationen:

Für andere MCP-Clients lesen Sie bitte deren jeweilige Dokumentation. Das allgemeine Muster ist ähnlich – Sie müssen den Befehl und die Argumente angeben, um den MCP-Server mit derselben Konfigurationsstruktur auszuführen.

Einrichtung - Docker-Bereitstellung

Für produktive Bereitstellungen oder eine einfachere Einrichtung können Sie den Vectra AI MCP-Server mit Docker ausführen. Wir bieten zwei Optionen an:

Option 1: Verwendung vorgefertigter Images (Empfohlen)

Der einfachste Einstieg ist die Verwendung unserer vorgefertigten Docker-Images aus der GitHub Container Registry.

Voraussetzungen

• Docker Desktop oder Docker Engine

Schnellstartschritte

1. Umgebungsvariablen konfigurieren:

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

Bearbeiten Sie anschließend die .env-Datei mit Ihren tatsächlichen Anmeldedaten für die Vectra AI-Plattform.

2. Mit vorgefertigtem Image ausführen:

Streamable HTTP-Transport (Empfohlen für die Produktion)

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

SSE-Transport (Server-Sent Events)

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

Stdio-Transport (Für lokale MCP-Clients)

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. Oder Docker Compose verwenden (Alternative):

Erstellen Sie eine docker-compose.yml-Datei:

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

Führen Sie dann Folgendes aus:

docker-compose up -d

Verfügbare Tags:

• latest: Neueste stabile Version aus dem Hauptzweig

• main: Neueste Version aus dem Hauptzweig (identisch mit latest)

• v*: Spezifische Versions-Tags (z. B. v1.0.0)

💡 Tipp: Vorgefertigte Images werden automatisch über GitHub Actions erstellt und veröffentlicht, sobald Code in den Hauptzweig gepusht oder Releases getaggt werden. Dies stellt sicher, dass Sie immer die neueste getestete Version erhalten, ohne lokal bauen zu müssen.

Option 2: Aus Quellcode bauen

Für die Entwicklung oder Anpassung können Sie das Docker-Image aus dem Quellcode bauen.

Voraussetzungen

1. Docker und Docker Compose installieren

   • Docker Desktop (enthält Docker Compose)

   • Oder installieren Sie Docker Engine und Docker Compose separat unter Linux

Schritte zum Bauen aus dem Quellcode

1. Projekt klonen/herunterladen auf Ihren lokalen Computer

2. In das Projektverzeichnis navigieren:

cd your-project-directory

3. Umgebungsvariablen konfigurieren:

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

Bearbeiten Sie anschließend die .env-Datei mit Ihren tatsächlichen Anmeldedaten für die Vectra AI-Plattform.

4. Mit Docker bauen und ausführen:

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

5. Das lokal gebaute Image ausführen:

Wählen Sie Ihren Transportmodus und führen Sie ihn mit dem lokal gebauten Image aus:

Streamable HTTP-Transport

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

SSE-Transport

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

Stdio-Transport

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

Docker-Einrichtung für mehrere Mandanten

Um den Server im Multi-Mandanten-Modus mit Docker auszuführen:

1. Erstellen Sie eine tenants.yaml-Datei (siehe tenants.yaml.example).

2. Mounten Sie diese in den Container und setzen Sie 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

Sie können Geheimnisse pro Mandant über Umgebungsvariablen injizieren, anstatt sie in der YAML-Datei zu speichern:

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

Docker-Umgebungsvariablen

Der Docker-Container unterstützt dieselben Umgebungsvariablen wie die lokale Einrichtung sowie zusätzliche MCP-Serverkonfigurationen:

MCP-Serverkonfiguration

• VECTRA_MCP_TRANSPORT: Transportprotokoll (stdio, sse oder streamable-http) - Standard: stdio

• VECTRA_MCP_HOST: Host, an den für HTTP-Transporte gebunden werden soll - Standard: 0.0.0.0

• VECTRA_MCP_PORT: Port für HTTP-Transporte - Standard: 8000

• VECTRA_MCP_DEBUG: Debug-Protokollierung aktivieren - Standard: false

• VECTRA_CONFIG_FILE: Pfad zur YAML-Konfigurationsdatei für den Multi-Mandanten-Modus (optional)

Variablen zum Überschreiben für mehrere Mandanten

Bei Verwendung einer YAML-Konfigurationsdatei können Einstellungen pro Mandant über Umgebungsvariablen überschrieben werden:

• 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

Wobei <NAME> der Mandantenname in Großbuchstaben ist (z. B. VECTRA_TENANT_PROD_CLIENT_SECRET).

Zugriff auf den HTTP-Server

Bei der Ausführung mit HTTP-Transporten (sse oder streamable-http) ist der MCP-Server unter folgenden Adressen verfügbar:

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

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

MCP-Client-Konfiguration für Docker

Für HTTP-basierte MCP-Clients, die eine Verbindung zum Docker-Container herstellen, verwenden Sie den entsprechenden Endpunkt:

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

Docker-Health-Checks

Der Docker-Container enthält Health-Checks, die überprüfen, ob der Server ordnungsgemäß läuft:

• Für stdio-Transport: Meldet immer „healthy“ (kein HTTP-Endpunkt zum Überprüfen)

• Für HTTP-Transporte: Überprüft die Verfügbarkeit des HTTP-Endpunkts

Hinweis: MCP (Model Context Protocol) ist eine aufstrebende und sich schnell entwickelnde Technologie. Seien Sie vorsichtig bei der Verwendung dieses Servers und befolgen Sie bewährte Sicherheitsverfahren, einschließlich ordnungsgemäßer Verwaltung von Anmeldedaten und Netzwerksicherheitsmaßnahmen.