> ## 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.
# Guide de connexion aux bibliothèques cloud pour les Agents
> Transmettez cette page à votre agent IA et laissez-le vous connecter à une bibliothèque cloud Linkly AI pour commencer à l'interroger immédiatement
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](/docs/fr/agent-setup).
***
## À 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 :
1. le client dans lequel tu t'exécutes est raccordé à la passerelle cloud de Linkly AI (`mcp.linkly.ai`) ;
2. tu retrouves réellement du contenu de cette bibliothèque avec `library="cloud:///"` ;
3. 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 `/` 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 `/`. 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 :**
```bash theme={null}
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](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//` : 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](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 :**
```bash theme={null}
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) :
```json theme={null}
{
"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](/docs/fr/integration). 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 :
```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_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** :
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`.
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](/docs/fr/integration/use-in-chatgpt) et [Utiliser Linkly AI dans Claude](/docs/fr/integration/use-in-claude).
### Option C : CLI (facultatif)
Si l'utilisateur a installé le Linkly AI CLI, la ligne de commande est également possible :
```bash theme={null}
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:///` 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:///` 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](/docs/fr/use-cloud-library) — l'explication complète destinée aux lecteurs humains : création, envoi, partage, quotas
* [Guide d'installation pour les Agents](/docs/fr/agent-setup) — la page à suivre pour indexer les fichiers de son propre ordinateur
* [Présentation des outils](/docs/fr/tools-intro) — la description complète des paramètres des sept outils de recherche
* [Utiliser les Skills](/docs/fr/use-skills) — pour que l'assistant IA sache mieux combiner ces outils