Как научить LLM-агента спрашивать Яндекс Метрику: разбираем протокол MCP и OAuth-авторизацию без секрета

Вот важная новость с фронта ИИ: Dearonski 4 минуты назад Как научить LLM-агента спрашивать Яндекс Метрику: разбираем протокол MCP и OAuth-авторизацию без секрета Средний 7 мин 173 Искусственный интеллект Open source * Веб-аналитика * Программирование * Яндекс API * Туториал Из песочницы Веб-аналитика живёт за дашбордами и HTTP-API. Чтобы получить ответ на простой вопрос вроде «откуда пришёл трафик за прошлую неделю и сколько из этого дошло до цели», человек лезет в интерфейс Метрики, а программа — собирает запрос к Reporting API, помнит про namespace полей, лимиты и форматы ответа. LLM-агент (Claude, модель в Cursor, любой другой) по умолчанию не умеет ни того, ни другого: у него нет ни доступа к вашему счётчику, ни знания о том, как устроен API.

Мостом между агентом и внешней системой служит MCP — Model Context Protocol. В этой статье я разберу, как устроен MCP-сервер для Яндекс. Метрики: как маппить отчёты Метрики на небольшой набор инструментов, как авторизоваться в Yandex ID без клиентского секрета (это оказалось самой нетривиальной частью) и на какие грабли API я наступил по дороге.

Технические детали

Код — на TypeScript; сам сервер open-source под MIT, ссылка в конце. Материал будет полезен, если вы пишете свой MCP-сервер над чужим HTTP-API, разбираетесь с OAuth-флоу Яндекса или просто хотите понять, что происходит под капотом, когда агент «сам ходит» в аналитику. Что такое MCP и зачем он здесьMCP — открытый протокол, описывающий, как приложение-хост (клиент с LLM) общается с внешними серверами, которые предоставляют модели инструменты (tools), ресурсы и промпты.

Идея простая: вместо того чтобы зашивать интеграции в каждый чат-клиент, вы поднимаете отдельный процесс-сервер, а хост подключается к нему по стандартному транспорту (обычно stdio) и получает список инструментов с их JSON-схемами. Дальше модель сама решает, какой инструмент и с какими аргументами вызвать, а хост исполняет вызов и возвращает результат в контекст. Для аналитики это удобная модель: сервер инкапсулирует всё неприятное — авторизацию, формирование запроса, разбор ответа, дисциплину по объёму данных, — а модель оперирует человекопонятными инструментами.

Ключевое проектное решение, к которому я пришёл: инструментов должно быть мало и они должны быть гибкими, а не «одна кнопка на каждый отчёт». Метрика умеет сотни комбинаций измерений и метрик — заводить под каждую отдельный tool бессмысленно. Поэтому вместо «покажи топ страниц» и «покажи источники» получилось пять инструментов:run_report — гибкая обёртка над Reporting API (/stat/v1/data): произвольные метрики, измерения, фильтры, сортировка;run_comparison — сравнение двух периодов с абсолютной и процентной дельтой;run_drilldown — проваливание по дереву измерения (ОС → версии ОС и т.

);run_timeseries — метрики, разложенные в динамику по времени (/bytime);get_metadata — обнаружение доступных счётчиков, целей и типовых полей, чтобы модель строила запрос по реальным именам, а не угадывала их. Дальше — самое интересное: как вообще пустить сервер к данным пользователя.

Этот прогресс даёт важные сигналы о будущем отрасли, и технологический мир внимательно наблюдает.