Перейти к основному содержимому

Model Context Protocol

Pingera MCP Server — это реализация Model Context Protocol (MCP), которая позволяет ИИ-агентам взаимодействовать с вашими данными платформы Pingera. Этот протокол — новый стандарт для взаимодействия языковых моделей с платформой.

Узнать больше про MCP сервер:

  1. Блог: Pingera MCP сервер - ближе к AI
  2. Github репозиторий pingera-mcp
  3. Скачать в PYPI: Pingera MCP Server

Быстрый старт​

Требования​

  • Python 3.10+
  • uv (пакетный менеджер)
  • Pingera API ключ — его можно получить в разделе «Настройки» вашего аккаунта Pingera.

Установка и запуск​

Установите зависимости проекта:

uv sync

Перед запуском экспортируйте ваш API-ключ как переменную окружения. Это обязательный шаг.

export PINGERA_API_KEY="ваш_api_ключ_здесь"

Запустите сервер. По умолчанию он работает в режиме read_only.

python -m pingera_mcp

Режимы работы​

Режимы доступа​

Сервер поддерживает два уровня доступа, которые определяют возможности ИИ-агента. Режим задаётся переменной окружения PINGERA_MODE.

read_only (по умолчанию)​

  • Функциональность: Агент может только читать данные мониторинга, включая списки страниц, проверки и инциденты.
  • Безопасность: Этот режим гарантирует, что ИИ-агент не сможет создать, изменить или удалить какие-либо ресурсы.

read_write​

  • Функциональность: Агент получает полный контроль над системой. Он может выполнять любые операции: создавать новые проверки, удалять страницы, управлять инцидентами и т.д.
  • Включение: Для активации установите PINGERA_MODE=read_write.

Режимы транспорта (Transport Modes)​

MCP сервер поддерживает два режима подключения:

1. Stdio Mode (по умолчанию)​

Используется для локальной интеграции с Claude Desktop и другими stdio-клиентами. Аутентификация настраивается через переменные окружения.

# Запуск в stdio режиме (по умолчанию)
python -m pingera_mcp

2. HTTP/SSE Mode​

Обеспечивает веб-доступ через HTTP с Server-Sent Events. Идеально подходит для удалённых клиентов, веб-приложений и программного доступа.

# Настройка SSE режима
export TRANSPORT_MODE=sse
export HTTP_HOST=0.0.0.0
export HTTP_PORT=5000

# Запуск в SSE режиме
python -m pingera_mcp

Сервер будет доступен по адресу http://0.0.0.0:5000/sse

Аутентификация в SSE режиме поддерживает два метода через заголовок Authorization:

  1. API ключ (рекомендуется для тестирования):

    Authorization: YOUR_API_KEY

  2. JWT Bearer токен:

    Authorization: Bearer YOUR_JWT_TOKEN

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

Зачем фильтровать инструменты?​

В настоящее время MCP сервер предоставляет 79 инструментов для работы с API Pingera. Передача полного списка в языковую модель неэффективна и приводит к:

  • Перегрузке контекстного окна: системный промпт занимает значительное количество токенов
  • Снижению качества ответов: модели сложнее выбрать нужный инструмент из десятков нерелевантных описаний
  • Росту стоимости: каждый запрос обрабатывает лишние данные

Опыт показывает, что для решения конкретной задачи агенту обычно требуется от 3 до 10 специализированных инструментов.

Как работает фильтрация​

Фильтрация реализована через механизм FastMCP Middleware и позволяет ограничить набор доступных инструментов двумя способами:

1. Локальный режим (Stdio)​

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

python -m pingera_mcp --tools=list_pages,get_page_details,list_checks

Пример конфигурации для Claude Desktop:

{
  "mcpServers": {
    "pingera": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "pingera-mcp-server",
        "--python",
        "3.10",
        "python",
        "-m",
        "pingera_mcp",
        "--tools=list_pages,get_page_details,list_checks"
      ],
      "env": {
        "PINGERA_API_KEY": "ваш_api_ключ_здесь",
        "PINGERA_MODE": "read_only"
      }
    }
  }
}

2. Сетевой режим (HTTP/SSE)​

В SSE режиме используйте кастомный заголовок X-MCP-Tools для динамической фильтрации:

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "pingera": {
        "url": "http://0.0.0.0:5000/sse",
        "transport": "sse",
        "headers": {
            "Authorization": "YOUR_API_KEY",
            "X-MCP-Tools": "list_pages,get_page_details,list_checks"
        }
    }
})

Это позволяет каждому клиенту определять свой набор инструментов без перезагрузки сервера.

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

  • Экономия токенов: уменьшение системного промпта на 60-90%
  • Повышение точности: модель фокусируется только на релевантных инструментах
  • Снижение стоимости: меньше токенов = меньше затрат на API

Примечание: Фильтрация учитывает режим доступа сервера. Инструменты для записи не будут доступны в режиме read_only, даже если указаны в фильтре.

Доступные инструменты (Tools)​

Полный и актуальный список всех доступных инструментов (Tools) и их параметров вы можете найти в файле README.md в репозитории на GitHub.

Основные категории инструментов:​

  • Pages Management (управление статус страницами): list_pages, get_page_details, create_page, update_page, delete_page
  • Component Management (управление компонентами): list_component_groups, get_component_details, create_component, update_component, delete_component
  • Monitoring Checks (проверки мониторинга): list_checks, get_check_details, create_check, update_check, delete_check, pause_check, resume_check
  • Alert Rules (правила оповещений): list_alert_rules, create_alert, update_alert, delete_alert
  • Heartbeat Monitoring (heartbeat мониторинг): list_heartbeats, create_heartbeat, update_heartbeat, delete_heartbeat, send_heartbeat_ping
  • Incident Management (управление инцидентами): list_incidents, create_incident, update_incident, delete_incident, add_incident_update
  • Connection Testing (тестирование соединения): test_pingera_connection

Интеграция с Claude Desktop​

Установка​

Установите пакет глобально с помощью UV:

uv tool install pingera-mcp-server

Настройка​

Чтобы настроить Claude Desktop для работы с Pingera MCP Server, отредактируйте файл конфигурации claude_desktop_config.json:

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

Добавьте в секцию mcpServers следующую конфигурацию:

{
  "mcpServers": {
    "pingera": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "pingera-mcp-server",
        "--python",
        "3.10",
        "python",
        "-m",
        "pingera_mcp"
      ],
      "env": {
        "PINGERA_API_KEY": "ваш_api_ключ_здесь",
        "PINGERA_MODE": "read_only",
        "PINGERA_BASE_URL": "https://api.pingera.ru/v1",
        "PINGERA_TIMEOUT": "30",
        "PINGERA_MAX_RETRIES": "3",
        "PINGERA_DEBUG": "false",
        "PINGERA_SERVER_NAME": "Pingera MCP Server"
      }
    }
  }
}

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

Обязательные:

  • PINGERA_API_KEY — Ваш API ключ Pingera

Опциональные:

  • PINGERA_MODE — Режим работы: read_only (по умолчанию) или read_write
  • PINGERA_BASE_URL — Endpoint API (по умолчанию: https://api.pingera.ru/v1)
  • PINGERA_TIMEOUT — Таймаут запроса в секундах (по умолчанию: 30)
  • PINGERA_MAX_RETRIES — Максимальное количество повторных попыток (по умолчанию: 3)
  • PINGERA_DEBUG — Включить отладочное логирование (по умолчанию: false)
  • PINGERA_SERVER_NAME — Отображаемое имя сервера (по умолчанию: Pingera MCP Server)

После сохранения файла перезапустите Claude Desktop. Теперь вы сможете использовать Pingera MCP Server, просто обращаясь к нему в чате.

Примеры запросов к Claude​

  • "Покажи мои статус страницы и их названия"
  • "Покажи детали страницы с id ..."
  • "Когда была последняя неудачная проверка для check ..."
  • "Запусти простую synthetic проверку для сайта https://example.com"

Отладка и тестирование​

Для тестирования и отладки сервер можно использовать с официальным инструментом MCP Inspector.

  1. Создайте файл mcp.json со следующей конфигурацией:
{
  "mcpServers": {
    "pingera": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "pingera-mcp-server",
        "--python",
        "3.10",
        "python",
        "-m",
        "pingera_mcp"
      ],
      "env": {
        "PINGERA_API_KEY": "ваш_api_ключ_здесь",
        "PINGERA_MODE": "read_only"
      }
    }
  }
}
  1. Запустите инспектор:
npx @modelcontextprotocol/inspector --config mcp.json