Guide de connexion aux bibliothèques cloud pour les Agents

Cette page s’adresse en priorité aux agents IA, et non aux humains. Sur la page de n’importe quelle bibliothèque cloud, cliquez sur Utiliser dans l’IA et transmettez à votre assistant IA la phrase affichée dans la fenêtre. Vous pouvez aussi lancer la procédure à la main — remplacez simplement l’adresse de bibliothèque ci-dessous par celle qui vous intéresse :

Veuillez lire https://linkly.ai/docs/fr/library-setup.md et me guider pour connecter cette bibliothèque : https://linkly.ai/blueeon/linkly-init-example

Vous êtes bien sûr libre de poursuivre la lecture vous-même — il s’agit aussi d’une procédure de connexion complète, simplement rédigée plus directement, avec une insistance particulière sur la manière de vérifier que chaque étape a réellement fonctionné. Si votre assistant IA n’a pas accès au web, utilisez Copy page dans le coin supérieur droit pour récupérer cette page en Markdown brut et collez-la-lui directement.

Cette voie ne nécessite pas d’installer l’application de bureau Linkly AI. Les bibliothèques cloud sont hébergées côté serveur, disponibles 24h/24, et n’importe quel outil IA compatible MCP peut les interroger directement. Si ce que vous voulez indexer, ce sont les fichiers de votre propre ordinateur, c’est un autre sujet : voir le Guide d’installation pour les Agents.

À l’attention de l’agent IA

Tout ce qui suit s’adresse à toi. Lis l’intégralité avant de commencer.

Ta mission

Permettre à l’utilisateur d’interroger une bibliothèque cloud donnée. Ta mission est accomplie lorsque :

le client dans lequel tu t’exécutes est raccordé à la passerelle cloud de Linkly AI (mcp.linkly.ai) ;
tu retrouves réellement du contenu de cette bibliothèque avec library="cloud://<owner>/<slug>" ;
tu as accompagné l’utilisateur sur sa première vraie question et fourni une réponse fondée sur de vrais documents.

Première chose à faire : convertir l’adresse web en identifiant de bibliothèque

Ce que l’utilisateur te transmet, c’est l’adresse web de la bibliothèque, de la forme :

https://linkly.ai/blueeon/linkly-init-example

Or le paramètre library des outils de recherche attend un identifiant de bibliothèque. Ce sont deux écritures d’une même chose : remplace le préfixe de domaine https://linkly.ai/ par cloud:// et conserve tel quel le couple <owner>/<slug> qui suit.

Ce que l’utilisateur te donne (adresse web)	Ce que tu passes à l’outil (identifiant)
`https://linkly.ai/blueeon/linkly-init-example`	`cloud://blueeon/linkly-init-example`
`linkly.ai/7running/basedge`	`cloud://7running/basedge`

Ne passe jamais l’adresse web telle quelle au paramètre library : elle sera rejetée. Tous les exemples en cloud://… de la suite de cette page sont déjà convertis. Si l’adresse fournie comporte d’autres segments de chemin (par ex. /settings) ou des paramètres de requête, ne retiens que les deux segments <owner>/<slug>. En cas de doute, appelle list_libraries une fois la connexion MCP établie : la réponse contient l’identifiant exact.

Tes limites et règles

Certaines choses, tu peux les faire toi-même ; d’autres doivent être confiées à l’utilisateur. N’outrepasse pas tes limites et ne présume jamais d’un résultat à la place de l’utilisateur :

Ce que tu peux faire toi-même : sonder l’état de la connexion, écrire la configuration MCP, envoyer une requête de poignée de main, appeler les outils de recherche, interpréter les erreurs, rendre compte. Pour toute commande qui écrit de la configuration, montre-la d’abord à l’utilisateur et obtiens son accord avant de l’exécuter.
Ce que l’utilisateur doit faire : créer un compte ou se connecter sur linkly.ai, définir un nom d’utilisateur, cliquer sur Lier sur la page de la bibliothèque, générer une clé API dans le tableau de bord, accorder l’autorisation OAuth dans le navigateur. Ce sont des actions dans le navigateur — tu ne peux pas les réaliser.

Et quelques règles strictes, chacune correspondant à un scénario d’échec bien réel :

N’écrase pas la configuration MCP locale existante de l’utilisateur. Chez ceux qui ont installé l’application de bureau, le client contient déjà un serveur nommé linkly-ai pointant vers http://127.0.0.1:60606/mcp. Le cloud est une entrée supplémentaire, et son nom doit impérativement être linkly-ai-cloud. Écrire sous le même nom remplace silencieusement l’entrée locale : l’utilisateur ne retrouvera soudain plus les documents de son ordinateur, et sans le moindre message d’erreur.
La connexion locale n’atteint pas les bibliothèques cloud. Sur la voie linkly-ai (locale / réseau local), toute référence cloud:// sera rejetée à chaque fois. Ne retente pas une bibliothèque cloud sur la connexion locale : c’est une frontière de la chaîne, pas une défaillance passagère.
Passe explicitement library à chaque recherche. Lorsque le paramètre library est omis, la passerelle route par défaut vers la machine de l’utilisateur (via le tunnel de bureau), et le tunnel est une fonctionnalité Pro — les comptes gratuits reçoivent directement une erreur. Les bibliothèques cloud ne sont jamais incluses implicitement.
Une bibliothèque par appel. Les bibliothèques cloud ne sont pas fusionnées automatiquement au sein d’une même recherche : pour en interroger deux, fais deux appels.
Sonde d’abord, agis ensuite. L’utilisateur a peut-être déjà réalisé une partie de la configuration — ne déroule pas aveuglément toutes les étapes depuis le début.
Lorsque l’utilisateur doit intervenir, dis-lui tout d’un coup, puis arrête-toi et attends une réponse unique. Ne découpe pas une même tâche en plusieurs allers-retours de confirmation.
N’exagère jamais l’avancement. Ce qui n’est pas vérifié n’est pas fait. Indique exactement où tu es bloqué et ce que tu as essayé.

Détermine d’abord à quelle catégorie de client tu appartiens

La voie à suivre dépend de ta capacité à écrire de la configuration et à exécuter des commandes :

Tu es	Voie à suivre
Doté d’une ligne de commande / capable de modifier des fichiers de configuration (Claude Code, Codex, Cursor, Gemini CLI…)	Voie de la clé API (Étape 2, option A)
Application en ligne sans ligne de commande (ChatGPT, Claude.ai…)	Voie OAuth (Étape 2, option B) : un seul URL à renseigner
Le Chat intégré à l’application de bureau Linkly AI	Rien à configurer, voir le raccourci ci-dessous

Raccourci : si l’utilisateur a déjà installé l’application de bureau Linkly AI, il peut mentionner directement une bibliothèque cloud connectée avec @ dans le Chat de l’application, sans configurer le moindre MCP. Cette voie ne demande que l’Étape 1.

Étape 0 : Sonder l’état actuel

Détermine d’abord jusqu’où la chaîne est déjà en place, puis décide par où commencer. Trois choses à établir. 1. Disposes-tu d’outils de recherche Linkly dans la session en cours ? De quel serveur proviennent-ils ? La passerelle cloud s’annonce sous le nom linkly-ai-cloud, l’application de bureau locale sous linkly-ai. La plupart des clients font apparaître le nom du serveur dans le nom des outils (par ex. mcp__linkly-ai-cloud__search). 2. Si tu disposes d’une ligne de commande, liste directement les serveurs configurés :

claude mcp list        # Claude Code
codex mcp list         # Codex

Regarde l’URL de chaque entrée : celles qui commencent par 127.0.0.1 sont locales, mcp.linkly.ai est le cloud. 3. L’utilisateur possède-t-il un compte linkly.ai, et a-t-il déjà lié cette bibliothèque ? Cela, tu ne peux pas le vérifier : pose directement la question à l’utilisateur.

Tableau des états

Parcours de haut en bas et applique la première ligne qui correspond :

Résultat du sondage	Signification	Commencer à
`linkly-ai-cloud` présent et capable de lister les bibliothèques	La chaîne cloud est en place	Directement la vérification de l’Étape 3
`linkly-ai-cloud` présent, mais la bibliothèque cible n’apparaît pas	La chaîne fonctionne, la bibliothèque n’est pas encore liée	Étape 1 (uniquement le point « lier la bibliothèque »)
Seul `linkly-ai` (local) est présent	L’application de bureau est installée, mais pas le cloud	Étape 1. Attention à conserver l’entrée locale, ne l’écrase pas
Aucun serveur Linkly	Nouvel utilisateur	Étape 1

Étape 1 : Demander à l’utilisateur de préparer son compte et de lier la bibliothèque

Cette étape se déroule entièrement dans le navigateur — tu ne peux pas la réaliser. Donne à l’utilisateur l’intégralité de ce qui suit en un seul message, puis arrête-toi et attends une réponse unique ; ne la découpe pas en plusieurs tours de confirmation. Voici ce qu’il faut transmettre à l’utilisateur (reformule-le à ta manière si tu veux, mais couvre les quatre parties) :

1. Créer un compte et se connecter

Rendez-vous sur https://linkly.ai pour créer un compte ou vous connecter, avec Google, GitHub ou Notion. Un compte gratuit suffit pour toute la procédure.

2. Définir un nom d’utilisateur (uniquement à la première connexion)

L’adresse d’une bibliothèque cloud est de la forme linkly.ai/<username>/<slug> : le compte a donc besoin d’un nom d’utilisateur unique. Définissez-le une fois dans le Dashboard en suivant l’invite, et vous n’aurez plus à y revenir.

3. Ouvrir la page de la bibliothèque et cliquer sur Lier

Rendez-vous sur l’adresse web de la bibliothèque (par exemple https://linkly.ai/blueeon/linkly-init-example) et cliquez sur le bouton Lier en haut à droite de la page (en anglais : Link). C’est réussi lorsque le bouton devient Liée et que le badge d’état affiche Connectée.

Même une bibliothèque que vous avez créée vous-même doit être liée une fois. La portée interrogeable via MCP est déterminée par la liaison, et non par la propriété : une bibliothèque non liée, même la vôtre, n’apparaît pas dans list_libraries.

Un compte gratuit dispose d’un seul emplacement de connexion (slot). Si une autre bibliothèque est déjà liée, il faut d’abord la délier ou passer à Pro (99 emplacements). La fenêtre de quota affichée sur la page de la bibliothèque contient le lien de mise à niveau.

4. Récupérer les identifiants (au choix)

Votre assistant IA dispose d’une ligne de commande ou peut modifier des fichiers de configuration : rendez-vous sur https://linkly.ai/dashboard/integrations, créez une clé dans la section Clés API et copiez la valeur générée (elle commence par lkai_). Cette clé équivaut aux identifiants de votre compte : réservez-la à vos propres outils IA, ne la partagez pas.
Vous utilisez une application en ligne comme ChatGPT ou Claude.ai : aucune clé API n’est nécessaire, passez ce point — l’autorisation se fera plus tard dans le navigateur.

Critère d’acceptation : l’utilisateur confirme que le bouton de la page de la bibliothèque affiche désormais Liée. S’il emprunte la voie de la clé API, confirme en même temps qu’il dispose bien d’une clé commençant par lkai_.

Étape 2 : Se raccorder au MCP cloud

Le point de terminaison est fixe :

https://mcp.linkly.ai/mcp

Le serveur doit systématiquement s’appeler linkly-ai-cloud, jamais linkly-ai : ce dernier est le nom de l’application de bureau locale, un nom identique écraserait la configuration locale de l’utilisateur, et un agent équipé des Linkly Skills prendrait cette connexion pour une connexion locale, avant de rejeter toutes les requêtes cloud://.

Option A : Clé API (clients disposant d’une ligne de commande, recommandé)

Montre d’abord la commande à l’utilisateur, explique-lui qu’elle inscrit la clé dans un fichier de configuration local, et n’exécute qu’après avoir obtenu son accord. Claude Code :

claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp \
  --header "Authorization: Bearer lkai_votre_cle"

Pour les autres clients compatibles HTTP MCP, ajoutez une section dans leur fichier de configuration respectif (mcp.json pour Cursor, ~/.gemini/settings.json pour Gemini CLI ; les noms de champs font foi dans la documentation de chaque éditeur) :

{
  "mcpServers": {
    "linkly-ai-cloud": {
      "url": "https://mcp.linkly.ai/mcp",
      "headers": {
        "Authorization": "Bearer lkai_votre_cle"
      }
    }
  }
}

Les différences de champs d’un client à l’autre (url / httpUrl / serverUrl) sont détaillées dans le Guide d’intégration. Certains clients acceptent la syntaxe ${env:LINKLY_API_KEY} pour lire la valeur depuis une variable d’environnement, ce qui évite d’écrire la clé en clair dans le fichier de configuration. Critère d’acceptation : envoie directement une poignée de main pour confirmer que le serveur répond correctement :

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_votre_cle" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'

Une réponse contenant "serverInfo":{"name":"linkly-ai-cloud" signifie que les identifiants sont valides et la chaîne saine. Un 401 signifie que la clé est erronée ou révoquée — demande à l’utilisateur d’en régénérer une depuis le tableau de bord.

Option B : OAuth (ChatGPT, Claude.ai et autres applications en ligne)

Ces applications ne permettent pas de renseigner des en-têtes personnalisés ; elles passent par une autorisation OAuth, ce qui est même plus simple — il n’y a qu’un URL à renseigner :

Ajouter un connecteur MCP

Dans les réglages de connecteurs / MCP de l’application, ajoutez un serveur nommé linkly-ai-cloud avec l’URL https://mcp.linkly.ai/mcp.

Compléter l'autorisation dans le navigateur

Après enregistrement, l’application redirige automatiquement vers la page d’autorisation de linkly.ai. Une fois l’utilisateur connecté et l’autorisation confirmée, l’application obtient un jeton d’accès, joint automatiquement aux requêtes suivantes — aucune nouvelle autorisation ne sera nécessaire.

L’emplacement exact du point d’entrée dans chaque application est décrit dans Utiliser Linkly AI dans ChatGPT et Utiliser Linkly AI dans Claude.

Option C : CLI (facultatif)

Si l’utilisateur a installé le Linkly AI CLI, la ligne de commande est également possible :

linkly auth set-key lkai_votre_cle
linkly search "mot-clé" --remote --library "cloud://blueeon/linkly-init-example"

--remote est le seul mode du CLI capable d’atteindre les bibliothèques cloud ; sans lui, seule la machine locale est interrogée.

Une fois le MCP configuré, les nouveaux outils ne sont généralement pas actifs immédiatement dans la session en cours — la plupart des clients doivent recharger leur configuration ou démarrer une nouvelle session. Dis-le clairement à l’utilisateur : « la configuration est enregistrée, recharge puis réessaie ». Ne continue pas à sonder la session en cours pour voir si les outils sont apparus.

Étape 3 : Vérification de bout en bout

Une fois les outils disponibles (l’utilisateur devra peut-être redémarrer sa session), fais deux choses pour confirmer que toute la chaîne fonctionne vraiment. 1. Vérifie que la bibliothèque figure dans la liste : Appelle list_libraries : la bibliothèque cible doit apparaître dans la liste renvoyée, sous une forme comme :

- **cloud://blueeon/linkly-init-example** (305 docs) [yours]: Documents d'initialisation fournis avec Linkly AI

Si elle n’y est pas, c’est que la liaison n’a pas abouti — reviens au point 3 de l’Étape 1. 2. Effectue une vraie recherche :

search(query="…", library="cloud://blueeon/linkly-init-example")

Le succès signifie : de véritables entrées de documents ont été renvoyées.

Le paramètre library doit être présent à chaque appel, et il doit s’agir du cloud://<owner>/<slug> complet, en deux segments — n’en écrire qu’un seul (par ex. cloud://linkly-init-example) provoque un rejet. Lorsque library est omis, la passerelle interroge par défaut la machine de l’utilisateur, ce qui renvoie directement une erreur pour un compte gratuit.

Si la première recherche revient vide, ne l’impute pas immédiatement à une erreur de configuration. Vérifie dans l’ordre : la requête est-elle trop étroite → le nombre de documents de cette bibliothèque dans list_libraries vaut-il 0 (le propriétaire n’a encore rien envoyé) → passe par explore pour voir ce que contient la bibliothèque dans son ensemble, puis affine la recherche.

Dépannage

Symptôme	Cause et solution
La poignée de main renvoie 401	Clé invalide ou révoquée. Fais-en régénérer une depuis le tableau de bord, en veillant à la copier intégralement (elle commence par `lkai_`).
La poignée de main renvoie 403	Les identifiants n’ont pas la permission `mcp`. Il suffit de générer une nouvelle clé API.
La bibliothèque cible n’apparaît pas dans `list_libraries`	La bibliothèque n’est pas encore liée. Fais cliquer l’utilisateur sur Lier depuis la page de la bibliothèque ; cela vaut aussi pour ses propres bibliothèques.
Le clic sur Lier signale un quota atteint	Un compte gratuit ne dispose que d’un emplacement de connexion. Il faut délier une autre bibliothèque, ou passer à Pro (99 emplacements).
L’erreur évoque un Desktop injoignable / une exigence Pro	Tu as oublié le paramètre `library` : la requête a été routée par défaut vers la machine de l’utilisateur. Ajoute `library="cloud://owner/slug"` et réessaie.
`cloud://` est rejeté comme non pris en charge	Tu es raccordé au serveur local (`linkly-ai`), pas à la passerelle cloud. Les bibliothèques cloud sont inaccessibles par cette voie : il faut ajouter une connexion `linkly-ai-cloud`.
Message `library must be in 'owner/slug' format`	Le plus souvent, l’adresse web a été passée telle quelle à `library`. Applique la règle de conversion du début et écris `cloud://<owner>/<slug>` en deux segments ; un seul segment est également rejeté. En cas de doute, prends la valeur exacte dans `list_libraries`.
Tout est configuré mais les outils n’apparaissent pas	Il faut recharger la configuration ou démarrer une nouvelle session. C’est le mécanisme de chargement du client, pas une erreur de configuration.
La recherche locale de l’utilisateur ne trouve soudain plus rien	La configuration cloud a été écrite sous le nom `linkly-ai` et a écrasé l’entrée locale. Bascule sur `linkly-ai-cloud` et rajoute l’entrée pointant vers la machine locale.
La bibliothèque affiche 0 document	Le propriétaire n’a pas encore envoyé son contenu vers le cloud. Ce n’est pas de ton ressort : dis-le honnêtement à l’utilisateur.

Rends compte une fois terminé

Termine par un court paragraphe à l’intention de l’utilisateur, couvrant :

la voie empruntée pour le raccordement (clé API ou OAuth) et le nom du serveur ;
si un redémarrage de session est nécessaire pour que cela prenne effet ;
combien de documents contient cette bibliothèque et ce qu’on y trouve en substance ;
comment l’utiliser ensuite — rappelle-lui qu’il lui suffit de nommer clairement la bibliothèque chaque fois qu’il veut l’interroger, et que tu ajouteras automatiquement le paramètre library.

Si une étape n’a pas pu être menée à bien, dis clairement où tu es resté bloqué, ce que tu as essayé, et ce que l’utilisateur peut faire lui-même ensuite.

Termine par quatre exemples de questions

À la fin de ton rapport, donne à l’utilisateur quatre questions qu’il peut copier et essayer immédiatement. Elles doivent impérativement être bâties sur le contenu réel de cette bibliothèque : Commence par un explore pour saisir la composition d’ensemble de la bibliothèque, complète au besoin par quelques search sur des thèmes précis, puis rédige quatre questions qui pointent vraiment vers son contenu. Évite les banalités du type « résume cette base de connaissances » — une bonne question doit faire dire à l’utilisateur au premier coup d’œil : « ça parle clairement de ce que contient cette bibliothèque ».

Pour aller plus loin

Utiliser les bibliothèques cloud — l’explication complète destinée aux lecteurs humains : création, envoi, partage, quotas
Guide d’installation pour les Agents — la page à suivre pour indexer les fichiers de son propre ordinateur
Présentation des outils — la description complète des paramètres des sept outils de recherche
Utiliser les Skills — pour que l’assistant IA sache mieux combiner ces outils

Démarrage rapide

Fonctionnalités principales

Connecter vos outils IA

Pour les Agents IA

Guide de connexion aux bibliothèques cloud pour les Agents

À l’attention de l’agent IA

Ta mission

Première chose à faire : convertir l’adresse web en identifiant de bibliothèque

Tes limites et règles

Détermine d’abord à quelle catégorie de client tu appartiens

Étape 0 : Sonder l’état actuel

Tableau des états

Étape 1 : Demander à l’utilisateur de préparer son compte et de lier la bibliothèque

1. Créer un compte et se connecter

2. Définir un nom d’utilisateur (uniquement à la première connexion)

3. Ouvrir la page de la bibliothèque et cliquer sur Lier

4. Récupérer les identifiants (au choix)

Étape 2 : Se raccorder au MCP cloud

Option A : Clé API (clients disposant d’une ligne de commande, recommandé)

Option B : OAuth (ChatGPT, Claude.ai et autres applications en ligne)

Option C : CLI (facultatif)

Étape 3 : Vérification de bout en bout

Dépannage

Rends compte une fois terminé

Termine par quatre exemples de questions

Pour aller plus loin

​À l’attention de l’agent IA

​Ta mission

​Première chose à faire : convertir l’adresse web en identifiant de bibliothèque

​Tes limites et règles

​Détermine d’abord à quelle catégorie de client tu appartiens

​Étape 0 : Sonder l’état actuel

​Tableau des états

​Étape 1 : Demander à l’utilisateur de préparer son compte et de lier la bibliothèque

​1. Créer un compte et se connecter

​2. Définir un nom d’utilisateur (uniquement à la première connexion)

​3. Ouvrir la page de la bibliothèque et cliquer sur Lier

​4. Récupérer les identifiants (au choix)

​Étape 2 : Se raccorder au MCP cloud

​Option A : Clé API (clients disposant d’une ligne de commande, recommandé)

​Option B : OAuth (ChatGPT, Claude.ai et autres applications en ligne)

​Option C : CLI (facultatif)

​Étape 3 : Vérification de bout en bout

​Dépannage

​Rends compte une fois terminé

​Termine par quatre exemples de questions

​Pour aller plus loin

À l’attention de l’agent IA

Ta mission

Première chose à faire : convertir l’adresse web en identifiant de bibliothèque

Tes limites et règles

Détermine d’abord à quelle catégorie de client tu appartiens

Étape 0 : Sonder l’état actuel

Tableau des états

Étape 1 : Demander à l’utilisateur de préparer son compte et de lier la bibliothèque

1. Créer un compte et se connecter

2. Définir un nom d’utilisateur (uniquement à la première connexion)

3. Ouvrir la page de la bibliothèque et cliquer sur Lier

4. Récupérer les identifiants (au choix)

Étape 2 : Se raccorder au MCP cloud

Option A : Clé API (clients disposant d’une ligne de commande, recommandé)

Option B : OAuth (ChatGPT, Claude.ai et autres applications en ligne)

Option C : CLI (facultatif)

Étape 3 : Vérification de bout en bout

Dépannage

Rends compte une fois terminé

Termine par quatre exemples de questions

Pour aller plus loin