Что такое ИИ-агент для аналитики: MCP-сервер сам строит отчёты Яндекс Метрики

Если вы слышали про MCP, но не понимали, зачем он нужен на практике, этот разбор покажет конкретный сценарий: ИИ-агент (что такое ИИ-агент: программа, которая сама решает, какие действия выполнить для достижения цели, вызывая внешние инструменты без ручного управления) подключается к вашему счётчику Метрики и отвечает на вопросы об аналитике на человеческом языке. Код сервера открыт под лицензией MIT, написан на TypeScript. Ниже разбираю, что нужно для запуска, как устроена авторизация и на каких граблях API Метрики вы сэкономите время.

Что понадобится?

• Счётчик Яндекс Метрики с данными (подойдёт любой, к которому у вас есть доступ)
• Node.js установленный на машине (сервер запускается через npx)
• MCP-совместимый клиент с LLM (большая языковая модель): Claude Desktop, Cursor или любой другой хост, поддерживающий MCP
• Аккаунт Яндекс ID для OAuth-авторизации
• Время: 15 минут на установку и первый запрос, ещё 10 минут на настройку под свои задачи

Как устроен MCP и почему инструментов всего пять?

MCP (Model Context Protocol, протокол контекста модели) описывает, как приложение с LLM общается с внешними серверами. Вместо того чтобы встраивать интеграции в каждый чат-клиент, вы запускаете отдельный процесс-сервер. Хост подключается к нему по стандартному транспорту (обычно stdio), получает список инструментов с JSON-схемами, а модель сама решает, какой инструмент вызвать и с какими аргументами.

Ключевое проектное решение автора сервера: инструментов мало, но каждый гибкий. Метрика поддерживает сотни комбинаций измерений и метрик. Заводить под каждую отдельный инструмент бессмысленно. Поэтому вместо набора кнопок получилось пять инструментов:

• run_report гибкая обёртка над Reporting API: произвольные метрики, измерения, фильтры, сортировка
• run_comparison сравнение двух периодов с абсолютной и процентной дельтой
• run_drilldown проваливание по дереву измерения (ОС, затем версии ОС и так далее)
• run_timeseries метрики, разложенные в динамику по времени
• get_metadata обнаружение доступных счётчиков, целей и типовых полей, чтобы модель строила запрос по реальным именам, а не угадывала

Пошаговая инструкция

1. Установите и запустите сервер одной командой:

npx yandex-metrica-mcp-server

1. Пройдите авторизацию. При первом запуске сервер откроет в браузере страницу Яндекс ID. Подтвердите доступ, скопируйте код со страницы и вставьте в терминал. Публичный client_id уже вшит в пакет, отдельное OAuth-приложение регистрировать не нужно.

2. Подключите сервер к MCP-клиенту. В настройках Claude Desktop или Cursor укажите путь к серверу как MCP-источник по транспорту stdio.

3. Задайте вопрос на обычном языке. Например: «Откуда пришёл трафик за прошлую неделю и сколько визитов дошло до цели?» ИИ-агент сам выберет нужный инструмент (run_report или run_comparison), сформирует запрос к API Метрики и вернёт ответ.

4. Для сравнения периодов используйте формулировку вроде: «Сравни источники трафика за эту и прошлую неделю.» Агент вызовет run_comparison и покажет дельту.

Авторизация без секрета: почему это работает?

Здесь начинается самая нетривиальная часть. Сервер устанавливается через npx и работает на машине пользователя. Встроить client_secret в npm-пакет нельзя: всё, что попадает в пакет, публично.

Решение: Authorization Code + PKCE (RFC 7636, стандарт для публичных клиентов). Клиент генерирует случайный code_verifier, отправляет на сервер авторизации его хеш (code_challenge), а при обмене кода на токен предъявляет исходный verifier. Секрет не нужен, подлинность подтверждается знанием verifier.

Генерация пары выглядит так:

import { createHash, randomBytes } from 'node:crypto'

function base64Url(buf: Buffer): string {
  return buf.toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '')
}

export function generatePkce() {
  const verifier = base64Url(randomBytes(48))
  const challenge = base64Url(
    createHash('sha256').update(verifier).digest()
  )
  return { verifier, challenge, method: 'S256' as const }
}

Обмен кода на токен отправляет секрет только если он есть:

const body = new URLSearchParams({
  grant_type: 'authorization_code',
  code,
  client_id: clientId,
  code_verifier: verifier,
  redirect_uri: 'https://oauth.yandex.com/verification_code',
})
if (clientSecret) body.set('client_secret', clientSecret)

const res = await fetch('https://oauth.yandex.com/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body,
})

Токен кэшируется в файле с правами 0600 (читать может только владелец). Логин делается один раз.

Три грабли OAuth у Яндекса, которых нет в документации

Эти три проблемы автор обнаружил экспериментально, проверяя каждый шаг против oauth.yandex.com:

• http:// редиректы запрещены. Стандартный для CLI приём: поднять локальный сервер на http://127.0.0.1:<port> и поймать редирект с кодом. Яндекс такие redirect_uri отклоняет. Поэтому используется out-of-band редирект: Яндекс показывает код на странице, пользователь копирует его в терминал.

• Refresh-токен требует секрет. Обмен authorization code на токен по PKCE проходит без секрета, и Яндекс выдаёт токен, живущий около года. Но grant_type=refresh_token без client_secret Яндекс не принимает. Решение: раз токен живёт год, refresh публичному клиенту не нужен. По истечении пользователь просто логинится заново. Refresh включается только при подстановке собственного OAuth-приложения с секретом.

• Заголовок авторизации не Bearer. На этом легко потерять час отладки. Подробности ниже в граблях API.

Что делать с этим прямо сейчас, по ролям

Автору на Дзене. Если вы ведёте канал и отслеживаете трафик из поиска, MCP-сервер позволяет задавать вопросы о Метрике голосом, без дашбордов. «Какие статьи привели больше всего визитов из органики за месяц?» Ответ придёт в чат, не нужно разбираться в интерфейсе Метрики.

Маркетологу. Сравнение периодов и воронки по целям через run_comparison экономит рутину построения отчётов. Но готовый инструмент пока требует установки Node.js и работы в терминале.

Разработчику, который пишет свой MCP-сервер. Разбор PKCE-авторизации через Яндекс ID без секрета, самый ценный кусок. Код открыт, лицензия MIT, и три описанные грабли OAuth сэкономят часы отладки.

Для тех, кто раньше не сталкивался: что такое ИИ-агент в контексте аналитики? Это программа, которая получает ваш вопрос на обычном языке, сама решает, какие данные запросить и через какой API, выполняет запрос и возвращает ответ. Вы не пишете код запроса, не помните имена полей, не разбираетесь с форматами. MCP-сервер для Метрики делает именно это: превращает набор API-эндпоинтов в пять понятных инструментов, а модель выбирает нужный сама.

Если вы разрабатываете собственный MCP-сервер над любым другим HTTP API, паттерн тот же: мало гибких инструментов лучше, чем сотня кнопок, а PKCE решает проблему секрета для любого распространяемого CLI.