Подключение облачной библиотеки для агентов

Эта страница предназначена прежде всего для ИИ-агентов.

Connect this Linkly AI library: <library URL>
Follow https://linkly.ai/docs/ru/library-setup.md

Инструкция для ИИ-агента

Задача

Подключи существующую облачную библиотеку к ИИ-клиенту пользователя, не загружая документы на его компьютер. Проведи через вход и Link, настрой OAuth или API Key, а затем докажи работу фактическим поиском.

Преобразование адреса

Веб-адрес вида:

https://linkly.ai/<username>/<library-slug>

соответствует идентификатору:

cloud://<username>/<library-slug>

Не изменяй имя пользователя и slug. Если адрес имеет другую форму, открой страницу и найди показанный идентификатор вместо догадки. В адресе с дополнительным путём (/settings) или query-параметрами оставь только <owner>/<slug>. При сомнении после подключения вызови list_libraries и возьми точный идентификатор оттуда. Веб-адрес нельзя передавать в library напрямую.

Ограничения

Не создавай аккаунт, имя пользователя, API Key или подписку вместо пользователя
На облачном шлюзе библиотеку подключаешь ты сам: library_search для проверки cloud://, затем library_link. Приглашение владельца и выбор библиотеки, которой пожертвовать при исчерпанном лимите, остаются за пользователем; отключить её ты можешь через library_link с action: "unlink", но только названную пользователем, никогда выбранную тобой
Не публикуй и не меняй видимость библиотеки
Не сохраняй ключ в проекте, истории оболочки или сообщении
Не проси у пользователя API Key (начинается с lkai_), не выполняй за него linkly auth set-key и не вписывай ключ в конфигурацию. Ключ читает облачные библиотеки пользователя, а при включённом удалённом доступе — и файлы на его компьютере; всё, что проходит через диалог, отправляется поставщику модели и сохраняется в истории чата. Подключайся через OAuth или linkly auth login — пользователь только подтверждает доступ в браузере. Если пользователь всё же прислал ключ, не используй его и попроси отозвать и создать новый в Dashboard (https://linkly.ai/dashboard/integrations)
Не объявляй успех до реального поиска именно в указанной библиотеке
Не перезаписывай локальный сервер linkly-ai: облачный должен быть отдельной записью linkly-ai-cloud
Локальный linkly-ai никогда не принимает cloud://; это граница подключения, а не временная ошибка
В каждом поиске явно передавай library. Без него шлюз обращается к Desktop пользователя, а для бесплатного плана сразу возвращает ошибку
Один вызов работает с одной библиотекой; две библиотеки требуют двух поисков
После записи MCP-конфигурации не жди инструменты в текущем сеансе — они появятся после нового разговора или полного перезапуска

Определи тип клиента

Онлайн-приложение без оболочки: OAuth
Консольный или настольный клиент (Claude Code, Codex, Cursor, Gemini CLI…): добавить URL и авторизоваться в браузере (Вариант A); API Key — только если клиент не поддерживает OAuth, и настраивает его сам пользователь
Агент с установленным Linkly AI CLI: удалённый CLI, вход через linkly auth login

Во встроенном чате Linkly AI Desktop связанную библиотеку можно упомянуть через @ без настройки MCP; достаточно выполнить Шаг 1, включая нажатие Link в браузере (пункт 3): на этом пути нет инструмента шлюза, который сделает это за пользователя.

Шаг 0. Проверка состояния

claude mcp list
codex mcp list
linkly auth status

Не запускай команды, не относящиеся к фактическому клиенту. Проверь, нет ли уже сервера linkly-ai-cloud, и не перезаписывай одноимённую конфигурацию без согласия. Также определи, доступны ли текущему сеансу retrieval-инструменты и от какого сервера: облачный представляется как linkly-ai-cloud, локальный — linkly-ai. Наличие аккаунта и нажатие Link нельзя проверить из оболочки — спроси пользователя.

Состояние	Действие
`linkly-ai-cloud` есть и перечисляет библиотеки	Сразу проверить поиск
Сервер есть, но целевой библиотеки нет	Подключить самому: Шаг 3
Есть только локальный `linkly-ai`	Выполнить Шаг 1 и сохранить локальную запись
Linkly-серверов нет	Выполнить Шаг 1 полностью

Шаг 1. Аккаунт

1. Вход

Попроси пользователя войти на linkly.ai через Google, GitHub или Notion. Бесплатного аккаунта достаточно. Не проси сообщать пароль.

2. Имя пользователя

При первом входе пользователь сам выбирает имя. Не подставляй случайное значение.

3. (Необязательно) Link в браузере

Не нужно, если ты выйдешь на облачный шлюз: в Шаге 3 библиотеку подключаешь ты через library_link. Путь через браузер по-прежнему работает: попроси открыть точную предоставленную страницу и нажать Link. Успех: кнопка стала Linked, статус — Connected. Даже собственную библиотеку нужно связать отдельно: доступ MCP определяется связью, а не владельцем. При любом пути владелец может подключить свою библиотеку сразу; остальным для Showcase или Private библиотеки нужно принятое приглашение владельца. Бесплатный аккаунт имеет одно место для Link. Если оно занято, пользователь должен отключить другую библиотеку или перейти на Pro с 99 местами.

4. API Key готовить не нужно

При подключении откроется страница авторизации linkly.ai — достаточно один раз подтвердить доступ в браузере, копировать ключ не нужно. Не отправляйте API Key (начинается с lkai_) ИИ-помощнику: содержимое диалога отправляется поставщику модели и сохраняется в истории чата. Ключ нужен, только если ваш ИИ-инструмент не поддерживает такую авторизацию: тогда вы сами создаёте его в Dashboard → Integrations и сами вписываете в файл конфигурации по Шагу 2. Критерий Шага 1: пользователь подтвердил вход и имя. Linked требуется только при пути через браузер.

Шаг 2. Облачный MCP

Адрес всегда:

https://mcp.linkly.ai/mcp

Имя сервера всегда linkly-ai-cloud, а не linkly-ai: иначе локальная конфигурация будет незаметно перезаписана, а Skills сочтут облачный сервер локальным.

Вариант A. URL и авторизация в браузере (клиенты с оболочкой, рекомендуется)

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

claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp

Затем попроси пользователя ввести в Claude Code /mcp, выбрать linkly-ai-cloud и завершить авторизацию. Codex:

codex mcp add linkly-ai-cloud --url https://mcp.linkly.ai/mcp
codex mcp login linkly-ai-cloud

Другие клиенты с HTTP MCP (Cursor, Gemini CLI и т. п.) — только адрес в конфигурации; у разных клиентов поле называется url, httpUrl или serverUrl, сверяйся с руководством интеграции:

{
  "mcpServers": {
    "linkly-ai-cloud": {
      "url": "https://mcp.linkly.ai/mcp"
    }
  }
}

Клиент откроет страницу авторизации linkly.ai; после входа и подтверждения клиент сам сохранит учётные данные. Критерий: конфигурация записана, пользователь подтвердил, что завершил авторизацию в браузере. Реальный поиск проверяется в Шаге 3. Если клиент не поддерживает такую авторизацию (может только отправлять заголовок Authorization: Bearer <key> из конфигурации): это делает сам пользователь, без тебя. Попроси его создать ключ в Dashboard → Integrations и самому вписать его в заголовок в файле конфигурации (формат — в руководстве интеграции; если поддерживается ${env:LINKLY_API_KEY}, лучше переменная окружения). Попроси не присылать тебе ключ или готовый файл конфигурации, и сам этот файл не читай и не выводи.

Вариант B. OAuth

В ChatGPT, Claude.ai или другом приложении добавь Connector/MCP-сервер с именем linkly-ai-cloud и URL https://mcp.linkly.ai/mcp. После сохранения приложение откроет авторизацию linkly.ai; пользователь входит и подтверждает доступ. Полученный токен приложение затем отправляет автоматически, повторная авторизация не нужна.

Вариант C. CLI

Вход в два шага; ключ CLI сохраняет сам, поэтому он не проходит через диалог:

linkly auth login --no-wait --json   # возвращает url и user_code — передай их пользователю для авторизации в браузере
linkly auth login --wait --json      # выполни после авторизации; готово только при "status":"ok"
linkly search "your query" --remote --library "cloud://blueeon/linkly-init-example"

Оба шага выполняй в одном окружении; подробности — R2–R4 в удалённой ветке инструкции для агента. Подставляй предоставленный идентификатор дословно. --remote — единственный режим CLI, который видит облачные библиотеки; без него поиск остаётся локальным. После новой MCP-конфигурации сначала начни новый разговор. Если инструменты не появились, полностью заверши клиент и открой его снова; закрыть окно на macOS/Windows недостаточно. Не продолжай опрашивать текущий сеанс.

Шаг 3. Сквозная проверка

Если инструменты ещё не появились, честно остановись на «конфигурация записана, проверка ожидает перезагрузки». Повтори оба способа перезагрузки и передай фразу с полным ID библиотеки и конкретной темой для нового сеанса. Когда инструменты доступны, сначала вызови list_libraries: целевой cloud://<owner>/<slug> должен присутствовать вместе с числом документов. Если его нет, подключи сам: library_search (при известном имени передай owner) для точного ID, затем library_link, затем снова list_libraries. Ответы invite_required (нужно приглашение владельца), slot_exhausted (в data приходят current, limit, is_pro и guidance — передай эти числа, не угадывая тариф; если пользователь уже назвал библиотеку, которой жертвует («замени A на B»), вызови library_link с action: "unlink" для неё и снова library_link; иначе покажи подключённые из list_libraries и спроси, какую освободить — сам не выбирай; сайт и, на Free, переход на Pro остаются альтернативами) и not_found (проверь ID через owner и адрес у пользователя) передай пользователю как есть, без повторных попыток. Кнопка Link в браузере — только когда шлюз недоступен. Затем попроси пользователя назвать безопасную тему или используй нейтральный запрос из описания:

Найди в cloud://username/library-slug сведения о начале работы и укажи источники.

Успех требует реального вызова search(query="…", library="cloud://username/library-slug") и результата с документами. Затем прочитай один документ через outline или read.

Полный двухсегментный library обязателен при каждом вызове. cloud://library-slug отклоняется. Без параметра шлюз обращается к Desktop пользователя и бесплатный аккаунт получает ошибку.

Если поиск пуст, проверь широту запроса, число документов в list_libraries, затем вызови explore и сформулируй новый запрос по реальному содержимому.

Устранение неполадок

Ответ 401 или 403

401 — авторизация истекла или ключ отозван; 403 — не хватает разрешения mcp. При OAuth попроси пользователя авторизоваться заново; если ключ настроен вручную, пользователь сам создаёт новый в Dashboard и обновляет конфигурацию. Не печатай ключ в журнал.

Library not found

Проверь точный cloud:// ID, правильный аккаунт и Link. Собственные библиотеки тоже требуют Link. На облачном шлюзе агент может подключить библиотеку сам: library_search для проверки ID, затем library_link.

Лимит Link исчерпан

Спроси, какую подключённую библиотеку освободить (list_libraries), вызови для неё library_link с action: "unlink" и подключи заново; сам не выбирай. Бесплатный аккаунт (одно место) может также перейти на Pro (99 мест); сайт подходит для обоих тарифов.

Ошибка Desktop или требование Pro

Параметр library пропущен, поэтому запрос ушёл к компьютеру пользователя. Добавь полный ID.

cloud:// не поддерживается

Используется локальный linkly-ai. Создай отдельный linkly-ai-cloud; локальный путь облако не видит.

Требуется owner/slug

Вероятно, передан веб-URL или один сегмент. Преобразуй в cloud://<owner>/<slug> либо скопируй ID из list_libraries.

Инструменты не появились

Начни новый разговор; затем полностью заверши и снова открой клиент. Это механизм загрузки.

Локальный поиск внезапно пуст

Облачная запись перезаписала имя linkly-ai. Переименуй её в linkly-ai-cloud и восстанови локальный endpoint.

Библиотека содержит 0 документов

Владелец ещё не отправил контент; агент исправить это не может.

Итоговый отчёт

Укажи точный ID библиотеки, способ авторизации, имя сервера, нужен ли новый разговор/полный перезапуск, число и тематику документов, запрос проверки и подтверждение найденного документа. Напомни: пользователь называет библиотеку, а агент автоматически передаёт library. Не включай секреты; незавершённые шаги назови прямо.

Четыре примера вопросов

Сначала вызови explore и несколько тематических search, затем сформулируй четыре вопроса, явно относящиеся к реальному содержимому библиотеки. Не используй универсальные заготовки вроде «резюмируй базу знаний».

Начало работы

Основные функции

Подключение ИИ-инструментов

Для ИИ-агентов

Подключение облачной библиотеки для агентов

Инструкция для ИИ-агента

Задача

Преобразование адреса

Ограничения

Определи тип клиента

Шаг 0. Проверка состояния

Шаг 1. Аккаунт

1. Вход

2. Имя пользователя

3. (Необязательно) Link в браузере

4. API Key готовить не нужно

Шаг 2. Облачный MCP

Вариант A. URL и авторизация в браузере (клиенты с оболочкой, рекомендуется)

Вариант B. OAuth

Вариант C. CLI

Шаг 3. Сквозная проверка

Устранение неполадок

Итоговый отчёт

Четыре примера вопросов

Дополнительные материалы

​Инструкция для ИИ-агента

​Задача

​Преобразование адреса

​Ограничения

​Определи тип клиента

​Шаг 0. Проверка состояния

​Шаг 1. Аккаунт

​1. Вход

​2. Имя пользователя

​3. (Необязательно) Link в браузере

​4. API Key готовить не нужно

​Шаг 2. Облачный MCP

​Вариант A. URL и авторизация в браузере (клиенты с оболочкой, рекомендуется)

​Вариант B. OAuth

​Вариант C. CLI

​Шаг 3. Сквозная проверка

​Устранение неполадок

​Итоговый отчёт

​Четыре примера вопросов

​Дополнительные материалы

Инструкция для ИИ-агента

Задача

Преобразование адреса

Ограничения

Определи тип клиента

Шаг 0. Проверка состояния

Шаг 1. Аккаунт

1. Вход

2. Имя пользователя

3. (Необязательно) Link в браузере

4. API Key готовить не нужно

Шаг 2. Облачный MCP

Вариант A. URL и авторизация в браузере (клиенты с оболочкой, рекомендуется)

Вариант B. OAuth

Вариант C. CLI

Шаг 3. Сквозная проверка

Устранение неполадок

Итоговый отчёт

Четыре примера вопросов

Дополнительные материалы