MCP-сервер для SEO: как подключить свои инструменты к Claude, Cursor и другим клиентам

Статья 2 цикла «AI-агенты в техническом SEO: от MCP-серверов до автоматизации аудита». Статья 1 описала слой action абстрактно — «инструменты, через которые агент действует». Здесь мы даём конкретный протокол: как собрать MCP-сервер, который отдаёт ваши SEO-данные и действия любому совместимому агенту.

Когда вы решаете «подключить модель к своим данным», есть два пути. Первый — писать интеграцию под каждый клиент отдельно: свой мост под Claude, свой под Cursor, свой под собственный цикл. Второй — один раз реализовать Model Context Protocol (MCP) и получить совместимость со всеми клиентами сразу. MCP стал де-факто стандартом именно потому, что это второй путь: сервер ничего не знает о модели, которая его вызывает, — он знает только контракт.

Для инженера, который сам хостит краулер, сам ходит в GSC API и сам платит за токены, это означает: выносите инструменты в MCP один раз, и их видит любой агент — и Claude Desktop за вашим столом, и production-цикл на сервере.

1. MCP — это протокол, а не библиотека

MCP описывает, как клиент (LLM-приложение) и сервер (ваши инструменты) обмениваются JSON-RPC-сообщениями. Модель не «знает» ваш сайт — она умеет его опросить через объявленные сервером возможности. Три типа таких возможностей, и это единственное, что нужно понять на входе:

  • Tools — функции, которые агент вызывает, чтобы что-то сделать или получить: crawl_url, get_gsc_pages. Это активное действие, у него есть входы, выходы и побочные эффекты.
  • Resources — данные, которые агент читает как контекст, по URI (gsc://example.com/pages, page://.../audit). Это пассивные, идемпотентные источники правды.
  • Prompts — шаблоны размеченных последовательностей сообщений, которые клиент подставляет пользователю («проанализируй выдачу по запросу X»).

SEO-инструменты ложатся на это естественно: краулинг и валидация — это tools, снимки GSC и страницы аудита — resources, типовые разборы — prompts.

2. Транспорт: stdio против Streamable HTTP

Здесь чаще всего ошибаются, потому что в сети живёт устаревший материал. Актуально так:

  • stdio — клиент запускает ваш сервер как дочерний процесс и общается через stdin/stdout. Идеально для локального MCP (Claude Desktop на вашей машине, ваш собственный цикл на том же хосте). Нет сети, нет аутентификации, нет лишних портов.
  • Streamable HTTP — сервер висит на HTTP-эндпоинте, клиент ходит к нему. Нужен, когда сервер remote: прод-цикл, общая команда, несколько клиентов из разных мест.

Старый транспорт HTTP+SSE (из версии протокола 2024-11-05) помечен deprecated начиная с 2025-03-26 и заменён на Streamable HTTP; свежая спецификация (2026-07-28) относит его к устаревшим. Если в туториале вам советуют «поднимать SSE-эндпоинт» — это устаревший путь; для remote сегодня выбирают Streamable HTTP.

Жизненный цикл сессии короткий и одинаков для обоих транспортов: клиент при подключении делает initialize (обмен версиями протокола и возможностями), сервер отвечает, что у него есть tools/resources/prompts, и дальше идёт обычная работа. При stdio сессия = время жизни процесса; при HTTP — на эндпоинт, с опциональным Session-Id для stateful-случаев.Схема: MCP-клиент ↔ транспорт ↔ MCP-сервер SEO:

Схема: MCP-клиент ↔ транспорт ↔ MCP-сервер SEO

3. Какие SEO-инструменты выносить в MCP

Не все. Критерий простой: инструмент имеет смысл в MCP, если у него есть проверяемый контракт и он переиспользуется между клиентами. Краулер, обёртка над GSC, валидатор schema, генератор отчётов — да. Одноразовый скрипт «прогнать один экспорт» — нет, это просто bash.

Полезная связка из четырёх инструментов закрывает большую часть технического аудита:

ИнструментТипПобочный эффект
get_gsc_pages(site, days)tool (read)нет — только чтение GSC API
crawl_url(url)tool (read)нет — GET по URL
validate_schema(url)tool (read)нет — парсит JSON-LD, сверяет со схемой
apply_link(url, anchor, href)tool (write)есть — меняет страницу

Последняя строка — единственная, где агент что-то пишет. И именно она упирается в границу автономии из статьи 1: write-инструмент существует, но по умолчанию требует подтверждения.

4. Контракт инструмента: входы, выходы, идемпотентность, ошибки, лимиты

Контракт — это то, что отличает инструмент от «надежды на модель». Соберём рабочий пример на Python (FastMCP — реализация протокола; инструменты объявляются декоратором @mcp.tool, а схему входов FastMCP генерирует из аннотаций типов автоматически).

Python
# seo_mcp_server.py — MCP-сервер SEO-инструментов (FastMCP, Python)
from fastmcp import FastMCP
from fastmcp.exceptions import ToolError
from typing import Annotated
import httpx

mcp = FastMCP("seo-tools", mask_error_details=True)  # не светим внутренние детали клиенту

# Минимальные хелперы, чтобы пример был самодостаточным.
import re
def _extract_title(html):
    m = re.search(r"<title>(.*?)</title>", html, re.S | re.I)
    return m.group(1).strip() if m else None
def _extract_canonical(html):
    m = re.search(r"<link[^>]+rel=[\"']canonical[\"'][^>]+href=[\"']([^\"']+)", html, re.I)
    return m.group(1) if m else None
def _build_link_diff(url, anchor, href):
    return f"--- {url}\n+++ {url}\n@@\n+ <a href=\"{href}\">{anchor}</a>"

@mcp.tool()
async def get_gsc_pages(
    site: Annotated[str, "URL ресурса, напр. https://example.com"],
    days: Annotated[int, "Глубина окна в днях"] = 28,
) -> dict:
    """Страницы и их клики/показы из Search Console за окно.

    Read-only, идемпотентен: одинаковый вход -> одинаковый снимок
    при неизменном GSC. Ошибку API превращаем в ToolError, чтобы
    агент видел сбой и мог отреагировать, а не получал пустоту.
    """
    if not 1 <= days <= 480:                      # лимит на входе
        raise ToolError(f"days вне диапазона 1..480: {days}")
    try:
        async with httpx.AsyncClient(timeout=30) as c:
            r = await c.post("https://example.com/gsc/query",
                             json={"site": site, "days": days})
            r.raise_for_status()
            return r.json()                        # dict -> structuredContent
    except httpx.HTTPError as e:
        raise ToolError(f"GSC недоступен: {e}")   # mask_error_details скроит детали

@mcp.tool()
async def crawl_url(
    url: Annotated[str, "Полный https-URL"],
) -> dict:
    """Фетч страницы: статус, <title>, финальный URL, canonical.

    Возвращаем доказательства, а не интерпретацию — reasoning-слой
    решает сам. Не ходим на приватные адреса (защита от SSRF).
    """
    async with httpx.AsyncClient(timeout=20, follow_redirects=True) as c:
        r = await c.get(url)
    html = r.text
    return {
        "url": str(r.url),
        "status": r.status_code,
        "title": _extract_title(html),
        "canonical": _extract_canonical(html),
    }

@mcp.tool(annotations={"readOnlyHint": False, "destructiveHint": True})
async def apply_link(
    url: Annotated[str, "Страница-источник"],
    anchor: Annotated[str, "Текст ссылки"],
    href: Annotated[str, "URL цели"],
) -> dict:
    """Единственный write-инструмент. Помечен как небезопасный:
    readOnlyHint=False -> клиент НЕ пропустит подтверждение;
    destructiveHint=True -> UI подсветит риск. Сама запись на прод
    здесь отсутствует намеренно — инструмент возвращает ДИФФ, а
    применяет его человек (см. статью 6 про guardrails)."""
    return {"diff": _build_link_diff(url, anchor, href), "applied": False}

Что здесь заложено как контракт, а не как детали реализации:

  • Входы типизированы и ограничены. days имеет диапазон, проверка на входе, ошибка — через ToolError, а не молчаливый пустой ответ.
  • Идемпотентность read-инструментов. get_gsc_pages и crawl_url при неизменном источнике дают одинаковый результат — это позволяет кэшировать и безопасно повторять.
  • Выходы — структурированные. Возврат dict FastMCP превращает в structuredContent + человекочитаемый content; агент получает и то и то.
  • Ошибки не текут наружу. mask_error_details=True не даёт внутреннему тексту исключения уйти клиенту — важно, когда сервер remote.
  • Write-инструмент возвращает дифф, а не применяет. Это ровно граница из статьи 1: «предложение», а не «действие».

Как это связано с вашим реальным плагин-контрактом

Если вы делали что-то вроде проверки ссылок на источники, вы уже проектировали контракт инструмента, просто не называли его MCP. Там ровно те же пять элементов: отдельная модель под конкретную задачу (не «чат вообще», а модель с веб-поиском под инструмент), резерв бюджета до запроса (иначе выбивает из квоты), независимое получение доказательств (реальный HTTP-фетч страницы, а не память модели), честный статус (not_found ≠ «не существует») и отсутствие write-действий по дизайну. MCP не меняет эту инженерию — он лишь стандартизирует транспорт, чтобы тот же инструмент увидели и Claude, и Cursor, и ваш цикл, без трёх отдельных мостов.

5. Безопасность: аутентификация, скоупы, read-only vs write, аудит

  • Аутентификация. stdio-сервер живёт локально и «аутентификации» не требует — граница доступа это сам процесс и его окружение (ключи GSC лежат в env, не в коде). Streamable HTTP требует настоящей авторизации; в протоколе для remote это OAuth 2.1 с токеном на каждый вызов — не прячьте сервисный токен в заголовок без проверки.
  • Скоупы. Разделяйте read-инструменты и write-инструменты на уровне доступа: токен, которому выдал только чтение, физически не должен мочь вызвать apply_link.
  • read-only vs write — это аннотации, а не только слова. readOnlyHint=True говорит клиенту «можно без подтверждения», destructiveHint=True — «подсвети риск». Клиенты (Claude, ChatGPT) по этим хинтам решают, спрашивать ли пользователя. Но аннотации — подсказка, а не защита: настоящий контроль — на сервере, в коде инструмента.
  • Аудит вызовов. Логируйте каждый tools/call: кто, какой инструмент, с какими аргументами, какой статус. Для write-инструментов — обязательная запись до и после. Это то, что превращает «агент что-то поменял» в «вот журнал, что и когда».

6. Подключение к клиентам: один сервер, много мест

Ключевое преимущество: вы не пишете код под клиента, вы добавляете его в конфиг. Форма почти одинаковая — корень mcpServers, локальный сервер через command+args+env, remote через url+headers.

Claude Desktop — файл claude_desktop_config.json (Settings → Developer):

JSON
{
  "mcpServers": {
    "seo-tools": {
      "command": "uv",
      "args": ["--directory", "/opt/seo-mcp", "run", "seo_mcp_server.py"],
      "env": { "GSC_TOKEN": "<ввести-сюда>" }
    }
  }
}

Cursor — ~/.cursor/mcp.json; для stdio у него обязателен явный маркер "type": "stdio":

JSON
{
  "mcpServers": {
    "seo-tools": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/opt/seo-mcp", "run", "seo_mcp_server.py"],
      "env": { "GSC_TOKEN": "<ввести-сюда>" }
    }
  }
}

Для remote-варианта (Streamable HTTP) вместо command/args дают "url": "https://mcp.example.com/..." и "headers" с авторизационным токеном. Тот же сервер, тот же контракт — меняется только эти четыре строчки конфига.

👤 Зарегистрируйтесь, чтобы добавить материал в закладки.