> ## Documentation Index > Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Подключение облачной библиотеки для агентов > Передайте страницу ИИ-агенту, чтобы он подключил облачную библиотеку Linkly AI и проверил поиск. Эта страница предназначена прежде всего для **ИИ-агентов**. ```text theme={null} Connect this Linkly AI library: Follow https://linkly.ai/docs/ru/library-setup.md ``` ## Инструкция для ИИ-агента ### Задача Подключи существующую облачную библиотеку к ИИ-клиенту пользователя, не загружая документы на его компьютер. Проведи через вход и Link, настрой OAuth или API Key, а затем докажи работу фактическим поиском. ### Преобразование адреса Веб-адрес вида: ```text theme={null} https://linkly.ai// ``` соответствует идентификатору: ```text theme={null} cloud:/// ``` Не изменяй имя пользователя и slug. Если адрес имеет другую форму, открой страницу и найди показанный идентификатор вместо догадки. В адресе с дополнительным путём (`/settings`) или query-параметрами оставь только `/`. При сомнении после подключения вызови `list_libraries` и возьми точный идентификатор оттуда. Веб-адрес нельзя передавать в `library` напрямую. ### Ограничения * Не создавай аккаунт, имя пользователя, API Key или подписку вместо пользователя * Не публикуй и не меняй видимость библиотеки * Не сохраняй ключ в проекте, истории оболочки или сообщении * Не объявляй успех до реального поиска именно в указанной библиотеке * Не перезаписывай локальный сервер `linkly-ai`: облачный должен быть отдельной записью `linkly-ai-cloud` * Локальный `linkly-ai` никогда не принимает `cloud://`; это граница подключения, а не временная ошибка * В каждом поиске явно передавай `library`. Без него шлюз обращается к Desktop пользователя, а для бесплатного плана сразу возвращает ошибку * Один вызов работает с одной библиотекой; две библиотеки требуют двух поисков * После записи MCP-конфигурации не жди инструменты в текущем сеансе — они появятся после нового разговора или полного перезапуска ### Определи тип клиента * Онлайн-приложение без оболочки: OAuth * Консольный или настольный клиент с пользовательскими заголовками: MCP + API Key * Агент с установленным Linkly AI CLI: удалённый CLI Во встроенном чате Linkly AI Desktop связанную библиотеку можно упомянуть через `@` без настройки MCP; достаточно выполнить Шаг 1. ## Шаг 0. Проверка состояния ```bash theme={null} claude mcp list codex mcp list linkly auth status ``` Не запускай команды, не относящиеся к фактическому клиенту. Проверь, нет ли уже сервера `linkly-ai-cloud`, и не перезаписывай одноимённую конфигурацию без согласия. Также определи, доступны ли текущему сеансу retrieval-инструменты и от какого сервера: облачный представляется как `linkly-ai-cloud`, локальный — `linkly-ai`. Наличие аккаунта и нажатие Link нельзя проверить из оболочки — спроси пользователя. | Состояние | Действие | | ----------------------------------------------- | -------------------------------------------- | | `linkly-ai-cloud` есть и перечисляет библиотеки | Сразу проверить поиск | | Сервер есть, но целевой библиотеки нет | Выполнить только пункт Link в Шаге 1 | | Есть только локальный `linkly-ai` | Выполнить Шаг 1 и сохранить локальную запись | | Linkly-серверов нет | Выполнить Шаг 1 полностью | ## Шаг 1. Аккаунт и Link ### 1. Вход Попроси пользователя войти на [linkly.ai](https://linkly.ai) через Google, GitHub или Notion. Бесплатного аккаунта достаточно. Не проси сообщать пароль. ### 2. Имя пользователя При первом входе пользователь сам выбирает имя. Не подставляй случайное значение. ### 3. Подключение библиотеки Открой точную предоставленную страницу и попроси нажать **Link**. Успех: кнопка стала **Linked**, статус — **Connected**. Даже собственную библиотеку нужно связать отдельно: доступ MCP определяется связью, а не владельцем. Для закрытой библиотеки необходимо приглашение владельца. Бесплатный аккаунт имеет одно место для Link. Если оно занято, пользователь должен отключить другую библиотеку или перейти на Pro с 99 местами. ### 4. Учётные данные Выбери один способ: OAuth для веб-клиента или API Key из [Dashboard → Integrations](https://linkly.ai/dashboard/integrations) для клиента с заголовками. Ключ начинается с `lkai_`, равнозначен учётным данным и предназначен только для инструментов владельца. CLI может сохранить его в собственном защищённом хранилище. Критерий Шага 1: пользователь подтвердил **Linked**; для API key также подтвердил наличие полного значения `lkai_...` без публикации в чате. ## Шаг 2. Облачный MCP Адрес всегда: ```text theme={null} https://mcp.linkly.ai/mcp ``` Имя сервера всегда `linkly-ai-cloud`, а не `linkly-ai`: иначе локальная конфигурация будет незаметно перезаписана, а Skills сочтут облачный сервер локальным. ### Вариант A. API Key Сначала покажи команду и объясни, что ключ будет записан в локальную конфигурацию. Получи согласие пользователя. ```bash theme={null} claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp \ --header "Authorization: Bearer " ``` Универсальная конфигурация: ```json theme={null} { "mcpServers": { "linkly-ai-cloud": { "url": "https://mcp.linkly.ai/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Не записывай реальный ключ в отслеживаемый файл; предпочитай переменную окружения или защищённое хранилище клиента. У разных клиентов поле называется `url`, `httpUrl` или `serverUrl`; сверяйся с [руководством интеграции](/docs/ru/integration). Если поддерживается `${env:LINKLY_API_KEY}`, используй переменную окружения, чтобы не хранить секрет открытым текстом. Проверь ключ прямым рукопожатием: ```bash theme={null} curl -sf --max-time 10 -X POST https://mcp.linkly.ai/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer lkai_YOUR_KEY" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}' ``` Ответ с `"serverInfo":{"name":"linkly-ai-cloud"` подтверждает цепочку. HTTP 401 означает неверный или отозванный ключ — пользователь должен создать новый. ### Вариант B. OAuth В ChatGPT, Claude.ai или другом приложении добавь Connector/MCP-сервер с именем `linkly-ai-cloud` и URL `https://mcp.linkly.ai/mcp`. После сохранения приложение откроет авторизацию linkly.ai; пользователь входит и подтверждает доступ. Полученный токен приложение затем отправляет автоматически, повторная авторизация не нужна. ### Вариант C. CLI ```bash theme={null} linkly auth set-key lkai_YOUR_KEY linkly search "your query" --remote --library "cloud://blueeon/linkly-init-example" ``` Подставляй предоставленный идентификатор дословно. `--remote` — единственный режим CLI, который видит облачные библиотеки; без него поиск остаётся локальным. После новой MCP-конфигурации сначала начни новый разговор. Если инструменты не появились, полностью заверши клиент и открой его снова; закрыть окно на macOS/Windows недостаточно. Не продолжай опрашивать текущий сеанс. ## Шаг 3. Сквозная проверка Если инструменты ещё не появились, честно остановись на «конфигурация записана, рукопожатие успешно, проверка ожидает перезагрузки». Повтори оба способа перезагрузки и передай фразу с **полным** ID библиотеки и конкретной темой для нового сеанса. Когда инструменты доступны, сначала вызови `list_libraries`: целевой `cloud:///` должен присутствовать вместе с числом документов. Затем попроси пользователя назвать безопасную тему или используй нейтральный запрос из описания: ```text theme={null} Найди в cloud://username/library-slug сведения о начале работы и укажи источники. ``` Успех требует реального вызова `search(query="…", library="cloud://username/library-slug")` и результата с документами. Затем прочитай один документ через `outline` или `read`. Полный двухсегментный `library` обязателен **при каждом вызове**. `cloud://library-slug` отклоняется. Без параметра шлюз обращается к Desktop пользователя и бесплатный аккаунт получает ошибку. Если поиск пуст, проверь широту запроса, число документов в `list_libraries`, затем вызови `explore` и сформулируй новый запрос по реальному содержимому. ## Устранение неполадок 401 — ключ неверен или отозван; 403 — ему не хватает разрешения `mcp`. В обоих случаях создай новый ключ и скопируй полностью. Не печатай его в журнал. Проверь точный `cloud://` ID, правильный аккаунт и **Link**. Собственные библиотеки тоже требуют Link. Бесплатный аккаунт имеет одно место: отключи другую библиотеку либо перейди на Pro (99 мест). Параметр `library` пропущен, поэтому запрос ушёл к компьютеру пользователя. Добавь полный ID. Используется локальный `linkly-ai`. Создай отдельный `linkly-ai-cloud`; локальный путь облако не видит. Вероятно, передан веб-URL или один сегмент. Преобразуй в `cloud:///` либо скопируй ID из `list_libraries`. Начни новый разговор; затем полностью заверши и снова открой клиент. Это механизм загрузки. Облачная запись перезаписала имя `linkly-ai`. Переименуй её в `linkly-ai-cloud` и восстанови локальный endpoint. Владелец ещё не отправил контент; агент исправить это не может. ## Итоговый отчёт Укажи точный ID библиотеки, способ авторизации, имя сервера, нужен ли новый разговор/полный перезапуск, число и тематику документов, запрос проверки и подтверждение найденного документа. Напомни: пользователь называет библиотеку, а агент автоматически передаёт `library`. Не включай секреты; незавершённые шаги назови прямо. ### Четыре примера вопросов Сначала вызови `explore` и несколько тематических `search`, затем сформулируй четыре вопроса, явно относящиеся к реальному содержимому библиотеки. Не используй универсальные заготовки вроде «резюмируй базу знаний». ## Дополнительные материалы * [Облачные библиотеки](/docs/ru/use-cloud-library) * [Аккаунт](/docs/ru/linkly-account) * [MCP](/docs/ru/use-mcp)