Подключение агента по MCP

На сайте «Вручай» работает сервер MCP (Model Context Protocol). Агенту не нужно изучать REST и собирать запросы руками: он видит готовые инструменты — «создать документ», «свёрстать лист», «посмотреть превью», «выпустить», «дать ссылку на архив» — и вызывает их сам. Здесь собрано, как подключить сервер к Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex, Gemini CLI и другим клиентам, какие инструменты он даёт и что делать, если подключение не заработало.

Быстрее всего — поручить подключение самому агенту. Скажите ему одну фразу:

Подключи себе сервис «Вручай» по инструкции https://vruchay.ru/docs/connect.md и проверь подключение вызовом get_account.

Агент в Claude Code, Codex, Gemini CLI, VS Code или Cursor добавит сервер сам и попросит вас один раз войти в кабинет и нажать «Разрешить». В Claude.ai и ChatGPT он подскажет, где нажать. Инструкция для агента — connect.md.

Адрес

https://vruchay.ru/mcp

• Транспорт — Streamable HTTP. Сервер отвечает на каждый POST сразу одним JSON, без потока событий и без сессий: заголовок Mcp-Session-Id не выдаётся и не нужен.
• GET и DELETE отвечают 405 — так и задумано: уведомлений сервер не шлёт, закрывать нечего.
• Версии протокола: новая 2026-07-28 (без рукопожатия, с server/discover) и прежние 2025-11-25, 2025-06-18, 2025-03-26 (с initialize) — на одном адресе, клиент ничего не настраивает.
• Сервер даёт инструменты (tools) и готовые задания (prompts). Ресурсов и пачек запросов нет.
• Права и данные — те же, что у REST по тому же токену: инструменты вызывают наш же API изнутри сервера, поэтому роли, возможности плана, проверка полей и лимиты работают одинаково.

Протокол по шагам — в справочнике: `POST /mcp`.

Готовые настройки показывает и кабинет: карточка «ИИ-агенты» в Настройки → Интеграции и API и блок «Подключить ИИ-агента» на главной базы знаний (https://vruchay.ru/docs) — команды для каждого клиента, кнопки установки в Cursor и VS Code и промпт для агента.

Два способа войти

Вход через OAuth — основной

Так подключаются все клиенты из списка ниже — без токена:

1. Клиент обращается к /mcp без токена и получает 401 с заголовком WWW-Authenticate: Bearer resource_metadata="https://vruchay.ru/.well-known/oauth-protected-resource/mcp".
2. По этому адресу он находит сервер авторизации, регистрируется сам (Dynamic Client Registration) и открывает в браузере https://vruchay.ru/oauth/authorize.
3. Человек входит в кабинет (если ещё не вошёл) и видит, какое приложение просит доступ, к какой организации и куда вернётся разрешение.
4. Выбирает права — «Выпускать документы» или «Полный доступ» — и нажимает «Разрешить».
5. Клиент получает токен и дальше работает с ним сам.

Разрешить может только владелец или управляющий, и только если доступ по API входит в план (на бесплатной пробе он есть). Подключение появляется в «Токенах API» строкой «Агент «Claude»» (название — то, которым представилось приложение); отключить его — кнопка «Отозвать» там же. Подключение личное: если человека, который его разрешил, убирают из организации или понижают до сотрудника, агент отключается (токены, выданные руками, остаются — они принадлежат организации). Повторное подключение того же приложения тем же человеком заменяет прежний токен, а не добавляет второй; разные приложения на одном компьютере (Claude Code и Codex) друг друга не вытесняют. Подключений через OAuth у организации — не больше десяти, отдельно от десяти обычных токенов.

Адреса этого входа описаны в справочнике: описание сервера авторизации, регистрация клиента; как он устроен и чем ограничен — в Аутентификации.

Клиент представляется автоматической регистрацией (Dynamic Client Registration, DCR): Claude, ChatGPT и остальные делают это сами. Если приложение спрашивает, как ему представиться, выберите DCR («Register automatically»). Вход по адресу описания клиента (Client ID Metadata Document, CIMD) сервер не объявляет: описания Claude и ChatGPT лежат на их сайтах, а те закрыты для российских адресов.

Токен API — для программ без OAuth

Нужен своим скриптам, интеграциям и клиентам, которые не умеют входить через OAuth. Токен выдаёт владелец или управляющий в кабинете: Настройки → Интеграции и API → Токены API → «Выдать токен». Права на выбор:

• «Выпускать документы» (member) — документы, вёрстка, получатели, выпуск, письма;
• «Полный доступ» (admin) — то же плюс формы выдачи, домены почты, удаление, отзыв и перевыпуск документов.

Полный токен показывается один раз. Агент передаёт его в каждом запросе:

Authorization: Bearer vru_ВАШ_ТОКЕН

Cookie кабинета на /mcp не принимаются: вход только заголовком. Подробнее о токенах — в Аутентификации.

Настройка клиентов

Ниже — проверенные настройки на октябрь 2026 года. Интерфейсы приложений меняются; если пункт меню называется иначе, ищите раздел про коннекторы или серверы MCP. У каждого клиента сначала вход через OAuth — токен не нужен. Вариант с токеном — для программ без OAuth: токен кладите в переменную окружения VRUCHAY_TOKEN, а не в файл, который попадёт в репозиторий.

Claude.ai и Claude Desktop

Вход через OAuth, токен не нужен. Коннектор привязан к учётной записи Claude: добавленный на claude.ai, он появляется и в Claude Desktop.

1. Откройте Customize → Connectors (https://claude.ai/customize/connectors).
2. Нажмите Add custom connector (на тарифах Pro и Max — «+ Add» → «Add custom connector»).
3. Название — «Вручай», адрес — https://vruchay.ru/mcp.
4. Authentication — «Sign in now» или «Sign in when needed». OAuth client — «Register automatically». Вариант «Use Claude's published identity» у нас не сработает: описание клиента Claude лежит на claude.ai, а тот закрыт для российских адресов. Если диалог одним экраном, с полями Client ID и Client Secret в «Advanced settings», оставьте их пустыми.
5. Нажмите Add, затем Connect: откроется страница «Вручай» — войдите и разрешите доступ.
6. В чате: кнопка + → Connectors → включите «Вручай».

На бесплатном тарифе Claude можно добавить один свой коннектор. На тарифах Team и Enterprise коннектор добавляет владелец рабочего пространства: Organization settings → Connectors → «Add» → «Custom» → «Web», с тем же адресом; каждый участник потом нажимает Connect у себя в Customize → Connectors и входит в «Вручай» сам.

У некоторых организаций Claude есть раздел Request headers (бета). Через него можно подключиться токеном вместо входа: Authentication — «No sign-in», заголовок authorization, значение Bearer vru_ВАШ_ТОКЕН (со словом Bearer и пробелом). Тогда все участники рабочего пространства Claude работают одним токеном.

Источник: Add a connector that isn't in the directory.

ChatGPT

Вход через OAuth. Свой сервер MCP в ChatGPT подключается в режиме разработчика, и права на это зависят от тарифа:

• Business — режим разработчика включает себе сам владелец или администратор рабочего пространства: Workspace Settings → Permissions & Roles → Connected Data → «Developer mode / Create custom MCP connectors»;
• Enterprise и Edu — Settings → Apps → Advanced settings → Developer mode;
• Plus и Pro — режим разработчика есть, но полная поддержка MCP с изменяющими инструментами объявлена для Business, Enterprise и Edu; проверьте на своей учётной записи.

Без поддержки изменяющих инструментов агент сможет только смотреть: документы, реестр, превью.

Подключение:

1. Откройте Plugins (https://chatgpt.com/plugins), нажмите + → Add custom MCP server. В прежнем интерфейсе — Settings → Apps → «Create app».
2. Название — «Вручай», описание — «Выпуск именных сертификатов и грамот».
3. Connection — Public endpoint, адрес https://vruchay.ru/mcp.
4. Authentication — OAuth. Если ChatGPT предлагает выбрать способ регистрации клиента, выберите динамическую регистрацию (DCR).
5. Подтвердите предупреждение о рисках («I understand and want to continue») и создайте («Create as a plugin»). ChatGPT откроет страницу «Вручай» — войдите и разрешите доступ.
6. В новом чате наберите @ и выберите «Вручай».

Изменяющие инструменты ChatGPT выполняет только после вашего подтверждения. Инструменты, которые только читают, помечены у нас readOnlyHint и подтверждения не просят. Если инструменты на сервере поменялись — Plugins → «Вручай» → Refresh.

Источники: Add custom MCP server, Connect from ChatGPT, Developer mode and MCP apps in ChatGPT.

Claude Code

Одна команда; Claude Code может выполнить её сам, если попросить:

claude mcp add --transport http --scope user vruchay https://vruchay.ru/mcp

Затем войдите: в Claude Code — /mcp → «vruchay» → Authenticate, или в терминале claude mcp login vruchay. Откроется страница «Вручай» — войдите и разрешите доступ. --scope user делает сервер видимым во всех проектах; без него — только в текущем.

Подсказки сервера видны командами: /mcp__vruchay__design_sheet, /mcp__vruchay__issue_from_table и другие.

С токеном — для общего на команду .mcp.json в корне проекта (--scope project): токен не вписывают, а ссылаются на переменную — каждый держит свою:

{
  "mcpServers": {
    "vruchay": {
      "type": "http",
      "url": "https://vruchay.ru/mcp",
      "headers": { "Authorization": "Bearer ${VRUCHAY_TOKEN}" }
    }
  }
}

Если задан свой заголовок Authorization, Claude Code пользуется им и OAuth не запускает.

Проверка: /mcp показывает «vruchay» подключённым, инструменты называются mcp__vruchay__get_account и так далее.

Источник: Connect Claude Code to tools via MCP.

Cursor

Проще всего — кнопкой «Добавить в Cursor» в кабинете (карточка «ИИ-агенты»). Вручную — ~/.cursor/mcp.json (для всех проектов) или .cursor/mcp.json (для одного):

{
  "mcpServers": {
    "vruchay": { "url": "https://vruchay.ru/mcp" }
  }
}

Без заголовков Cursor предложит войти через OAuth: у сервера в настройках MCP появится кнопка входа.

С токеном — "headers": { "Authorization": "Bearer ${env:VRUCHAY_TOKEN}" }. Переменную задайте в профиле оболочки или в системе: envFile у удалённых серверов Cursor не работает, а запущенный из Dock Cursor профиль оболочки не читает.

Источники: Cursor — Model Context Protocol, MCP Install Links.

VS Code и GitHub Copilot

Кнопкой «Добавить в VS Code» в кабинете или одной командой — сервер добавится в профиль пользователя:

code --add-mcp '{"name":"vruchay","type":"http","url":"https://vruchay.ru/mcp"}'

При первом запуске сервера VS Code спросит, доверяете ли вы ему, и предложит войти через OAuth. Инструменты доступны в чате Copilot в режиме агента.

С токеном — .vscode/mcp.json в проекте. Токен VS Code спросит при первом запуске сервера и сохранит в защищённом хранилище — в файл он не попадёт:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "vruchay-token",
      "description": "Токен API «Вручай»",
      "password": true
    }
  ],
  "servers": {
    "vruchay": {
      "type": "http",
      "url": "https://vruchay.ru/mcp",
      "headers": { "Authorization": "Bearer ${input:vruchay-token}" }
    }
  }
}

Для всех проектов — палитра команд → «MCP: Open User Configuration», тот же фрагмент.

Источник: MCP configuration reference.

OpenAI Codex CLI

codex mcp add vruchay --url https://vruchay.ru/mcp
codex mcp login vruchay

Первая команда пишет сервер в ~/.codex/config.toml, вторая открывает вход.

С токеном — в ~/.codex/config.toml только имя переменной окружения, сам токен задайте перед запуском: export VRUCHAY_TOKEN=vru_ВАШ_ТОКЕН.

[mcp_servers.vruchay]
url = "https://vruchay.ru/mcp"
bearer_token_env_var = "VRUCHAY_TOKEN"

Источник: Codex — MCP.

Windsurf (Devin Desktop)

Windsurf со 2 июня 2026 года называется Devin Desktop. Файл настроек MCP — mcp_config.json; где он лежит, зависит от версии (~/.config/devin/mcp_config.json в новых, ~/.codeium/windsurf/mcp_config.json в прежних), поэтому надёжнее открыть его из настроек MCP в самом приложении:

{
  "mcpServers": {
    "vruchay": {
      "serverUrl": "https://vruchay.ru/mcp",
      "headers": { "Authorization": "Bearer ${env:VRUCHAY_TOKEN}" }
    }
  }
}

Источники: Devin Desktop — MCP, Devin Desktop FAQ.

Gemini CLI

gemini mcp add --transport http --scope user vruchay https://vruchay.ru/mcp

Затем в Gemini CLI — /mcp auth vruchay: откроется вход в «Вручай». Без --scope user сервер запишется в настройки текущего проекта.

С токеном — в ~/.gemini/settings.json (или .gemini/settings.json в проекте); для Streamable HTTP ключ — httpUrl, а не url; переменные окружения подставляются в любые строки файла:

{
  "mcpServers": {
    "vruchay": {
      "httpUrl": "https://vruchay.ru/mcp",
      "headers": { "Authorization": "Bearer $VRUCHAY_TOKEN" }
    }
  }
}

Для бесплатных учётных записей и Google One Gemini CLI с 18 июня 2026 года заменён на Antigravity CLI — там настройка своя.

Источники: Gemini CLI — MCP servers, Gemini CLI — configuration.

Любой другой клиент

Подойдёт любой клиент MCP с транспортом Streamable HTTP: адрес https://vruchay.ru/mcp. Клиенты с OAuth находят вход сами по /.well-known/oauth-protected-resource/mcp и /.well-known/oauth-authorization-server; остальным — заголовок Authorization: Bearer vru_ВАШ_ТОКЕН.

Если клиент умеет запускать только локальные серверы (stdio), поможет сторонний мост mcp-remote — он запускается через npx и пересылает вызовы на удалённый сервер:

{
  "mcpServers": {
    "vruchay": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://vruchay.ru/mcp",
        "--header",
        "Authorization:${VRUCHAY_AUTH}"
      ],
      "env": { "VRUCHAY_AUTH": "Bearer vru_ВАШ_ТОКЕН" }
    }
  }
}

Пробелов вокруг двоеточия в --header нет намеренно: часть клиентов (Cursor, Codex, Claude Desktop под Windows) ломает аргументы с пробелами, а в переменной окружения пробел допустим.

Если MCP недоступен вовсе, агент работает с REST API по тому же токену — сценарии в AGENTS.md расписаны для обоих путей.

Проверить подключение

Без клиента, одним запросом — вызов инструмента get_account:

curl -s https://vruchay.ru/mcp \
  -H "Authorization: Bearer $VRUCHAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'

В ответе — организация, условия (left, expired, features) и проекты. Список инструментов со схемами — тот же запрос с "method":"tools/list".

Инструменты

Первым агент вызывает get_account, за инструкцией идёт в get_guide. Чего нет отдельным инструментом — делает через api_request по справочнику.

setup_form, revoke_documents, reissue_documents и delete_document (в корзину) требуют прав «Полный доступ», остальное — и возврат из корзины (restore: true) — доступно и с правами «Выпускать документы».

Клиент видит у каждого инструмента пометки риска (annotations): только читает, может стереть или заменить, безопасен при повторе, выходит наружу (письма, чужие ссылки). По ним Claude и ChatGPT решают, спрашивать ли вас перед вызовом.

Файлы с диска

Бланк, логотип или таблица часто лежат у агента файлом, а не в интернете. Передать их аргументом инструмента нельзя: MCP ходит JSON-ом, а мегабайт base64 модель не напишет. Агенту с оболочкой — Claude Code, Codex, Cursor, VS Code — сервер даёт ссылку на загрузку:

1. get_upload_link с documentId и целью: background (с sheetId) — фон листа, element — картинка для блока, recipients — таблица получателей (mode: append — дописать, replace — заменить; headers — как понимать первую строку).
2. В ответе — готовая команда. Агент подставляет путь и выполняет её:

``bash curl -sS -F "file=@бланк.png" "https://vruchay.ru/api/v1/uploads/u.…" ``

3. curl печатает итог JSON-ом. У картинок — fileId, widthPx, heightPx: фон уже стоит на листе, дальше preview_sheet; картинку блока ставят в props.fileId через edit_layout. У таблицы — сколько строк загружено и как названы колонки, дальше validate_recipients.

Ссылка действует 15 минут и принимает один файл: повтор отвечает 410, за следующим файлом — новая ссылка. Файл не того типа ссылку не тратит. Типы и размеры — те же, что у загрузки в кабинете: PNG или JPEG до 20 МБ, таблица .xlsx или .csv до 10 МБ. Токена в команде нет: права — того токена, который выдал ссылку, и отозванный токен гасит её. В журнал действий загрузка попадает с автором — токеном или подключённым агентом; имени файла и строк таблицы там нет. Без оболочки (Claude.ai, ChatGPT) — upload_image по публичной ссылке или кабинет. Справочник — `POST /api/uploads` и `POST /api/v1/uploads/{link}`.

Готовые задания (подсказки)

Сервер отдаёт клиенту подсказки (prompts) — те же задания, что на странице Готовые тексты для агента: do_task, design_sheet, issue_from_table, site_form, crm_integration, new_event, fix_issued. В Claude Code это команды /mcp__vruchay__design_sheet и другие: выберите, допишите своими словами, что нужно, — и агент получит задание целиком. Подробности о каждом сценарии — в AGENTS.md, о вёрстке — в руководстве по вёрстке.

Как выглядят ответы

• Обычный ответ — один текстовый блок с JSON. Ответы сжаты: у листа — id, место и начало текста каждого блока, а не всё дерево; полный макет — get_document с full: true.
• Превью — картинка JPEG (type: "image") и короткая подпись. Код и номер на превью — образцы.
• Ошибка — ответ с isError: true и текстом по-русски: Ошибка 400: …, следом Поля: [...] с путём и причиной по каждому полю. У edit_recipients — ещё Успело выполниться: {...}, если часть правок прошла. По этому тексту агент исправляет запрос сам.
• Ошибки протокола — JSON-RPC error: неизвестный инструмент (-32602), неверный JSON-RPC (-32600), неизвестный метод (-32601), заголовки не совпали с телом (-32020), незнакомая версия (-32022). Подробно — в справочнике `POST /mcp`.
• Длинный ответ обрезается на 80 000 знаках с припиской «сузьте запрос».
• api_request возвращает только JSON. Файлы (архив, CSV, PDF) через MCP не передаются — для готовых документов есть get_download_link, а файл с диска приносит curl по ссылке из get_upload_link.
• Тело api_request — тоже только JSON. Адреса, которые ждут файл (multipart/form-data: картинка, фон листа, логотип, разбор таблицы из файла), через него не вызвать. Файл с диска — через get_upload_link, картинка из интернета — ссылкой в upload_image, таблица — строками в import_recipients. Страница в справочнике REST ещё не значит, что адрес доступен агенту: закрытые разделы перечислены ниже, а роли и возможности плана действуют как у токена.

Ограничения

Сверх лимита запросов к /mcp — 429 с числом секунд в тексте и в заголовке Retry-After. Внутри инструментов действуют те же пределы, что у REST: см. Ограничения частоты. Сверх них инструмент отвечает ошибкой «Ошибка 429: Слишком много попыток. Повторите через N с.» — секунды только в тексте, заголовка у инструмента нет.

Чего агент не может

• Управлять людьми: приглашать и удалять сотрудников, менять роли и пароли.
• Выдавать и отзывать токены, разрешать подключения OAuth.
• Платить: оплата картой и счета — только человек в кабинете.
• Удалить документ насовсем — только владелец в кабинете.
• Ходить в служебные и публичные адреса: api_request не пускает в /api/auth (кроме /api/auth/me), /api/tokens, /api/oauth, /api/team, /api/team-invite, /api/push, /api/billing/checkout, /api/invoices, /api/platform, /api/leads, /api/render и /api/v1/*.
• Видеть чужие организации: чужой объект отвечает 404.

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

Если не работает

Проверить подключение изнутри клиента проще всего просьбой: «вызови get_account».

Claude.ai и ChatGPT обращаются к серверу из своего облака, а не с вашего компьютера, поэтому офисная сеть на них не влияет. Ответы сервера — обычный JSON, без потоков, так что буферизующие прокси их не ломают.

Коды и формат ошибок — в Кодах ошибок.