MCP-сервер: подключение ИИ-помощников (версия 126)

MCP (Model Context Protocol) — открытый протокол, который позволяет ИИ-помощникам (Claude, Cursor и другим) обращаться к внешним программам и пользоваться их инструментами. SEOMaster предоставляет проверенные технические данные, а помощник помогает человеку их осмыслить. В самом сервисе по-прежнему работают только PHP и обычные алгоритмы: MCP лишь открывает доступ к тем же методам, что и API, с теми же правами ключа, лимитами и правилами. Отдельной системы расчётов нет.

Что это даёт

Вы задаёте вопрос обычными словами, например: «Почему у моего сайта уменьшилось число страниц в поиске за последнюю неделю?». Помощник сам вызывает нужные инструменты (индексация, различия проверок, недавние исправления, первопричина), получает данные и составляет объяснение: что произошло, какие причины вероятны и в каком порядке действовать.

Подключение

Адрес сервера: https://ваш-сервис/mcp. Авторизация — заголовок Authorization: Bearer smk_… (тот же ключ API). Готовые настройки с вашим ключом показаны в кабинете: «API и вебхуки» → «ИИ-помощники (MCP)».

Claude Code:

claude mcp add --transport http seomaster https://seo.example/mcp --header "Authorization: Bearer smk_…"

Cursor, VS Code и другие клиенты, которые принимают заголовки (mcp.json):

{"mcpServers": {"seomaster": {"url": "https://seo.example/mcp", "headers": {"Authorization": "Bearer smk_…"}}}}

Claude Desktop, через мост mcp-remote (нужен Node.js):

{"mcpServers": {"seomaster": {"command": "npx", "args": ["-y", "mcp-remote", "https://seo.example/mcp", "--header", "Authorization:${SEOMASTER_AUTH}"], "env": {"SEOMASTER_AUTH": "Bearer smk_…"}}}}

Запуск как программы (stdio), если на компьютере есть PHP: самостоятельный файл bin/mcp.php пересылает сообщения на сервер.

SEOMASTER_URL=https://seo.example SEOMASTER_KEY=smk_… php bin/mcp.php

Переменные: SEOMASTER_URL, SEOMASTER_KEY, необязательные SEOMASTER_TOOLS, SEOMASTER_READONLY, SEOMASTER_LANG. ChatGPT и веб-версия Claude подключаются кнопкой через вход OAuth (см. ниже).

Подключение кнопкой (OAuth)

ChatGPT и claude.ai подключают сервер без заголовка: добавьте свой коннектор с адресом https://ваш-сервис/mcp и нажмите «Подключить». Откроется страница SEOMaster: войдите в аккаунт, отметьте права (чтение включено всегда; запуск проверок и изменение данных — по желанию) и нажмите «Разрешить». Протокол — OAuth 2.1:

• метаданные: /.well-known/oauth-protected-resource (защищённый ресурс /mcp) и /.well-known/oauth-authorization-server (адреса конечных точек); ответ 401 на /mcp указывает на них в заголовке WWW-Authenticate (resource_metadata);
• динамическая регистрация клиентов: POST /oauth/register (RFC 7591); адрес возврата — https, http://localhost или схема приложения; до 20 регистраций в час с одного адреса;
• вход: GET /oauth/authorize — код с обязательным PKCE (code_challenge_method=S256), state и resource проверяются, ответ содержит iss (RFC 9207);
• токены: POST /oauth/token — authorization_code и refresh_token; отзыв: POST /oauth/revoke (RFC 7009).

Токен доступа — обычный ключ API (smk_…) с выбранными правами: он работает в MCP и в REST API, виден в «API и вебхуки → Ключи» с пометкой OAuth, а вкладка «ИИ-помощники (MCP)» показывает все подключения. Токен живёт сутки и обновляется приложением само; refresh-токен меняется при каждом обновлении и действует 90 дней с последнего использования. Повторное использование старого refresh-токена или кода отзывает доступ целиком. Отзыв ключа в «Ключах» закрывает доступ немедленно, повторное подключение того же приложения заменяет прежнее. Если сервис стоит за прокси, задайте SEOMASTER_BASE_URL (адрес с https).

Ключ и права

Для помощника заведите отдельный ключ (кнопка в кабинете создаёт его с правом read). Набор инструментов определяется правами ключа: с read помощник видит только чтение; run добавляет запуск проверок, write — изменение данных. Ключ можно отозвать в любой момент; журнал вызовов виден в карточке ключа. Каждый вызов инструмента — запрос API в лимите ключа (по умолчанию 120 в час; для помощника кнопка в кабинете задаёт не меньше 120): помощник делает несколько вызовов на один вопрос, при необходимости поднимите лимит ключа.

Инструменты

Всего 62; каждый соответствует методу API (подробности и параметры — в справочнике «API_REFERENCE»). Названия общие для API, CLI и MCP.

Ключ (account)

Сайты (sites)

Данные сайта (site-data)

Задачи (tasks)

События (events)

Трафик (traffic)

Позиции (positions)

Глубокий обход (deep)

Сторонние API (providers)

Соцсети (social)

Конкуренты (competitors)

Диагностика (diagnosis)

Вебхуки (webhooks)

Проверки (checks)

Индексация (indexing)

Рынок (market)

Тип сайта (profile)

Справка (help)

Задания (jobs)

Поиск и ссылки (search)

Утилиты (utilities)

Сводки (digest)

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

Любой инструмент, который меняет данные или расходует лимит проверок, сначала возвращает не результат, а описание действия:

{"confirmation_required": true, "tool": "start_analysis", "action": "Будет запущена проверка сайта example.com: расходуется суточный лимит проверок вашего тарифа.", "arguments": {"host": "example.com"}, "next": "Спросите пользователя…"}

Помощник должен спросить вас и только после согласия повторить вызов с confirmed=true. Кроме того, такие инструменты помечены в протоколе как не «только чтение» (и удаление — как разрушающее), поэтому клиенты показывают собственный запрос разрешения. Сервер не может проверить, что человек действительно согласился: это обязанность клиента и помощника, поэтому давайте права run и write только тем помощникам, которым доверяете.

Ресурсы и готовые сценарии

Ресурсы (resources): seomaster://sites, seomaster://plan, seomaster://today, seomaster://utilities, seomaster://guide и шаблоны seomaster://site/{host}/issues, …/changes, …/indexing, seomaster://explain/{code}. Готовые сценарии (prompts) — заготовки вопросов с порядком вызова инструментов:

Наборы инструментов

Чтобы не перегружать помощника и сузить доступ, добавьте параметры к адресу: ?tools=essentials — основной набор из 21 инструмента; ?tools=site-data,indexing — только указанные группы (коды групп указаны в заголовках разделов выше; неизвестная группа отклоняется ошибкой, как и у других серверов); ?readonly=1 — без действий; ?lang=en — описания на английском (по умолчанию русский).

Безопасность

• Вебхуки через MCP не публикуются: адрес для событий, подсказанный текстом чужой страницы, был бы каналом утечки данных. Их можно настраивать только в кабинете или через API.
• Тексты со страниц сайтов (заголовки, анкоры, запросы) — недоверенные данные. Сервер сообщает об этом помощнику в инструкции; тем не менее внимательно относитесь к просьбам помощника, которые пришли «из данных».
• Запросы из браузера принимаются только с разрешённых источников (адрес сервиса, claude.ai, chatgpt.com и список mcp_origins в настройках); остальные получают 403.
• Ответ инструмента ограничен 60 КБ: длинные списки укорачиваются, в ответе есть поле _truncated с числом показанных и общих элементов. Для остального есть limit и offset.
• Данные видит только владелец ключа; права и IP-ограничения ключа действуют так же, как в API.

Протокол

Транспорт — Streamable HTTP: только POST /mcp с одним сообщением JSON-RPC 2.0, ответ application/json (без потоков SSE и без сеансов). GET и DELETE дают 405. Пакеты запросов не поддерживаются (убраны в версии протокола 2025-06-18). Поддерживаемые версии: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Методы: initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read, prompts/list, prompts/get.

Ошибки авторизации и лимита приходят с HTTP-кодом 401, 403 или 429 и телом JSON-RPC: {"error": {"code": -32001, "message": "…", "data": {"code": "invalid"}}}; коды data.code — те же, что в API (missing, invalid, revoked, expired, ip, blocked, limit, maintenance, server). Ошибка самого инструмента приходит как обычный результат с isError: true и телом {"error", "code", "http", "retryable", "hint"}, чтобы помощник мог на неё отреагировать. Ошибки протокола (неизвестный инструмент, неверные параметры) — стандартные ошибки JSON-RPC.

Ограничения

• Вход OAuth требует публичного адреса с https; для работы на закрытой сети используйте ключ в заголовке.
• Сервер не отправляет уведомления и не ведёт сеансы; долгие операции — задания, ход смотрите через get_job.
• Данные, которых нет (источник не подключён, проверка не запускалась), возвращаются как not_ready с пояснением; помощник не должен их выдумывать, но это зависит от модели.
• Описания инструментов и сценарии — на русском и английском; plain и guide в explain_check — только на русском.
• Согласие на действие обеспечивается описанием инструмента, пометками протокола и запросом клиента, а не проверкой на сервере.