MCP для агентов

Полное руководство по подключению AI к своему аккаунту Gensite через удалённый MCP.

Удалённый MCP Gensite позволяет AI-агенту работать в вашем аккаунте: получать список проектов, создавать многостраничные сайты и собирать каждую страницу из блоков. Сервер уже работает на проде:

https://gensite.ru/api/mcp

Клонировать репозиторий, устанавливать Node.js, запускать npm run mcp или поднимать локальную копию Gensite не требуется. MCP-клиент отправляет запросы непосредственно на gensite.ru по HTTPS.

Как устроен доступ

Каждое подключение содержит Bearer-токен аккаунта:

Authorization: Bearer gs1.…

По токену Gensite определяет пользователя до выполнения любого инструмента. Агент:

создаёт новые проекты с текущим пользователем в качестве владельца;
получает принадлежащие пользователю и доступные ему проекты;
добавляет, правит, удаляет и переупорядочивает блоки в проектах, где у него есть права редактора;
не получает пароль и браузерную сессию;
не может переключиться на другой аккаунт без другого токена;
не получает административные права только из-за подключения MCP.

Токен действует 30 дней. Его нельзя публиковать, добавлять в Git или отправлять посторонним: он предоставляет такой же программный доступ к проектам, как API-токен.

Каждый выпущенный токен записывается в аккаунт и виден в Настройки → MCP для AI → Активные токены: название, хвост токена, дата выпуска, срок и время последнего использования. Любой токен можно отозвать — следующий запрос с ним получит 401 Токен отозван, без редеплоя и смены серверного секрета. Если токен раскрыт, отзовите его и выпустите новый. Токенов может быть несколько: по одному на каждый клиент или машину.

Сам токен показывается один раз, при выпуске — Gensite его не хранит. Потеряли — отзовите и выпустите новый.

Что потребуется

Аккаунт на gensite.ru.
MCP-клиент с поддержкой удалённых HTTP-серверов: Cursor, Claude Code, VS Code и аналоги.
Токен, выпущенный в настройках аккаунта.

Выпуск токена

Войдите в Gensite.
Откройте Кабинет → Настройки → MCP для AI.
При желании впишите название — где токен будет использоваться («Cursor на ноутбуке», «Claude Code»), чтобы потом отличать его в списке.
Нажмите Выпустить токен.

После этого на странице появятся три вещи:

Токен доступа — голая строка gs1.… без префикса Bearer. Её можно отдать агенту или вставить в поле авторизации любого клиента.
URL сервера — https://gensite.ru/api/mcp, транспорт Streamable HTTP.
Готовый конфиг — выберите клиент в списке (Cursor, Claude Code, VS Code или универсальный .mcp.json), сниппет уже содержит URL и токен; нажмите Скопировать конфиг.

Если агент или клиент просит «токен» отдельно, передавайте именно значение из поля Токен доступа. Если просит заголовок целиком — Authorization: Bearer <токен> с одним пробелом после Bearer.

Подключение в Cursor

Выберите в списке Cursor, скопируйте конфиг и добавьте его в ~/.cursor/mcp.json (глобально) или .cursor/mcp.json в проекте — то же самое открывается через Settings → MCP. Перезапустите сервер MCP в настройках Cursor, если он не подключился автоматически.

{
  "mcpServers": {
    "gensite": {
      "url": "https://gensite.ru/api/mcp",
      "headers": {
        "Authorization": "Bearer gs1.…"
      }
    }
  }
}

Заменять URL на localhost не нужно. Команды command, args, npx и путь к репозиторию также не нужны: это конфигурация удалённого HTTP MCP, а не локального stdio-процесса.

Подключение в Claude Code

Выберите в списке Claude Code и выполните скопированную команду в терминале:

claude mcp add --transport http gensite https://gensite.ru/api/mcp --header "Authorization: Bearer gs1.…"

Проверка — claude mcp list или /mcp внутри сессии. Для проектного .mcp.json подходит универсальный формат из следующего раздела.

Подключение в VS Code / Copilot

Выберите VS Code / Copilot и вставьте конфиг в .vscode/mcp.json проекта или в пользовательскую конфигурацию (MCP: Open User Configuration). Корень здесь называется servers, а не mcpServers:

{
  "servers": {
    "gensite": {
      "type": "http",
      "url": "https://gensite.ru/api/mcp",
      "headers": {
        "Authorization": "Bearer gs1.…"
      }
    }
  }
}

Другие клиенты

Вариант Другой клиент (.mcp.json) даёт переносимый формат mcpServers с явным "type": "http". Он подходит для .mcp.json Claude Code, Codex, Windsurf и большинства клиентов с поддержкой удалённого Streamable HTTP MCP:

{
  "mcpServers": {
    "gensite": {
      "type": "http",
      "url": "https://gensite.ru/api/mcp",
      "headers": {
        "Authorization": "Bearer gs1.…"
      }
    }
  }
}

Если клиент настраивается через форму, а не JSON, достаточно двух значений из настроек: URL сервера и Токен доступа (заголовок Authorization, значение Bearer <токен>).

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

Сам Gensite не открывает диалоги подтверждения внутри MCP. Инструменты передают стандартные annotations: чтение помечено readOnly; создание и обновление проекта, страницы, темы и блока — как недеструктивные изменения; destructive стоит только у delete_project, delete_page и delete_block.

AI-клиент может применять собственную политику и всё равно запрашивать разрешение. Это поведение настраивается на стороне клиента и не может быть отключено MCP-сервером. Если агент пишет, что Gensite доступен «только через браузер», или вызывает GET /projects и получает HTML, он не использует это MCP-соединение и не читает контракт. Проверьте, что в списке инструментов есть whoami, list_projects, create_project, create_page и add_block. Для HTTP-клиентов без MCP базовый URL — https://gensite.ru/api/v1, контракт — https://gensite.ru/api/v1/openapi.json.

Первый запрос агента

После подключения попросите агента:

Вызови whoami и get_product_guide у MCP-сервера Gensite,
затем покажи список моих проектов.

Ожидаемое поведение:

whoami возвращает email и ID аккаунта.
get_product_guide объясняет агенту модель продукта и порядок работы.
list_projects возвращает доступные аккаунту проекты.
После подтверждения задачи агент вызывает create_project.

Отдельный login через MCP отсутствует и не нужен. Авторизация выполняется до вызова инструмента по токену из конфигурации.

Инструменты

`whoami`

Проверяет, к какому аккаунту привязано текущее соединение.

Аргументы отсутствуют. Результат:

{
  "success": true,
  "user": {
    "id": "user_id",
    "email": "agent@example.com",
    "name": "Имя"
  }
}

Используйте этот инструмент первым, если есть сомнение, в чей аккаунт попадёт новый проект.

`get_product_guide`

Возвращает инструкцию для AI: что считается проектом, как устроены блоки, где открыть редактор и какие инструменты вызывать. Аргументы отсутствуют.

Рекомендуется вызывать в начале новой сессии или перед задачей, для которой агенту нужен контекст Gensite.

`list_projects`

Возвращает проекты, доступные текущему аккаунту. В список могут входить:

проекты, которыми пользователь владеет;
проекты, которыми с ним поделились;
общие демонстрационные проекты без владельца.

Аргументы отсутствуют. Основные поля результата:

{
  "success": true,
  "projects": [
    {
      "id": "project_id",
      "title": "Лендинг клиента",
      "slug": "landing-klienta",
      "publishedAt": null,
      "editorPath": "/editor/landing-klienta",
      "editorUrl": "https://gensite.ru/editor/landing-klienta"
    }
  ]
}

publishedAt: null означает черновик. Для надёжной идентификации проекта используйте id, а не только название.

`get_project`

Один проект по projectId или projectSlug. Тот же объект, что элемент list_projects. Не заменяет HTTP GET /projects на корне сайта.

`create_project`

Создаёт пустой проект, владельцем которого становится текущий пользователь.

Аргументы:

title — обязательная непустая строка, название проекта;
clientName — необязательное имя клиента;
description — необязательное описание задачи или сайта.

Пример вызова:

{
  "title": "Сайт студии Север",
  "clientName": "Студия Север",
  "description": "Корпоративный лендинг для дизайн-студии"
}

Успешный результат содержит id, slug, editorPath и абсолютный editorUrl. Проект создаётся как черновик без блоков и не публикуется автоматически.

Перед созданием агенту полезно вызвать list_projects, чтобы не создать очевидный дубликат. Нельзя считать одинаковые названия гарантией дубликата: окончательное решение должен подтвердить пользователь.

`delete_project`

Удаляет проект целиком: страницы, блоки и связанные данные. Только владелец текущего аккаунта. Аргументы: projectId или projectSlug.

Действие необратимо. Редактор с доступом к проекту, но без владения, получит ошибку.

`publish_project`

Публикует проект или возвращает его в черновик. Аргументы:

projectId или projectSlug — проект;
publish — true (по умолчанию) публикует сайт, false снимает с публикации.

Пока проект в черновике, публичная главная показывает заглушку «Проект не опубликован», а подстраницы отвечают 404; смотреть черновик можно только по preview-ссылке. После публикации главная и все подстраницы открываются по публичным адресам.

Ответ содержит published, publishedAt, publicPath и абсолютный publicUrl. Публиковать может владелец или редактор проекта.

Агент должен вызывать инструмент только по явной просьбе: публикация меняет то, что видят посетители сайта.

`get_theme`

Возвращает тему проекта: цвета, шрифты и настройки соцпревью. Аргументы: projectId или projectSlug. Инструмент только читает — вызывайте его перед update_theme, чтобы видеть текущие значения.

`update_theme`

Задаёт оформление сразу для всего сайта: главной, подстраниц и блога. Аргументы:

projectId или projectSlug — проект;
textColor, secondaryColor, backgroundColor, accentBackgroundColor — цвета в hex (#0f172a, #4f46e5);
fontFamily, headingFont — семейства Google Fonts, например Manrope и Sora;
fontFamilyCategory, headingFontCategory — sans-serif, serif, display, handwriting или monospace;
fontSize — базовый размер текста вида 17px или 1.1rem;
lang — язык страниц (ru, en-US);
ogTitle, ogDescription, ogImage, faviconUrl — превью в соцсетях и фавикон.

{
  "projectSlug": "portfolio-ili",
  "backgroundColor": "#0b1020",
  "textColor": "#f8fafc",
  "secondaryColor": "#94a3b8",
  "accentBackgroundColor": "#6366f1",
  "headingFont": "Sora",
  "fontFamily": "Manrope"
}

Меняются только переданные поля, остальная тема сохраняется. null сбрасывает поле к значению по умолчанию. Некорректное значение (цвет не в hex, неизвестная категория шрифта, относительный URL картинки) вернёт ошибку с именем поля, и тема не изменится.

Смена fontFamily или headingFont сбрасывает сохранённый список начертаний: новый шрифт грузится с весами по умолчанию, а подобрать конкретные начертания можно в редакторе темы.

`list_block_types`

Справочник секций конструктора. Не добавляет блоки на страницу.

Ответ группирует блоки по семействам (family), а не плоским списком одинаковых названий:

note — как читать каталог;
recommendedPageOrder — типичный порядок секций лендинга сверху вниз;
families[] — семейство, поток (main | popup | utility | blog), зачем блок (purpose), когда брать (whenToUse), макеты (variants).

У варианта:

type — идентификатор макета в редакторе, например cover__cover_1 (вид семейство__семейство_id); его и передают в add_block;
title — человекочитаемое имя макета, уникальное внутри семейства;
description — что это за макет и когда его брать;
label и layout — те же title и description, оставлены для старых клиентов;
fields — ключи, которые принимают add_block.fields и update_block_content.fields.

Потоки:

main — секция страницы;
popup — всплывающее окно, не стоит в ленте;
utility — CSS или JavaScript без видимой секции;
blog — шаблоны блога проекта, не обычный лендинг услуг.

Агенту: вызывать перед выбором структуры сайта, а type варианта передавать в add_block.

`list_pages`

Возвращает обычные подстраницы проекта по порядку. Аргументы: projectId или projectSlug. У каждой страницы есть id, slug, title/SEO, blockCount, editorPath, previewPath и publicPath.

Шаблоны блога в этот список не входят.

`create_page`

Создаёт подстраницу. Обязательные аргументы:

projectId или projectSlug;
slug — адрес внутри сайта, например services;
title — название страницы.

Необязательно можно сразу передать metaTitle, metaDescription и ogImage. После создания используйте возвращённый page.id в add_block.

`update_page`

Меняет title, slug и SEO обычной подстраницы. Передайте проект и pageId либо pageSlug. Значение null очищает SEO-поле.

`delete_page`

Удаляет обычную подстраницу вместе с её блоками. Шаблоны блога инструмент не удаляет.

`reorder_pages`

Принимает проект и pageIds — все id обычных подстраниц в нужной последовательности, без повторов и пропусков.

`list_project_blocks`

Блоки главной или выбранной подстраницы в порядке сверху вниз. Всегда передайте projectId или projectSlug. Для подстраницы дополнительно передайте pageId либо pageSlug; без них инструмент читает главную.

{
  "success": true,
  "projectId": "project_id",
  "blocks": [
    {
      "id": "block_id",
      "type": "cover__cover_1",
      "order": 0,
      "fields": {
        "text": {
          "title": "Илья — фронтенд-разработчик",
          "description": "React, TypeScript, современная вёрстка",
          "ctaFill.text": "Связаться",
          "ctaFill.href.value": "#contacts",
          "image.url": "https://example.com/ilya.png"
        },
        "numbers": {},
        "toggles": { "root.isVisible": true, "fullHeight": false },
        "lists": {}
      }
    }
  ]
}

fields — карта правимых путей: text для строк, numbers для чисел, toggles для переключателей, lists для длины списков. Эти же ключи принимают add_block и update_block_content.

Пути бывают вложенными: ctaFill.href.value — ссылка кнопки, items[0].title — первая строка списка, items[0].image.url — картинка этой строки. Очень длинные значения (например, data-URI картинки-заглушки) в ответе обрезаны с пометкой …(обрезано) — ключ от этого не меняется.

`add_block`

Добавляет секцию на главную или выбранную подстраницу. Аргументы:

projectId или projectSlug — проект;
pageId или pageSlug — необязательно; без них блок добавляется на главную;
type — макет из list_block_types, например cover__cover_1;
position — необязательный индекс вставки сверху вниз; по умолчанию блок идёт в конец;
fields — необязательные значения полей, чтобы сразу наполнить блок;
sharedAcrossPages — необязательный флаг «показывать на всех страницах» для блока главной;
sharedPosition — before (сверху подстраниц) или after (снизу) для общего блока.

{
  "projectSlug": "portfolio-ili",
  "type": "cover__cover_1",
  "fields": {
    "title": "Илья — фронтенд-разработчик",
    "description": "React, TypeScript, современная вёрстка",
    "ctaFill.text": "Связаться"
  }
}

Блок создаётся со значениями по умолчанию, поверх которых накладывается fields. Ответ содержит id, order и актуальные fields.

Ключи для нового блока заранее видны в variants[].fields ответа list_block_types. Если ключ не подошёл, ошибка перечислит доступные поля этого блока.

`update_block_content`

Меняет тексты и переключатели существующего блока. Аргументы: blockId и fields. Передаются только изменяемые ключи, остальное состояние блока сохраняется.

Неизвестный ключ вернёт ошибку с его именем — сверьтесь с list_project_blocks. Поля оформления отдельного блока (style.*) через MCP не меняются: цвета и шрифты задаются через update_theme, а точечные правки — CSS в блоке customStyles.

`set_block_sharing`

Включает или снимает у блока главной страницы показ на всех страницах сайта. Аргументы: blockId, sharedAcrossPages и необязательный sharedPosition (before | after).

Инструмент работает только с блоками главной: у блока подстраницы вернётся ошибка. Пригодится, когда меню или футер уже созданы отдельно на каждой странице и их нужно свести к одному экземпляру.

`delete_block`

Удаляет блок главной или подстраницы по blockId. Порядок оставшихся блоков пересчитывается автоматически.

`reorder_blocks`

Задаёт порядок блоков. Аргументы: проект, необязательная подстраница и blockIds — все id выбранной страницы в нужной последовательности, без повторов и пропусков. Иначе инструмент вернёт ошибку и порядок не изменится.

Общие блоки на всех страницах

Блок главной страницы с sharedAcrossPages: true рендерится и на подстраницах: sharedPosition: "before" ставит его сверху (меню, header), "after" — снизу (футер). Так меню и футер живут в одном экземпляре: правка через update_block_content меняет их на всём сайте сразу.

Тот же приём работает для блока customStyles — один CSS применяется ко всем страницам.

Флаг доступен только блокам главной. add_block с sharedAcrossPages: true и заданной подстраницей вернёт ошибку, а уже созданный блок главной переключается через set_block_sharing.

Единое оформление сайта

Цельный вид даёт тема проекта, а не настройки отдельных секций:

update_theme — цвета, шрифты, базовый размер текста и соцпревью на весь сайт.
Блок customStyles (поток utility, поле css) — точечные правки, которых нет в теме.
add_block с sharedAcrossPages: true для этого блока — CSS действует на всех страницах.

В CSS опирайтесь на переменные темы, чтобы стили не расходились с настройками проекта: --theme-text, --theme-secondary-text, --theme-background, --theme-accent, --theme-font-family, --theme-heading-font.

.section-title {
  font-family: var(--theme-heading-font);
  letter-spacing: -0.02em;
}

Границы работы с блоками

Главная и обычные подстраницы доступны через одни block-инструменты; для подстраницы передавайте pageId.
Попапы и шаблоны блога пока редактирует человек.
Длина списков фиксирована шаблоном блока: fields меняет существующие строки (items[0], items[1]), а добавление и удаление строк делается в редакторе. Если элементов нужно больше, чем в шаблоне, добавьте второй блок того же семейства.
Загрузка файлов недоступна: изображения задаются URL в полях вида image.url.
Отступы и типографику отдельной секции настраивает человек в редакторе: у агента есть тема проекта и блок customStyles.
Добавление блоков сайт не публикует: публикация — отдельный вызов publish_project по просьбе пользователя.

Ошибки подключения

`401 Unauthorized`

Токен отсутствует, повреждён, истёк или отозван. Текст ошибки уточняет причину:

Некорректный токен — строка повреждена или скопирована не целиком;
Срок токена истёк — прошло 30 дней;
Токен отозван — его отозвали в настройках;
Токен устаревшего формата — выпущен до появления списка токенов; выпустите новый.

Выпустите новый токен в Настройки → MCP для AI и замените значение целиком, включая префикс Bearer.

Отозвать доступ агента

Откройте Настройки → MCP для AI → Активные токены и нажмите Отозвать у нужного токена — или Отозвать все, если не уверены, какой из них раскрыт. Доступ прекращается немедленно, ничего перезапускать не нужно.

Сервер не появляется в клиенте

Проверьте:

URL равен https://gensite.ru/api/mcp;
конфигурация содержит поле url, а не локальные command и args;
корень соответствует клиенту: mcpServers для Cursor и .mcp.json, servers для VS Code;
заголовок называется Authorization;
значение начинается с Bearer и содержит один пробел; если клиент просит только токен — вставлен gs1.… без Bearer;
JSON не содержит комментариев и завершающих запятых.

Агент видит не тот аккаунт

Вызовите whoami. Затем выпустите токен, находясь в нужном аккаунте, и замените конфигурацию MCP.

Токен работал, а затем перестал

Либо прошли 30 дней, либо токен отозвали в настройках — в списке активных токенов его больше нет. Выпустите новый токен. Повторный деплой Gensite или перезапуск PM2 для этого не нужен.

Проект создан, но страница пустая

create_project создаёт только черновик. Блоки добавляются отдельными вызовами add_block. Если агент сообщает, что «редактор не применяет блоки», проверьте по его логу, вызывал ли он add_block: попытки кликать в интерфейс браузером к MCP не относятся.

`Неизвестный тип блока`

type не найден в реестре. Возьмите значение из variants[].type в ответе list_block_types, например cover__cover_1, а не название семейства.

`У блока нет поля …`

Ключ отсутствует в состоянии блока. Текст ошибки перечисляет доступные поля; их же отдают variants[].fields в list_block_types и fields в list_project_blocks. Частая причина — ключ из другого семейства: у обложки заголовок называется title, а у каталога — header.title.

Прямой HTTP API

MCP — рекомендуемый способ дать AI типизированные инструменты и инструкции. Если агент или интеграция не поддерживает MCP, подключите OpenAPI https://gensite.ru/api/v1/openapi.json и работайте с базовым URL https://gensite.ru/api/v1 тем же Bearer-токеном.

Полные форматы регистрации, логина, проектов, страниц, блоков и темы описаны в статье HTTP API v1.

Если клиент не умеет URL

Для продакшена нужен клиент с поддержкой удалённого Streamable HTTP MCP. Локальный mcp/server.ts остаётся только инструментом разработки Gensite и не требуется пользователям продукта.

Как устроен доступ

Что потребуется

Выпуск токена

Подключение в Cursor

Подключение в Claude Code

Подключение в VS Code / Copilot

Другие клиенты

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

Первый запрос агента

Инструменты

whoami

get_product_guide

list_projects

get_project

create_project

delete_project

publish_project

get_theme

update_theme

list_block_types

list_pages

create_page

update_page

delete_page

reorder_pages

list_project_blocks

add_block

update_block_content

set_block_sharing

delete_block

reorder_blocks