Vectra AI MCP Server

Этот проект реализует MCP-сервер для платформы Vectra AI.

Что такое Vectra AI MCP?

MCP-сервер, который подключает ИИ-ассистентов к вашей платформе безопасности Vectra AI, обеспечивая интеллектуальный анализ данных об обнаружении угроз, аналитику безопасности и автоматизированные рабочие процессы реагирования на инциденты. Совместим с Claude, ChatGPT, Cursor, VS Code и другими ИИ-инструментами с поддержкой MCP.

Что можно делать с помощью Vectra AI MCP?

• Расследовать угрозы на естественном языке

• Принимать меры реагирования в Vectra напрямую через вашего ИИ-агента

• Сопоставлять и анализировать данные безопасности с помощью промптов

• Динамически создавать расширенные визуализации для анализа

• Генерировать отчеты о расследованиях на естественном языке

Настройка — Локальный хостинг

Предварительные требования

1. Установите Python Проверьте файл .python-version для получения информации о требуемой версии

2. Установите uv — менеджер пакетов 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

Шаги по настройке

1. Клонируйте/скачайте проект на свой локальный компьютер

2. Перейдите в директорию проекта:

cd your-project-directory

3. Настройте учетные данные:

Вариант А: Один арендатор (файл .env)

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

Затем отредактируйте файл .env, указав свои актуальные учетные данные платформы Vectra AI. Необходимые переменные для обновления:

• VECTRA_BASE_URL: URL вашего портала Vectra

• VECTRA_CLIENT_ID: Ваш идентификатор клиента (client ID) из Vectra

• VECTRA_CLIENT_SECRET: Ваш секретный ключ клиента (client secret) из Vectra

Вариант Б: Несколько арендаторов (YAML-конфигурация)

Если у вас несколько арендаторов Vectra, используйте YAML-файл конфигурации:

cp tenants.yaml.example tenants.yaml

Затем отредактируйте tenants.yaml, указав данные ваших арендаторов:

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

Каждый арендатор получает свой собственный набор инструментов с префиксом имени арендатора (например, prod_list_detections, staging_list_detections). Также добавлен мета-инструмент list_tenants для обнаружения доступных арендаторов.

Значения для каждого арендатора можно переопределить с помощью переменных окружения, используя шаблон VECTRA_TENANT_<NAME>_<FIELD> (например, VECTRA_TENANT_PROD_CLIENT_SECRET). Это полезно для Docker/Kubernetes, где секреты не должны храниться в файлах.

4. Создайте и активируйте виртуальное окружение:

uv venv

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

# On Windows:
.venv\Scripts\activate

5. Установите зависимости:

uv sync

Это установит все зависимости, указанные в pyproject.toml, используя точные версии из uv.lock.

6. Запустите приложение:

Сервер поддерживает несколько транспортных протоколов:

# 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

Варианты транспорта:

• stdio: Связь через стандартный ввод/вывод (по умолчанию, используется Claude Desktop)

• sse: Server-Sent Events через HTTP (подходит для веб-клиентов)

• streamable-http: Потоковый HTTP-транспорт (рекомендуется для HTTP-развертываний в продакшене)

Переменные окружения: Вы также можете настроить сервер с помощью переменных окружения:

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 для Claude Desktop

7. Добавьте MCP-сервер в 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

Добавьте следующую конфигурацию в раздел mcpServers (обновите пути в соответствии с вашей настройкой):

Один арендатор:

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

Несколько арендаторов:

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

8. Отладка — Найдите путь установки uv:

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

9. Отладка — Получите абсолютный путь к вашему проекту:

# From your project directory, run:
pwd

10. Перезапустите Claude Desktop, чтобы загрузить новую конфигурацию MCP-сервера.

Настройка других MCP-клиентов

После настройки вы сможете использовать возможности платформы Vectra AI непосредственно в Claude Desktop или других MCP-клиентах через этот MCP-сервер!

Для других MCP-клиентов, помимо Claude Desktop, обратитесь к ссылкам на документацию ниже:

Для других MCP-клиентов обратитесь к их соответствующей документации. Общий шаблон схож — вам нужно будет указать команду и аргументы для запуска MCP-сервера с той же структурой конфигурации.

Настройка — Развертывание в Docker

Для развертывания в продакшене или упрощения настройки вы можете запустить Vectra AI MCP Server с помощью Docker. Мы предоставляем два варианта:

Вариант 1: Использование готовых образов (рекомендуется)

Самый простой способ начать — использовать наши готовые Docker-образы из GitHub Container Registry.

Предварительные требования

• Docker Desktop или Docker Engine

Шаги для быстрого запуска

1. Настройте переменные окружения:

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

Затем отредактируйте файл .env, указав свои актуальные учетные данные платформы Vectra AI.

2. Запустите с помощью готового образа:

Потоковый HTTP-транспорт (рекомендуется для продакшена)

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-транспорт (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-транспорт (для локальных MCP-клиентов)

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. Или используйте Docker Compose (альтернатива):

Создайте файл 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

Затем запустите:

docker-compose up -d

Доступные теги:

• latest: Последняя стабильная сборка из ветки main

• main: Последняя сборка из ветки main (аналогично latest)

• v*: Теги конкретных версий (например, v1.0.0)

💡 Совет: Готовые образы автоматически собираются и публикуются через GitHub Actions при каждом пуше кода в ветку main или при создании тегов релизов. Это гарантирует, что вы всегда получите последнюю протестированную версию без необходимости сборки локально.

Вариант 2: Сборка из исходного кода

Для разработки или внесения изменений вы можете собрать Docker-образ из исходного кода.

Предварительные требования

1. Установите Docker и Docker Compose

   • Docker Desktop (включает Docker Compose)

   • Или установите Docker Engine и Docker Compose отдельно в Linux

Шаги по сборке из исходного кода

1. Клонируйте/скачайте проект на свой локальный компьютер

2. Перейдите в директорию проекта:

cd your-project-directory

3. Настройте переменные окружения:

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

Затем отредактируйте файл .env, указав свои актуальные учетные данные платформы Vectra AI.

4. Соберите и запустите с помощью Docker:

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

5. Запустите локально собранный образ:

Выберите режим транспорта и запустите локально собранный образ:

Потоковый HTTP-транспорт

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-транспорт

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-транспорт

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

Настройка Docker для нескольких арендаторов

Чтобы запустить сервер в режиме нескольких арендаторов с Docker:

1. Создайте файл tenants.yaml (см. tenants.yaml.example).

2. Примонтируйте его в контейнер и установите 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

Вы можете внедрять секреты для каждого арендатора через переменные окружения вместо хранения их в 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

Переменные окружения Docker

Docker-контейнер поддерживает все те же переменные окружения, что и локальная установка, плюс дополнительные настройки MCP-сервера:

Конфигурация MCP-сервера

• VECTRA_MCP_TRANSPORT: Транспортный протокол (stdio, sse или streamable-http) — по умолчанию: stdio

• VECTRA_MCP_HOST: Хост для привязки HTTP-транспортов — по умолчанию: 0.0.0.0

• VECTRA_MCP_PORT: Порт для HTTP-транспортов — по умолчанию: 8000

• VECTRA_MCP_DEBUG: Включить отладочное логирование — по умолчанию: false

• VECTRA_CONFIG_FILE: Путь к YAML-файлу конфигурации для режима нескольких арендаторов (опционально)

Переменные переопределения для нескольких арендаторов

При использовании YAML-файла конфигурации настройки для каждого арендатора можно переопределить через переменные окружения:

• 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

Где <NAME> — это имя арендатора в верхнем регистре (например, VECTRA_TENANT_PROD_CLIENT_SECRET).

Доступ к HTTP-серверу

При работе с HTTP-транспортами (sse или streamable-http) MCP-сервер будет доступен по адресу:

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

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

Конфигурация MCP-клиента для Docker

Для HTTP-клиентов MCP, подключающихся к контейнеризированному серверу, используйте соответствующую конечную точку:

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

Проверки работоспособности Docker

Docker-контейнер включает проверки работоспособности, которые подтверждают правильность работы сервера:

• Для транспорта stdio: Всегда сообщает о работоспособности (нет HTTP-конечной точки для проверки)

• Для HTTP-транспортов: Проверяет доступность HTTP-конечной точки

Примечание: MCP (Model Context Protocol) — это развивающаяся и быстро меняющаяся технология. Будьте осторожны при использовании этого сервера и следуйте лучшим практикам безопасности, включая надлежащее управление учетными данными и меры сетевой безопасности.