Содержание
Коротко
Автор Habr показал, как дать LLM-агенту доступ к данным Яндекс Вебмастера через сервер протокола MCP. Вместо того чтобы заставлять модель разбираться в нескольких десятках методов API, сервер предлагает восемь предметных инструментов: от списка сайтов и поисковых запросов до диагностики и отправки URL на переобход.
В центре разбора не только обёртка над API, но и пользовательский сценарий: агент замечает отсутствие входа, запускает авторизацию в Яндекс ID и продолжает работу после согласия человека. Код сервера написан на TypeScript и опубликован под лицензией MIT.
Что произошло
Яндекс Вебмастер хранит сведения о том, как поиск видит сайт: показы и клики по запросам, индексацию, найденные ошибки, карты сайта, внешние ссылки и остаток лимита на переобход. Эти данные дополняют Яндекс Метрику: Вебмастер отвечает за путь до клика, а Метрика — за поведение посетителя после него.
Автор не сопоставляет каждому методу API отдельный инструмент MCP. Вместо этого он объединяет вызовы вокруг задачи пользователя. Например, search_queries умеет выдавать как список популярных запросов, так и их динамику, а get_indexing собирает несколько связанных вариантов проверки обхода и индексации.
Такой подход важен для моделей: длинный перечень почти одинаковых названий повышает вероятность ошибочного выбора. Отдельный инструмент get_hosts решает ещё одну практическую проблему — идентификатор сайта в API нельзя надёжно составить из обычного адреса, его нужно сначала запросить.
Почему это важно
Сервер MCP делает API доступным не только для программы, которую заранее написал разработчик, но и для диалога с агентом. Вопрос «какие запросы часто показываются, но редко получают клики» превращается в один вызов инструмента, а не в ручной обход разделов поисковой консоли и сведение цифр в таблице.
При этом агенту нельзя бездумно передавать исходные ответы. Сервер отбрасывает неактуальные диагностические записи, сортирует проблемы по серьёзности и добавляет сводные счётчики. Перед действием recrawl_submit он показывает остаток дневного лимита, чтобы модель не потратила квоту на случайный URL.
Разбор также напоминает, что HTTP-статусы недостаточно считать общими ошибками доступа. Код 401 означает, что требуется новый вход, а 403 говорит о нехватке прав на конкретный сайт. Если не объяснить это в ответе инструмента, агент может бессмысленно повторять авторизацию.
На практике
Для собственного сервера MCP над внешним API полезно начать не с числа методов, а с вопросов, которые должен решать пользователь. Следующие решения из материала особенно применимы к интеграциям с ИИ:
- Сгруппируйте методы API по смысловой задаче. Один гибкий инструмент с понятными режимами обычно надёжнее набора почти одинаковых команд.
- Добавьте явное получение неугадываемых идентификаторов и укажите модели, что его следует вызвать первым.
- Возвращайте компактный, объяснённый результат, а не весь ответ поставщика: текущие проблемы, сводку и следующий шаг при ошибке.
- Разделяйте чтение и действия с побочным эффектом. Перед отправкой URL на переобход показывайте квоту и состояние уже созданных задач.
- Не храните долгоживущий токен в конфигурации
MCP. В материале он сохраняется в отдельном файле с ограниченными правами доступа.
Автор использует OAuth-поток авторизации с кодом и механизмом PKCE, а также локальный адрес перенаправления. При занятом порте остаётся запасной путь с ручной передачей кода, но переключаться на него стоит только при ошибке запуска локального сервера, а не при любой проблеме авторизации.
Итог
Главный вывод материала: авторизация и обработка ошибок — часть интерфейса инструмента для ИИ, а не предварительная настройка, которую пользователь должен пройти в терминале. Сервер, запускающийся без токена и умеющий подсказать агенту следующий шаг, заметно снижает порог входа.
Технический разбор полезен и вне Яндекс Вебмастера. Он показывает, как проектировать интеграции MCP над чужими API: сохранять различия протоколов, кэшировать только успешные ответы и формулировать ошибки так, чтобы модель могла корректно продолжить сценарий.