IBM Instana MCP Server

официальный

Сервер IBM Instana MCP обеспечивает бесшовное взаимодействие с платформой наблюдаемости IBM Instana, позволяя получать доступ к данным наблюдаемости в реальном времени непосредственно в вашем рабочем процессе разработки.

GitHub

Что можно делать с IBM Instana MCP?

Получение снимков инфраструктуры — Запросите снимок конкретного хоста, процесса или контейнера с помощью get_infra_snapshot.
Анализ метрик приложений или сервисов — Запросите временные ряды метрик для вызовов, ошибок или задержек с помощью get_app_metrics или get_service_metrics.
Просмотр активных оповещений и инцидентов — Получите текущие оповещения, инциденты или глобальные умные оповещения через get_alerts и get_incidents.
Проверка событий Kubernetes — Извлеките недавние события Kubernetes для кластера или пространства имен с помощью get_k8s_events.
Запрос данных мониторинга веб-сайтов — Получите метрики производительности веб-сайта или результаты маяков через get_website_metrics.

Документация

Содержание

MCP-сервер для IBM Instana

MCP-сервер для IBM Instana

📚 Быстрые ссылки

Инструменты и примеры - Подробная документация по инструментам с реальными примерами
Политика конфиденциальности - Информация об обработке данных и конфиденциальности
Руководство по развертыванию в Docker - Подробное руководство по развертыванию в Docker, сборке для нескольких архитектур и настройке для промышленной эксплуатации

MCP-сервер Instana обеспечивает беспрепятственное взаимодействие с платформой наблюдаемости Instana, позволяя получать доступ к данным наблюдаемости в реальном времени непосредственно в вашем рабочем процессе разработки.

Он служит мостом между клиентами (такими как AI-агенты или пользовательские инструменты) и REST API Instana, преобразуя пользовательские запросы в запросы к API Instana и форматируя ответы в структурированные, легко воспринимаемые форматы.

Сервер поддерживает транспортные режимы Streamable HTTP и Stdio для максимальной совместимости с различными MCP-клиентами. Для получения дополнительной информации обратитесь к спецификации транспортных режимов MCP.

Обзор архитектуры

graph LR
    subgraph "Application Host Process"
        MH[MCP Host]
        MSI[Instana MCP Server]
        MST[ProductA MCP Server]
        MSC[ProductB MCP Server]

        MH <--> MSI
        MH <--> MSC
        MH <--> MST
    end

    subgraph "Remote Service"
        II[Instana Instance]
        TI[ProductA Instance]
        CI[ProductB Instance]

        MSI <--> II
        MST <--> TI
        MSC <--> CI
    end

    subgraph "LLM"
        L[LLM]
        MH <--> L
    end

Рабочий процесс

Рассмотрим простой пример: вы используете MCP-хост (например, Claude Desktop, VS Code или другой клиент), подключенный к MCP-серверу Instana. Когда вы запрашиваете информацию об оповещениях Instana, происходит следующий процесс:

MCP-клиент получает список доступных инструментов от MCP-сервера Instana
Ваш запрос отправляется в LLM вместе с описаниями инструментов
LLM анализирует доступные инструменты и выбирает подходящий(ие) для получения оповещений Instana
Клиент выполняет выбранный(ые) инструмент(ы) через MCP-сервер Instana
Результаты (последние оповещения) возвращаются в LLM
LLM формулирует ответ на естественном языке
Ответ отображается вам

sequenceDiagram
    participant User
    participant ChatBot as MCP Host
    participant MCPClient as MCP Client
    participant MCPServer as Instana MCP Server
    participant LLM
    participant Instana as Instana Instance

    ChatBot->>MCPClient: Load available tools from MCP Server
    MCPClient->>MCPServer: Request available tool list
    MCPServer->>MCPClient: Return list of available tools
    User->>ChatBot: Ask "Show me the latest alerts from Instana for application robot-shop"
    ChatBot->>MCPClient: Forward query
    MCPClient->>LLM: Send query and tool description
    LLM->>MCPClient: Select appropriate tool(s) for Instana alert query
    MCPClient->>MCPServer: Execute selected tool(s)
    MCPServer->>Instana: Retrieve alerts for application robot-shop
    MCPServer->>MCPClient: Send alerts of Instana result
    MCPClient->>LLM: Forward alerts of Instana
    LLM->>ChatBot: Generate natural language response for Instana alerts
    ChatBot->>User: Show Instana alert response

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

Вариант 1: Установка из PyPI (рекомендуется)

Самый простой способ использовать mcp-instana — установить его напрямую из PyPI:

pip install mcp-instana

После установки вы можете запустить сервер, используя команду mcp-instana напрямую.

Вариант 2: Установка для разработки

Для разработки или локальной настройки вы можете клонировать и настроить проект локально.

Установка uv

В этом проекте используется uv, быстрый установщик и распознаватель пакетов Python. Чтобы установить uv, у вас есть несколько вариантов:

Использование pip:

pip install uv

Использование Homebrew (macOS):

brew install uv

Для получения дополнительных вариантов установки и подробных инструкций посетите документацию uv.

Настройка окружения

После установки uv настройте окружение проекта, выполнив:

uv sync

Аутентификация на основе заголовков для потокового режима HTTP

При использовании потокового режима HTTP необходимо передавать учетные данные Instana через HTTP-заголовки. Этот подход повышает безопасность и гибкость за счет:

Отсутствия хранения учетных данных в переменных окружения
Возможности использования разных учетных данных для разных запросов
Поддержки общих сред, где изменение переменных окружения ограничено
Поддержки аутентификации как по API-токену, так и по токену сессии

Поддерживаемые режимы аутентификации:

1. Аутентификация по API-токену (прямые вызовы API)

Обязательные заголовки:

instana-base-url: URL вашего экземпляра Instana
instana-api-token: Ваш API-токен Instana

Пример:

--header "instana-base-url: https://your-instance.instana.io"
--header "instana-api-token: your-api-token"

2. Аутентификация по токену сессии (вызовы, инициированные из пользовательского интерфейса)

Обязательные заголовки:

instana-base-url: URL вашего экземпляра Instana
instana-auth-token: Токен аутентификации сессии из бэкенда пользовательского интерфейса
instana-csrf-token: CSRF-токен из бэкенда пользовательского интерфейса
instana-cookie-name: (Необязательно) Имя cookie для аутентификации сессии (по умолчанию: instanaAuthToken)

Пример:

--header "instana-base-url: https://your-instance.instana.io"
--header "instana-auth-token: your-session-token"
--header "instana-csrf-token: your-csrf-token"
--header "instana-cookie-name: in-token"

3. Аутентификация по JWT-токену (интеграция с IBM Platform)

Обязательные заголовки:

instana-base-url: URL вашего экземпляра Instana
instana-jwt-token: JWT-токен от IBM Platform
instana-csrf-token: CSRF-токен для проверки запроса

Пример конфигурации:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://0.0.0.0:8080/mcp",
        "--allow-http",
        "--header",
        "instana-base-url: https://your-instana-instance.instana.io",
        "--header",
        "instana-jwt-token: your_jwt_token_here",
        "--header",
        "instana-csrf-token: your_csrf_token_here"
      ]
    }
  }
}

Приоритет аутентификации:

JWT-токен (если предоставлен с CSRF-токеном) - Имеет приоритет для интеграции с IBM Platform
Токены сессии (если предоставлены и auth_token, и csrf_token)
API-токен (если предоставлен) - Стандартная аутентификация
Переменная окружения (INSTANA_API_TOKEN) - Резервный вариант

Поток аутентификации:

HTTP-заголовки должны присутствовать в каждом запросе
Сервер проверяет учетные данные в порядке приоритета
Запросы без действительной аутентификации будут отклонены

Такая схема обеспечивает безопасную передачу учетных данных и поддерживает несколько потоков аутентификации, включая вызовы, инициированные из пользовательского интерфейса, через WebSocket → Coordinator → MCP-сервер.

Убедитесь, что используемый токен имеет необходимые разрешения для вызова инструментов MCP. Для получения дополнительной информации смотрите здесь.

Запуск локального MCP-сервера

Перед настройкой любого MCP-клиента (Claude Desktop, GitHub Copilot или пользовательских MCP-клиентов) необходимо запустить локальный MCP-сервер. Сервер поддерживает два транспортных режима: Streamable HTTP и Stdio.

Параметры команд сервера

Использование CLI (установка из PyPI)

Если вы установили mcp-instana из PyPI, используйте команду mcp-instana:

mcp-instana [OPTIONS]

Использование установки для разработки

Для локальной разработки используйте команду uv run:

uv run src/core/server.py [OPTIONS]

Доступные параметры:

--transport <mode>: Транспортный режим (варианты: streamable-http, stdio)
--env KEY=VALUE: Установить переменную окружения (можно повторять для нескольких переменных, например, --env INSTANA_BASE_URL=https://... --env INSTANA_API_TOKEN=...)
--debug: Включить режим отладки с дополнительным логированием
--log-level <level>: Установить уровень логирования (варианты: DEBUG, INFO, WARNING, ERROR, CRITICAL)
--tools <categories>: Список категорий инструментов для включения через запятую (например, infra,app,events,website). Включение категории также активирует связанные с ней подсказки. Например: --tools infra включает инструменты infra и все подсказки, связанные с infra.
--list-tools: Вывести список всех доступных категорий инструментов и выйти
--port <port>: Порт MCP-сервера (по умолчанию: 8080, можно переопределить переменной окружения PORT)
--help: Показать справочное сообщение и выйти

Запуск в потоковом режиме HTTP

Потоковый режим HTTP предоставляет интерфейс REST API и рекомендуется для большинства случаев использования.

Использование CLI (установка из PyPI)

# Start with all tools enabled (default)
mcp-instana --transport streamable-http

# Start with debug logging
mcp-instana --transport streamable-http --debug

# Start with a specific log level
mcp-instana --transport streamable-http --log-level WARNING

# Start with specific tool categories only
mcp-instana --transport streamable-http --tools infra,events

# Combine options (specific log level, custom tools)
mcp-instana --transport streamable-http --log-level DEBUG --tools app,events

Использование установки для разработки

# Start with all tools enabled (default)
uv run src/core/server.py --transport streamable-http

# Start with debug logging
uv run src/core/server.py --transport streamable-http --debug

# Start with a specific log level
uv run src/core/server.py --transport streamable-http --log-level WARNING

# Start with specific tool and prompts categories only
uv run src/core/server.py --transport streamable-http --tools infra,events

# Start with custom port
uv run src/core/server.py --transport streamable-http --port 9000

# Combine options (specific log level, custom tools and prompts)
uv run src/core/server.py --transport streamable-http --log-level DEBUG --tools app,events

Ключевые особенности потокового режима HTTP:

Использует HTTP-заголовки для аутентификации (переменные окружения не требуются)
Поддерживает разные учетные данные для каждого запроса
Лучше подходит для общих сред
Порт MCP-сервера по умолчанию: 8080
Конечная точка MCP: http://0.0.0.0:8080/mcp/

Запуск в режиме Stdio

Режим Stdio использует стандартный ввод/вывод для связи и требует переменные окружения для аутентификации.

Использование CLI (установка из PyPI)

# Option 1: Set environment variables first
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"

# Start the server (stdio is the default if no transport specified)
mcp-instana

# Or explicitly specify stdio mode
mcp-instana --transport stdio

# Option 2: Use --env flag to set environment variables directly
mcp-instana --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

# Or with explicit stdio mode
mcp-instana --transport stdio --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

Использование установки для разработки

# Option 1: Set environment variables first
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"

# Start the server (stdio is the default if no transport specified)
uv run src/core/server.py

# Or explicitly specify stdio mode
uv run src/core/server.py --transport stdio

# Option 2: Use --env flag to set environment variables directly
uv run src/core/server.py --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

# Or with explicit stdio mode
uv run src/core/server.py --transport stdio --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

Ключевые особенности режима Stdio:

Использует переменные окружения для аутентификации (можно задать через export или флаг --env)
Прямая связь через stdin/stdout
Требуется для определенных конфигураций MCP-клиентов
Флаг --env предоставляет удобный способ задать учетные данные без изменения окружения оболочки

Категории инструментов

Вы можете оптимизировать производительность сервера, включив только необходимые категории инструментов и подсказок:

Использование CLI (установка из PyPI)

# List all available categories
mcp-instana --list-tools

# Enable specific categories
mcp-instana --transport streamable-http --tools infra,app
mcp-instana --transport streamable-http --tools events

Использование установки для разработки

# List all available categories
uv run src/core/server.py --list-tools

# Enable specific categories
uv run src/core/server.py --transport streamable-http --tools infra,app
uv run src/core/server.py --transport streamable-http --tools events

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

infra: Инструменты и подсказки мониторинга инфраструктуры (ресурсы, каталог, топология, анализ, метрики)
app: Инструменты и подсказки производительности приложений (ресурсы, метрики, оповещения, каталог, топология, анализ, настройки, глобальные оповещения)
events: Инструменты и подсказки мониторинга событий (события Kubernetes, мониторинг агентов)
website: Инструменты и подсказки мониторинга веб-сайтов (метрики, каталог, анализ, конфигурация)

Проверка состояния сервера

После запуска вы можете проверить, работает ли сервер:

Для потокового режима HTTP:

# Check MCP server
curl http://0.0.0.0:8080/mcp/

# Or with custom port
curl http://0.0.0.0:9000/mcp/

Для режима Stdio: Сервер запустится и будет ожидать ввод stdin от MCP-клиентов.

Распространенные проблемы при запуске

Проблемы с сертификатами: Если вы столкнулись с ошибками SSL-сертификата, убедитесь, что ваше окружение Python имеет доступ к системным сертификатам:

# macOS - Install certificates for Python
/Applications/Python\ 3.13/Install\ Certificates.command

Порт уже используется: Если порт 8080 уже используется, укажите другой порт:

uv run src/core/server.py --transport streamable-http --port 9000

Отсутствующие зависимости: Убедитесь, что все зависимости установлены:

uv sync

Настройка и использование

Bob IDE

Bob — это IDE от IBM на базе искусственного интеллекта, которая изначально поддерживает интеграцию с MCP. Bob обеспечивает удобную среду разработки со встроенной помощью ИИ и инструментами наблюдаемости.

Режим Streamable HTTP

Режим Streamable HTTP предоставляет интерфейс REST API для взаимодействия по MCP с использованием JSON-RPC поверх HTTP.

Шаг 1: Запуск MCP-сервера в режиме Streamable HTTP

Перед настройкой Bob необходимо запустить MCP-сервер в режиме Streamable HTTP. Подробные инструкции см. в разделе Запуск локального MCP-сервера.

Шаг 2: Настройка Bob

В правом верхнем углу панели Bob вы увидите выпадающий список с MCP-серверами:

При его выборе вы сможете увидеть опцию настройки MCP на уровне проекта или на глобальном уровне.

Области конфигурации MCP

Bob поддерживает два уровня конфигурации MCP, позволяя выбрать область, которая наилучшим образом соответствует вашему сценарию использования:

1. Глобальная конфигурация (уровень пользователя)

Глобальная конфигурация применяет MCP-серверы ко всем проектам текущего пользователя. Это идеально, когда вы хотите, чтобы одни и те же MCP-серверы были доступны в каждом проекте, над которым вы работаете.

Расположение файлов:

macOS: ~/Library/Application Support/Bob/bob_config.json
Windows: %APPDATA%\Bob\bob_config.json
Linux: ~/.config/Bob/bob_config.json

2. Конфигурация проекта (уровень проекта)

Конфигурация проекта применяет MCP-серверы только к конкретному проекту. Это полезно, когда разным проектам требуются разные конфигурации MCP-серверов или когда вы хотите поделиться настройками MCP с командой через систему контроля версий.

Расположение файла:

.bob/bob_config.json в корневой директории вашего проекта

Выбор между глобальной и проектной конфигурацией:

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

Для получения дополнительной информации о Bob и конфигурации MCP посетите: https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob

Локальная конфигурация:

Настройте Bob для подключения к вашему локальному MCP-серверу Instana:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Удаленная конфигурация:

Настройте Bob для подключения к удаленному MCP-серверу Instana (например, развернутому на IBM Code Engine):

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "https://app-instana-750.1zetetanw8ul.us-east.codeengine.appdomain.cloud/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Примечание: Для использования npx мы рекомендуем сначала установить NVM (Node Version Manager), а затем использовать его для установки Node.js. Инструкции по установке доступны по адресу: https://nodejs.org/en/download

Шаг 3: Проверка соединения

После настройки конфигурации MCP вновь настроенный MCP-сервер должен отображаться как включенный. Зеленая точка означает, что сервер успешно работает.

Теперь вы можете выполнять запросы в Bob IDE:

get me all applications from Instana in the last 24 hours

Режим Stdio

Конфигурация с использованием CLI (установка через PyPI — рекомендуется):

Вариант 1: Использование переменных окружения в конфигурации:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Вариант 2: Использование флага --env (альтернативный метод):

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": [
        "--transport", "stdio",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Примечание: Если вы столкнулись с ошибками «command not found», используйте полный путь к mcp-instana. Найдите его с помощью which mcp-instana и используйте этот путь.

Конфигурация с использованием установки для разработки:

Вариант 1: Использование переменных окружения в конфигурации:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Вариант 2: Использование флага --env (альтернативный метод):

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Claude Desktop

Claude Desktop поддерживает как режим Streamable HTTP, так и режим Stdio для интеграции MCP.

Настройте Claude Desktop, отредактировав файл конфигурации:

Расположение файлов:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Режим Streamable HTTP

Режим Streamable HTTP предоставляет интерфейс REST API для взаимодействия по MCP с использованием JSON-RPC поверх HTTP.

Шаг 1: Запуск MCP-сервера в режиме Streamable HTTP

Перед настройкой Claude Desktop необходимо запустить MCP-сервер в режиме Streamable HTTP. Подробные инструкции см. в разделе Запуск локального MCP-сервера.

Шаг 2: Настройка Claude Desktop

Настройте Claude Desktop для передачи учетных данных Instana через заголовки:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Шаг 3: Проверка соединения

Перезапустите Claude Desktop. Теперь вы должны увидеть IBM Instana MCP Server в интерфейсе Claude Desktop, как показано ниже:

Теперь вы можете выполнять запросы в Claude Desktop:

get me all endpoints from Instana

Режим Stdio

Конфигурация с использованием CLI (установка через PyPI — рекомендуется):

Вариант 1: Использование переменных окружения в конфигурации:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Вариант 2: Использование флага --env (альтернативный метод):

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": [
        "--transport", "stdio",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Конфигурация с использованием установки для разработки:

Вариант 1: Использование переменных окружения в конфигурации:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Вариант 2: Использование флага --env (альтернативный метод):

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Настройка Kiro

Kiro — это агентная IDE, а не расширение, которое можно загрузить в VS Code или другую IDE.

Шаг 1: Загрузите и установите Kiro для вашей операционной системы с https://kiro.dev/.

Шаг 2: После установки запустите Kiro и откройте любой проект в IDE. alt text

Шаг 3: Нажмите значок Kiro (Ghost) на левой боковой панели, чтобы получить доступ к функциям Kiro. alt text

Шаг 4: Выберите значок Edit Config в правом верхнем углу раздела MCP Servers. alt text

Шаг 5: Откройте файл конфигурации MCP-сервера (mcp.json) и настройте его в соответствии с предпочитаемым транспортным режимом:

Режим Streamable HTTP (рекомендуется для Kiro)

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Примечание: Перед использованием этой конфигурации обязательно запустите MCP-сервер в режиме streamable-http:

mcp-instana --transport streamable-http

Режим Stdio

Вариант 1: Использование переменных окружения в конфигурации:

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Вариант 2: Использование флага --env (альтернативный метод):

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": [
        "--transport", "stdio",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Шаг 6: После сохранения файла нажмите кнопку Enable MCP, и вы увидите ваш MCP-сервер и его доступные инструменты в левом нижнем углу Kiro. alt text

Шаг 7: Перейдите на панель AI Chat, введите запрос, связанный с вашим MCP-сервером, и просмотрите ответ непосредственно в Kiro. alt text

GitHub Copilot

GitHub Copilot поддерживает интеграцию MCP через конфигурацию VS Code. Для интеграции GitHub Copilot с VS Code обратитесь к этому руководству по настройке.

Режим Streamable HTTP

Шаг 1: Запуск MCP-сервера в режиме Streamable HTTP

Перед настройкой VS Code необходимо запустить MCP-сервер в режиме Streamable HTTP. Подробные инструкции см. в разделе Запуск локального MCP-сервера.

Шаг 2: Настройка VS Code

Обратитесь к разделу Использование MCP-серверов в VS Code для получения подробной информации о настройке.

Вы можете напрямую создать или обновить .vscode/mcp.json со следующей конфигурацией:

{
  "servers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ],
      "env": {
        "PATH": "/usr/local/bin:/bin:/usr/bin",
        "SHELL": "/bin/sh"
      }
    }
  }
}

Примечание: Замените следующие значения на ваши фактические данные конфигурации:

instana-base-url: URL вашего экземпляра Instana
instana-api-token: Ваш API-токен Instana
command: Обновите путь npx в соответствии с установкой Node.js в вашей системе (например, /path/to/your/node/bin/npx)
Переменные окружения: При необходимости скорректируйте PATH и другие переменные окружения для вашей системы

Режим Stdio

Шаг 1: Создание конфигурации MCP для VS Code

Использование CLI (установка через PyPI — рекомендуется):

Создайте .vscode/mcp.json в корне вашего проекта:

Вариант 1: Использование переменных окружения в конфигурации:

{
  "servers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Вариант 2: Использование флага --env (альтернативный метод):

{
  "servers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": [
        "--transport", "stdio",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Использование установки для разработки:

Создайте .vscode/mcp.json в корне вашего проекта:

Вариант 1: Использование переменных окружения в конфигурации:

{
  "servers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project/mcp-instana",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Вариант 2: Использование флага --env (альтернативный метод):

{
  "servers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project/mcp-instana",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Примечание: Замените следующие значения на ваши фактические данные конфигурации:

Для установки через CLI: Убедитесь, что mcp-instana находится в вашем PATH
Для установки для разработки:
- command: Обновите путь uv в соответствии с установкой uv в вашей системе (например, /path/to/your/uv/bin/uv или /usr/local/bin/uv)
- --directory: Обновите абсолютный путь к директории вашего проекта mcp-instana
INSTANA_BASE_URL: URL вашего экземпляра Instana
INSTANA_API_TOKEN: Ваш API-токен Instana

Шаг 2: Управление сервером в VS Code

Откройте .vscode/mcp.json — вы увидите элементы управления сервером вверху
Нажмите Start рядом с Instana MCP Server, чтобы запустить сервер
Статус работы и количество инструментов указывают на то, что сервер запущен

Шаг 3: Проверка интеграции

Переключитесь в режим Agent в GitHub Copilot и перезагрузите инструменты. Вот пример ответа GitHub Copilot:

GitHub Copilot Response

Mistral AI

Mistral AI поддерживает интеграцию MCP исключительно через режим Streamable HTTP.

Шаг 1: Запуск MCP-сервера в режиме Streamable HTTP

Запустите MCP-сервер в режиме Streamable HTTP, предоставив ваши учетные данные Instana. Выполните следующую команду:

uv run src/core/server.py --transport streamable-http \
  --api-token "your_instana_api_token" \
  --base-url "https://your-instana-instance.instana.io" \
  --port 8080

Шаг 2: Настройка переадресации портов с помощью Ngrok

Настройте переадресацию портов для предоставления доступа к вашему локальному серверу. Следуйте документации по настройке Ngrok для получения подробных инструкций.

Шаг 3: Настройка Mistral AI

Перейдите на вкладку Intelligence на левой боковой панели и выберите Connectors
Нажмите Add Connector
Создайте пользовательский коннектор, введя имя коннектора и URL MCP-сервера, переадресованный через Ngrok
Начните новый сеанс чата и убедитесь, что инструменты MCP включены. Вы можете просмотреть ответ здесь

Поддерживаемые функции

Доступные инструменты

Инструмент	Категория	Описание
`manage_applications`	Приложения и инфраструктура	Унифицированный инструмент для управления метриками приложений, конфигурациями оповещений, настройками и каталогом
`manage_websites`	Мониторинг веб-сайтов	Унифицированный интеллектуальный маршрутизатор для анализа веб-сайтов, каталога, конфигурации и расширенных операций конфигурации
`manage_custom_dashboards`	Пользовательские панели	Унифицированный инструмент для управления операциями CRUD пользовательских панелей
`analyze_infrastructure`	Анализ инфраструктуры	Двухпроходный анализ инфраструктуры со сбором данных о сущностях/метриках
`manage_automation`	Автоматизация	Унифицированный интеллектуальный маршрутизатор для автоматизации: просмотр каталога действий и истории выполнения
`manage_events`	События	Унифицированный интеллектуальный маршрутизатор для мониторинга событий: получение события по ID, событий по ID, событий Kubernetes, событий мониторинга агентов и всех событий
`manage_slo`	Управление SLO	Унифицированный интеллектуальный маршрутизатор для конфигураций SLO, отчетов, оповещений и окон коррекции с интеллектуальной обработкой часовых поясов
`manage_releases`	Управление релизами	Унифицированный интеллектуальный маршрутизатор для отслеживания релизов: список релизов с пагинацией и фильтрацией по имени, получение деталей релиза, создание/обновление/удаление релизов с поддержкой часовых поясов
`manage_maintenance_windows`	Окна обслуживания	Унифицированный интеллектуальный маршрутизатор для управления жизненным циклом окон обслуживания: создание, изменение, закрытие и список окон обслуживания с поддержкой шаблонов и интеграцией ServiceNow
`manage_mobile_apps`	Мониторинг мобильных приложений	Унифицированный интеллектуальный маршрутизатор для мониторинга мобильных приложений: анализ маяков, метрик производительности, конфигурации и управления оповещениями

👉 Подробную документацию по инструментам, возможностям и техническую справку см. в разделе Инструменты и примеры

Фильтрация инструментов

MCP-сервер поддерживает выборочную загрузку инструментов для оптимизации производительности и снижения потребления ресурсов. Вы можете включить только те категории инструментов, которые необходимы для вашего конкретного сценария.

Доступные категории инструментов

router: Унифицированное управление приложениями и инфраструктурой
- manage_instana_resources: Единый инструмент для метрик приложений, конфигураций оповещений, настроек и каталога
- Поддерживает перспективы приложений, конечные точки, сервисы и ручные сервисы
- Управляет как специфичными для приложения, так и глобальными конфигурациями оповещений
- Предоставляет доступ к каталогу тегов и каталогу метрик приложений
dashboard: Управление пользовательскими панелями
- manage_custom_dashboards: Операции CRUD для пользовательских панелей
- Поддерживает создание, получение, обновление и удаление панелей
- Управляет пользователями и API-токенами, которым можно предоставить доступ к панелям
infra: Инструменты анализа инфраструктуры
- analyze_infrastructure: Двухпроходный анализ инфраструктуры со сбором данных о сущностях/метриках
- Динамически поддерживает все типы сущностей, доступные в вашей установке Instana (автоматически загружаются из каталога API)
- Включает JVM, Kubernetes, Docker, хосты, базы данных, очереди сообщений и любые пользовательские или недавно добавленные типы сущностей
- Гибкая агрегация метрик, фильтрация, группировка и запросы с временными диапазонами
automation: Инструменты действий автоматизации
- manage_automation: Унифицированный интеллектуальный маршрутизатор для каталога автоматизации и истории выполнения
- Каталог действий: просмотр действий, получение деталей, поиск по имени/описанию, фильтрация по ID приложения или снимка
- История действий: список экземпляров выполнения с фильтрацией, получение деталей выполнения
events: Инструменты мониторинга событий
- События: события Kubernetes, мониторинг агентов и отслеживание системных событий
website: Инструменты мониторинга веб-сайтов
- Метрики веб-сайтов: измерение производительности веб-сайтов
- Каталог веб-сайтов: метаданные и определения веб-сайтов
- Анализ веб-сайтов: анализ производительности веб-сайтов
- Конфигурация веб-сайтов: управление конфигурацией веб-сайтов
slo: Управление целевыми показателями уровня обслуживания (SLO)
- manage_slo: Унифицированный интеллектуальный маршрутизатор для комплексных операций SLO
- Управление конфигурацией: Создание, чтение, обновление, удаление конфигураций SLO с поддержкой индикаторов на основе времени и событий
- Генерация отчетов: Создание подробных отчетов SLO со значениями SLI, бюджетами ошибок, скоростью сжигания и графиками временных рядов
- Конфигурация оповещений: Управление конфигурациями оповещений SLO для мониторинга бюджета ошибок и отслеживания скорости сжигания
- Окна коррекции: Создание и управление окнами обслуживания для исключения плановых простоев из расчетов SLO
- Интеллектуальная обработка часовых поясов: Автоматический сбор данных о часовом поясе для ввода даты и времени, чтобы обеспечить точный временной контекст
- Двухпроходный сбор данных: Интерактивный сбор параметров для сложных операций, требующих множественных вводов
releases: Отслеживание релизов и управление развертыванием
- manage_releases: Унифицированный интеллектуальный маршрутизатор для операций с релизами
- Список релизов: Получение всех релизов с эффективной пагинацией (page_number, page_size) и фильтрацией по имени
- Детали релиза: Получение конкретной информации о релизе по ID, включая приложения, сервисы и области действия
- Создание/Обновление/Удаление: Полные операции CRUD для управления релизами
- Интеллектуальная обработка часовых поясов: Автоматический сбор данных о часовом поясе для времени начала релиза
- Эффективная пагинация: Избегайте избыточной выборки данных с помощью правильной постраничной навигации
- Фильтрация по имени: Регистронезависимое сопоставление подстрок для поиска релизов по имени
maintenance_window: Управление жизненным циклом окон обслуживания
- manage_maintenance_windows: Унифицированный интеллектуальный маршрутизатор для операций с окнами обслуживания
- Операции с окнами: Создание, изменение, закрытие и список окон обслуживания (активные, запланированные, все, истекшие)
- Массовые операции: Создание окон обслуживания для нескольких приложений одновременно
- Поддержка шаблонов: Предопределенные шаблоны для распространенных сценариев (deployment, database_migration, infrastructure_upgrade, emergency, routine)
- Повторяющиеся окна: Поддержка повторяющихся окон обслуживания с использованием формата RFC 5545 RRULE
- Интеграция ServiceNow: Опциональная интеграция с запросами на изменения ServiceNow
- Валидация: Проверка параметров перед созданием окна
- Гибкая длительность: Указание длительности в минутах, часах или днях
mobile_app: Мониторинг мобильных приложений
- manage_mobile_apps: Унифицированный интеллектуальный маршрутизатор для операций мониторинга мобильных приложений
- Анализ маяков: Запрос данных маяков мобильных приложений с группировкой и фильтрацией
- Метрики производительности: Отслеживание длительности сессий, частоты сбоев и производительности HTTP-запросов
- Географический анализ: Анализ распределения пользователей по странам, городам и регионам
- Анализ устройств: Мониторинг производительности на различных устройствах, платформах и версиях ОС
- Управление конфигурацией: Управление конфигурациями мобильных приложений, геолокацией и настройками маскирования IP
- Управление оповещениями: Настройка и управление конфигурациями оповещений для мобильных приложений

Примеры использования

Использование CLI (установка через PyPI)

# Enable only router (unified app/infra management) and events tools
mcp-instana --tools router,events --transport streamable-http

# Enable only infrastructure analysis tools
mcp-instana --tools infra --transport streamable-http

# Enable router and infrastructure analysis
mcp-instana --tools router,infra --transport streamable-http

# Enable events and website tools
mcp-instana --tools events,website --transport streamable-http

# Enable dashboard and router tools
mcp-instana --tools dashboard,router --transport streamable-http

# Enable releases and events tools
mcp-instana --tools releases,events --transport streamable-http

# Enable maintenance window and events tools
mcp-instana --tools maintenance_window,events --transport streamable-http

# Enable all tools (default behavior)
mcp-instana --transport streamable-http

# List all available tool categories and their tools
mcp-instana --list-tools

Использование установки для разработки

# Enable only router (unified app/infra management) and events tools
uv run src/core/server.py --tools router,events --transport streamable-http

# Enable only infrastructure analysis tools
uv run src/core/server.py --tools infra --transport streamable-http

# Enable router and infrastructure analysis
uv run src/core/server.py --tools router,infra --transport streamable-http

# Enable events and website tools
uv run src/core/server.py --tools events,website --transport streamable-http

# Enable dashboard and router tools
uv run src/core/server.py --tools dashboard,router --transport streamable-http

# Enable releases and events tools
uv run src/core/server.py --tools releases,events --transport streamable-http

# Enable maintenance window and events tools
uv run src/core/server.py --tools maintenance_window,events --transport streamable-http

# Enable all tools (default behavior)
uv run src/core/server.py --transport streamable-http

# List all available tool categories and their tools
uv run src/core/server.py --list-tools

Преимущества фильтрации инструментов

Производительность: Сокращение времени запуска и использования памяти
Безопасность: Ограничение доступа только к необходимым API
Ясность: Фокусировка на конкретных сценариях использования (например, только мониторинг инфраструктуры)
Эффективность ресурсов: Снижение загрузки ЦП и использования сети

👉 Примеры использования и подсказки см. в Примеры подсказок

Развертывание в Docker

Сервер MCP Instana можно развернуть с помощью Docker для производственных сред. Настройка Docker оптимизирована для безопасности, производительности и минимального использования ресурсов.

Архитектура Docker

В проекте используется стратегия управления зависимостями с двумя файлами:

pyproject.toml

Назначение: Унифицированная конфигурация как для разработки, так и для продакшена
Зависимости: Все основные зависимости с опциональными зависимостями для разработки
Использование: Локальная разработка, тестирование, CI/CD и производственные сборки Docker
Преимущества: Единый источник истины для всех зависимостей, упрощенное обслуживание

Сборка образа Docker

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

Установленный и запущенный Docker
Доступ к исходному коду проекта
Docker BuildKit для мультиархитектурных сборок (включен по умолчанию в последних версиях Docker)

Команда сборки

# Build the optimized production image
docker build -t mcp-instana:latest .

# Build with a specific tag
docker build -t mcp-instana:<image_tag> .

#### **Run Command**
# Run the container (no credentials needed in the container)
docker run -p 8080:8080 mcp-instana

# Run with custom port
docker run -p 8081:8080 mcp-instana

📖 Полную документацию по Docker, включая мультиархитектурные сборки, настройку Docker Compose, лучшие практики безопасности и примеры производственного развертывания, см. в DOCKER.md.

Устранение неполадок

Проблемы с Docker

Контейнер не запускается

# Check container logs
docker logs <container_id>
# Common issues:
# 1. Port already in use
# 2. Invalid container image
# 3. Missing dependencies
# Credentials are passed via HTTP headers from the MCP client

Проблемы с подключением

# Test container connectivity
docker exec -it <container_id> curl http://127.0.0.1:8080/health
# Check port mapping
docker port <container_id>

Проблемы с производительностью

# Check container resource usage
docker stats <container_id>
# Monitor container health
docker inspect <container_id> | grep -A 10 Health

Общие проблемы

GitHub Copilot
- Если у вас возникли проблемы с GitHub Copilot, попробуйте запустить/остановить/перезапустить сервер в файле mcp.json и держите запущенным только один сервер одновременно.
Проблемы с сертификатами
- Если у вас возникли проблемы с сертификатами, например [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate:
  - Проверьте, можете ли вы достичь конечной точки Instana API с помощью curl или wget с проверкой SSL.
    - Если это работает, возможно, ваше окружение Python не может проверить сертификат и не имеет доступа к тем же сертификатам, что и ваша оболочка или система. Убедитесь, что ваше окружение Python использует системные сертификаты (macOS). Это можно сделать, установив сертификаты в Python: //Applications/Python\ 3.13/Install\ Certificates.command
  - Если вы не можете достичь конечной точки с проверкой SSL, попробуйте без нее. Если это сработает, проверьте сертификаты ЦС вашей системы и убедитесь, что они актуальны.