agentsready
API / Auth / MCP Сложно

WebMCP: инструменты сайта для браузерного AI-агента

Что такое WebMCP (браузерный API document.modelContext), чем он отличается от удалённого MCP-сервера, минимальный пример registerTool, ошибки и как проверить.

Обновлено:

Что это

WebMCP — браузерный JavaScript API из черновика W3C Web Machine Learning Community Group (авторы из Microsoft и Google). Страница регистрирует «инструменты» (tools) — функции с именем, описанием и JSON Schema входных параметров — через document.modelContext.registerTool(). AI-агент браузера (или агент в iframe или расширении) вызывает эти функции напрямую, вместо того чтобы кликать по DOM.

Код инструмента выполняется на самой странице, в сессии пользователя: те же cookie, тот же стейт приложения. С MCP у WebMCP общий словарь (tools, inputSchema), но это не MCP-протокол поверх сети: у WebMCP нет серверного endpoint, транспорта и URL для подключения.

Не путайте с удалённым MCP-сервером (транспорт Streamable HTTP / SSE по адресу вроде /mcp) — это отдельный механизм, он обнаруживается через MCP Server Card.

Зачем это AI-агентам

Агент, который управляет сайтом через скриншоты и клики, медленный и хрупкий: поменялась вёрстка — сценарий сломался. WebMCP даёт явный контракт: «вот какие действия здесь доступны и с какими параметрами». Плюсы:

  • Надёжность — вызов функции вместо угадывания кнопок.
  • Без отдельного бэкенда для агентов — инструмент переиспользует клиентский код и авторизацию пользователя.
  • Пользователь в контуре — результат действия виден в интерфейсе, который он уже открыл.

Статус на октябрь 2026: origin trial в Chrome 149 и Edge 150 (локальная разработка — флаг about:flags#enable-webmcp-testing), поддержка в ChatGPT Desktop, экспериментально в Brave; у Firefox и Safari позиции пока нет. Декларативный вариант через <form> удалён из спецификации 8 октября 2026 — остаётся императивный API.

Минимальный рабочий пример

<script type="module">
  if ('modelContext' in document) {
    const controller = new AbortController();

    await document.modelContext.registerTool({
      name: 'add-to-cart',
      description: 'Добавляет товар в корзину по артикулу',
      inputSchema: {
        type: 'object',
        properties: {
          sku: { type: 'string', description: 'Артикул товара' },
          qty: { type: 'integer', minimum: 1, description: 'Количество' },
        },
        required: ['sku'],
      },
      async execute({ sku, qty = 1 }) {
        // Та же функция, что у кнопки «В корзину»: проверки, сессия, обновление UI
        const item = await addToCart(sku, qty);
        return { content: [{ type: 'text', text: `В корзине: ${item.title} × ${qty}` }] };
      },
    }, { signal: controller.signal });

    // controller.abort() снимает инструмент — например, когда он стал неприменим
  }
</script>

API доступен только в secure context (HTTPS). Агентам в cross-origin iframe инструменты видны только при allow="tools" на iframe и явном списке origin в опции exposedTo при регистрации. Изменения набора инструментов сопровождаются событием toolchange.

Правильно vs неправильно

ПравильноНеправильно
Несколько инструментов, у каждого одна задачаДесятки инструментов «на всё» — съедают контекст модели
Ввод, права и предусловия проверяются внутри executeДоверие аргументам агента — схема не защита
После вызова UI обновляется так же, как после кликаДействие прошло «невидимо», интерфейс показывает старое состояние
Инструменты регистрируются и снимаются по состоянию приложения (AbortSignal)Все инструменты висят всегда, даже когда неприменимы
Проверка 'modelContext' in document перед вызовомОшибка в браузерах без WebMCP

Типичные ошибки

  • Путать WebMCP с удалённым MCP-сервером — endpoint /mcp и SSE-транспорт к WebMCP не относятся.
  • Старый API navigator.modelContext — в актуальной спецификации объект висит на document.
  • Декларативные <form>-инструменты — удалены из спецификации, не стройте на них.
  • Нет проверок в execute — агент может передать что угодно; валидируйте как пользовательский ввод.
  • Страница по HTTP — вне secure context document.modelContext недоступен.

Как проверить

Проверка webmcp в сканере информационная (вес 0, на балл не влияет) и пока не выполняется: инструменты регистрируются из JavaScript, а сканер не исполняет скрипты страницы. Дешёвый статический сигнал возможен — вызов modelContext.registerTool в скриптах страницы, — но он показывает лишь наличие кода, а не работающие инструменты.

Вручную:

  1. Chrome 149+ с флагом about:flags#enable-webmcp-testing (или origin trial на вашем домене).
  2. Откройте страницу по HTTPS и в консоли DevTools выполните 'modelContext' in document — должно быть true.
  3. По спецификации await document.modelContext.getTools() возвращает инструменты, зарегистрированные на странице, — ваши должны быть в списке.

Источники