# Se connecter via MCP

Connectez Claude Desktop, Claude Code, Cursor, Codex ou un autre client MCP aux outils de projet locaux d'Oleafly.

Oleafly peut jouer le rôle de serveur MCP (Model Context Protocol). Des clients MCP tels que Claude Desktop, Claude Code, Cursor, Codex et Grok CLI peuvent lire, modifier, rechercher et compiler un projet Oleafly. Vous n'avez pas besoin de clé de fournisseur d'IA dans Oleafly : c'est le client qui fournit le modèle.

C'est l'option à retenir quand vous avez déjà un abonnement Claude (ou équivalent) et que vous voulez piloter Oleafly depuis cette application de discussion, sans coller de clé d'API dans [Paramètres](/docs/ai-setup/).

## Activer le serveur

1. Ouvrez **Paramètres → Intégrations → Oleafly MCP**.
2. Activez **Activer le serveur MCP**.

Le serveur ne tourne que pendant que le processus Oleafly est ouvert. Il écoute uniquement sur `127.0.0.1`, jamais sur votre réseau local. Fermer la fenêtre du projet n'arrête pas le serveur ; désactiver MCP ou quitter Oleafly, si.

Oleafly privilégie le port `5323` (`http://127.0.0.1:5323/mcp`). S'il est indisponible, le serveur se lie automatiquement à un autre port local libre et le conserve pour le prochain lancement. Paramètres affiche l'URL active ; son bouton de redémarrage réutilise le port actuel quand c'est possible, ou en choisit un autre de libre.

## Connecter votre client

:::tip[Pas de jeton à copier]
La commande `oleafly` a son propre serveur MCP, qui communique par l'entrée et la sortie standard. Il trouve tout seul l'application en cours d'exécution et son jeton : vous ne copiez ni URL ni jeton, et vous n'avez pas besoin de Node.js. `oleafly mcp config --client claude-desktop` affiche la configuration ; les noms de clients sont `claude-code`, `claude-desktop`, `codex`, `cursor` et `gemini`. Voir [Outil en ligne de commande](/docs/cli/#connect-an-agent-over-mcp).
:::

Paramètres affiche des extraits prêts à copier-coller pour les clients courants. Copiez l'URL active, car le port retenu peut différer de `5323`, puis remplacez `<token>` par le jeton bearer provenant de Paramètres (Révéler / Copier).

### Claude Code

```bash
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"
```

### Claude Desktop

Ajoutez ceci à `claude_desktop_config.json` (pont stdio via `mcp-remote`, car Desktop privilégie stdio) :

```json
{
  "mcpServers": {
    "oleafly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://127.0.0.1:5323/mcp",
        "--header",
        "Authorization: Bearer <token>",
        "--transport",
        "http-only"
      ]
    }
  }
}
```

### Extension Claude Desktop

Chaque version inclut `oleafly.mcpb`, une extension Claude Desktop : vous n'avez besoin ni du fichier de configuration ni du token. Téléchargez-la depuis la [dernière version](https://github.com/Oleafly/Oleafly/releases/latest) et ouvrez-la avec Claude Desktop pour l'installer.

L'extension lance la commande `oleafly` fournie avec l'application et travaille sur le projet ouvert dans Oleafly : gardez donc Oleafly ouvert avec son serveur MCP activé. Si Claude Desktop ne trouve pas la commande, choisissez-la dans les paramètres de l'extension : `oleafly-cli` dans `Oleafly.app/Contents/MacOS` sur macOS, ou `oleafly-cli.exe` dans `%LOCALAPPDATA%\Oleafly` sur Windows.

Le MCP Registry référence la même extension sous `io.github.Oleafly/oleafly`.

### Cursor / VS Code

Dans `.cursor/mcp.json` (ou la configuration MCP de votre client) :

```json
{
  "mcpServers": {
    "oleafly": {
      "url": "http://127.0.0.1:5323/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

### Grok CLI

Dans `~/.grok/config.toml` :

```toml
[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }
```

### Codex CLI

Utilisez l'extrait **Codex CLI** des paramètres d'Oleafly, qui fournit un pont stdio vers le serveur en cours d'exécution. Ajoutez l'entrée à votre configuration Codex et utilisez l'URL active et le jeton affichés par Oleafly :

```toml title="~/.codex/config.toml"
[mcp_servers.oleafly]
command = "npx"
args = [
  "-y",
  "mcp-remote@latest",
  "http://127.0.0.1:5323/mcp",
  "--header",
  "Authorization: Bearer <token>",
  "--transport",
  "http-only"
]
```

Le pont nécessite Node.js et `npx`. Redémarrez ou reconnectez le client après avoir modifié sa configuration.

Le fichier `mcp.json` placé à côté de vos données Oleafly (indiqué dans Paramètres) contient la même URL et le même jeton si vous préférez scripter la mise en place. Il n'est écrit que pendant que le serveur tourne (mode `0600` sous Unix) et il est supprimé quand le serveur s'arrête. Traitez-le comme n'importe quel autre secret local.

## Ce que les outils peuvent faire

La plupart des outils MCP portent les mêmes noms et les mêmes schémas que ceux de l'assistant intégré. Les outils de découverte et de routage des projets sont fournis par le backend de l'application.

Les outils ciblent le projet ouvert dans l'application lorsqu'il y en a un. Avec une fenêtre connectée, utilisez `list_projects` et `open_project` pour sélectionner un autre projet.

Après la fermeture de la dernière fenêtre, le backend maintient `read_file`, `list_files` et `search_project` disponibles. Les écritures, remplacements, créations et renommages natifs restent aussi disponibles quand la politique d'approbation les autorise. Ces outils n'utilisent que le dernier projet signalé par l'application et refusent l'appel si ce projet n'est plus valide. Ils ne font jamais de supposition à partir d'autres projets de la bibliothèque. Statut, sélection de projet, suppression, compilation, journaux, inspection du PDF, changements de thème et outils de figure exigent une fenêtre connectée.

### Repérage

| Outil | Ce qu'il fait |
|---|---|
| `get_status` | Version d'Oleafly, projet ouvert, son moteur de document, document principal, statut de la dernière compilation, et pourquoi la dernière compilation a échoué ou n'a pas pu s'exécuter |
| `list_projects` | Projets avec identifiants, noms, moteurs, types, documents principaux, horodatages, couleurs, état de l'aperçu et historique d'exportation |
| `open_project` | Ouvre un projet par identifiant afin que les autres outils le ciblent |
| `list_files` | Arborescence des fichiers du projet |
| `project_map` | Plan, labels, citations, macros, graphe des inclusions, références non résolues |
| `search_project` | Recherche du texte dans le projet actuel |

### Lecture

| Outil | Ce qu'il fait |
|---|---|
| `read_file` | Lit un fichier du projet |
| `get_log` | Dernier journal de compilation |
| `get_pdf_text` | Texte extrait du PDF compilé |
| `verify_pdf_pages` | Vérifie les pages PDF rendues à la recherche de problèmes de mise en page, à partir d'images de pages ou du texte des pages |

`get_pdf_text` et `verify_pdf_pages` lisent le dernier PDF qu'Oleafly possède. Quand la dernière compilation a échoué ou n'a pas pu s'exécuter, leur résultat dit que le PDF est périmé et pourquoi, car il vient d'une compilation antérieure ou est un PDF partiel issu de la compilation échouée. `get_log` dit la même chose quand la dernière compilation n'a pas pu s'exécuter, car son journal vient alors d'une compilation antérieure.

### Modification

| Outil | Ce qu'il fait |
|---|---|
| `write_file` | Écrit ou remplace un fichier |
| `replace_in_file` | Recherche et remplace dans un fichier |
| `create_file` | Crée un fichier ou un dossier |
| `rename_file` | Renomme ou déplace un chemin |
| `delete_file` | Supprime un fichier ou un dossier |
| `set_main_doc` | Définit le document d'entrée de la compilation |

### Compilation et figures

| Outil | Ce qu'il fait |
|---|---|
| `compile` | Compile le projet en PDF |
| `preview_figure` | Effectue le rendu d'une figure isolée et renvoie une image PNG |
| `insert_figure` | Insère la dernière figure prévisualisée dans le document |
| `load_image` | Charge une image du projet pour le travail sur les figures |

`compile` dit si la compilation a réussi, liste ses erreurs, dit s'il existe un PDF, et se termine par la dernière partie du journal. Une compilation terminée signale aussi ses avertissements. Quand la compilation n'a pas pu s'exécuter, ne s'est pas terminée, ou a besoin de quelque chose en dehors du source, comme une installation TeX ou une version de Typst qui n'est pas là, le résultat donne la raison et nomme le correctif qu'Oleafly vous propose dans l'application. L'outil demande au client de vous le dire et de laisser votre source tranquille. Une compilation que vous avez arrêtée est marquée comme arrêtée, pour que le client ne la prenne pas pour une erreur dans le code. L'assistant d'Oleafly reçoit le même résultat.

Appelez d'abord `get_status` pour savoir si le projet est en LaTeX, Typst ou Markdown, puis écrivez le source dans ce format. `preview_figure` et `insert_figure` fonctionnent dans les projets LaTeX et Typst :

- En LaTeX, la figure est du code TikZ compilé dans un petit document autonome, et `insert_figure` l'enveloppe dans un environnement `figure`.
- En Typst, la figure est du balisage Typst, comme une toile CeTZ ou un diagramme fletcher, rendu avec la version Typst du projet. `insert_figure` l'enveloppe dans `#figure`, place le label après elle et déplace ses lignes `#import` au-dessus.
- Dans un projet Markdown, les deux outils renvoient une erreur et ne modifient rien.

`load_image` fonctionne dans tous les projets.

### Application

| Outil | Ce qu'il fait |
|---|---|
| `toggle_theme` | Bascule entre le mode clair et le mode sombre |

### Compétences

| Outil | Ce qu'il fait |
|---|---|
| `list_skills` | Liste les compétences installées avec leur identifiant, leur nom, leur description et leur état d'activation |
| `load_skill` | Charge les instructions complètes d'une compétence et sa liste de fichiers |
| `read_skill_file` | Lit une référence ou un script du dossier d'une compétence |

Les outils de compétences fonctionnent dès la connexion, sans projet ouvert et sans fenêtre Oleafly. Un client voit toutes les compétences valides, y compris celles désactivées dans Paramètres : les interrupteurs déterminent les compétences qu'utilise l'assistant d'Oleafly lui-même, pas celles qu'un client peut lire. Les agents qui lisent plutôt les compétences depuis un dossier peuvent utiliser **Partager les compétences avec les autres agents de cet ordinateur** dans **Paramètres → Assistant IA → Compétences**. Voir [Compétences](/docs/skills/).

### Notes

Ces outils sont disponibles tant que **Notes** est activé dans **Paramètres → Expérimentation**, comme le décrit [Activer Notes](/docs/notes/#turn-on-notes). Ils agissent sur vos notes, pas sur le projet ouvert, et ont besoin d'une fenêtre connectée.

| Outil | Ce qu'il fait |
|---|---|
| `list_knowledge_notes` | Liste vos notes, les plus récentes en premier, avec leurs identifiants, titres, tags, projets liés et courts résumés. Filtrable par tag ou par projet |
| `search_notes` | Cherche dans vos notes et renvoie les identifiants, titres, tags, liens et extraits correspondants |
| `read_note_by_id` | Lit une note en Markdown avec son en-tête (front matter) |
| `today_note` | Lit la note du jour, ou le titre qu'elle aurait si elle n'existe pas encore |
| `list_note_tasks` | Liste les tâches à cocher de vos notes, la note la plus récente en premier. Filtrable par note et par tâches ouvertes ou terminées |
| `note_backlinks` | Liste les notes qui renvoient à une note, avec le texte autour de chaque lien |
| `append_to_note` | Ajoute du Markdown à la fin d'une note ou de la note du jour |
| `edit_note_section` | Réécrit la partie d'une note située sous un titre, ou y ajoute du texte à la fin |
| `create_note` | Crée une note avec un titre, du Markdown, des tags et un projet lié |

`append_to_note` et `edit_note_section` n'écrivent pas dans la note. Leurs modifications y apparaissent comme des suggestions jusqu'à ce que vous les acceptiez dans Oleafly. `create_note` attend votre approbation dans Oleafly, tout comme `append_to_note` quand il doit d'abord créer la note du jour. Sous **Faire confiance à cette connexion**, la création d'une note ne demande rien. Une note partagée via un serveur de collaboration peut être lue mais pas modifiée de cette façon. **Lecture seule** retire les trois outils qui modifient des notes.

## Approbations et sécurité

De nombreux clients MCP demandent avant d'appeler un outil. Oleafly applique aussi la politique sélectionnée dans **Paramètres → Intégrations → Oleafly MCP** :

- **Confirmer chaque changement** est la politique par défaut. Écritures, renommages et suppressions affichent une carte d'approbation tant qu'une fenêtre de l'application est connectée. Sans fenêtre, ces opérations sont refusées car il n'y a nulle part où afficher la carte.
- **Autoriser les modifications, confirmer les suppressions** laisse les écritures et renommages s'exécuter dans le backend. Les suppressions exigent toujours une fenêtre connectée pour confirmation.
- **Faire confiance à cette connexion** laisse les écritures et renommages du backend s'exécuter sans invite Oleafly. La suppression exige toujours une fenêtre connectée. N'utilisez cette politique que si vous faites confiance au client et à ses propres contrôles d'approbation.

Deux autres interrupteurs complètent le dispositif :

- **Lecture seule** (interrupteur distinct) retire entièrement les outils modifiants de `tools/list` : une application externe peut lire et compiler, mais jamais modifier de fichiers, quelle que soit la politique ci-dessus.
- **Jeton bearer** : une valeur aléatoire de 256 bits stockée, chiffrée de manière authentifiée, dans le stockage local sous `~/.oleafly/`. Régénérez-le pour invalider les anciens clients. Les lectures ordinaires de la configuration n'exposent jamais le jeton. Seuls les contrôles de connexion du serveur en cours d'exécution peuvent le révéler dans Paramètres.

Et deux invariants que vous ne configurez pas :

- **Localhost uniquement** : l'adresse de liaison est `127.0.0.1`. Les requêtes portant un en-tête `Origin` de navigateur sont rejetées, et `Host` doit être en bouclage.
- **Confinement au projet** : les outils de fichiers du backend acceptent des chemins relatifs au projet et cantonnent les chemins canoniques au projet signalé par l'application. Un appel d'outil ne peut pas fournir un autre identifiant de projet ni amener le backend à choisir un autre projet de la bibliothèque.

## Suivre l'activité

Tant qu'une fenêtre est connectée, un onglet **Activité MCP** enregistre les appels entrants. Les appels au backend peuvent continuer après la fermeture de la dernière fenêtre, mais il n'y a plus ni panneau d'activité ni carte d'approbation tant qu'une fenêtre ne s'est pas reconnectée.

## Pourquoi claude.ai dans le navigateur ne peut pas se connecter

Un service de discussion dans le cloud ne peut pas atteindre `127.0.0.1` sur votre machine. Utilisez plutôt **Claude Desktop** (ou Claude Code, Cursor, etc.). N'ouvrez pas de tunnel vers l'internet public pour le port MCP : cela permettrait à quiconque dispose de l'URL de modifier et de supprimer vos fichiers de projet locaux.

## Dépannage

| Symptôme | Ce qu'il faut essayer |
|---|---|
| Certains outils sont indisponibles | Les prévisualisations de figures et les autres outils limités à l'interface exigent une fenêtre Oleafly. Ouvrez l'application et le projet, puis réessayez `tools/list`. |
| Le port a changé par rapport à `5323` | Le port préféré était indisponible, Oleafly en a donc choisi un libre. Copiez l'URL active depuis Paramètres. |
| HTTP 401 | Jeton non concordant (par exemple après une régénération). Copiez le nouveau jeton dans le client. |
| HTTP 403 | Le client a envoyé un en-tête `Origin` ou un `Host` hors bouclage. Utilisez un client MCP natif, pas un onglet de navigateur. |
| Délai d'appel dépassé | Chaque appel d'outil attend jusqu'à **5 minutes** (300 s) une compilation ou votre clic sur Approuver. Approuvez ou rejetez les cartes en attente, ou réessayez. Une compilation peut durer plus longtemps, jusqu'à une heure pour un notebook Quarto ou Calepin. Elle continue de tourner dans Oleafly après l'expiration de l'appel, et les outils qui ont besoin de la fenêtre Oleafly l'attendent : laissez-la donc finir avant de réessayer. |
| `compile` renvoie une raison au lieu d'erreurs | La compilation n'a pas pu s'exécuter, par exemple parce que TeX n'est pas installé. Utilisez le correctif qu'Oleafly propose dans l'application, comme installer TinyTeX, puis compilez de nouveau. |
| Connexion impossible | Oleafly doit être en cours d'exécution avec MCP activé. Ce serveur s'arrête quand vous quittez ; pour les outils de projet avec l'application fermée, connectez plutôt le client à `oleafly mcp`. |

## Ajouter des outils externes à Oleafly

![Paramètres → Assistant IA → MCP. Ajoutez un serveur, parcourez le registre ou importez des configurations depuis un autre outil.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

Pour donner plus d'outils à l'assistant intégré, ouvrez **Paramètres → Assistant IA → MCP**.

- **Parcourir le registre** pour trouver un serveur et examiner sa mise en place.
- **Importer depuis d'autres outils** pour sélectionner des configurations de serveurs existantes. Vérifiez les entrées sélectionnées avant l'import.
- **Ajouter un serveur** pour saisir un serveur vous-même, puis validez la connexion.

Les serveurs connectés exposent leurs outils à l'assistant. Vous pouvez consulter l'état des connexions et activer ou désactiver des serveurs depuis la même page. Identifiants et commandes appartiennent à chaque configuration de serveur ; vérifiez-les avant de connecter un nouveau serveur.

alphaXiv se connecte aussi comme serveur MCP, mais il se configure dans **Paramètres → Intégrations → alphaXiv** avec une clé d'API, et non ici. Une fois connecté, il apparaît dans cette liste sous le nom **alphaXiv**. [Connecter des sources de recherche](/docs/integrations/research-sources/#alphaxiv) détaille les étapes.

## Configurer un serveur externe à la main

![Ajouter un serveur → Formulaire. Choisissez Commande locale ou URL distante, remplissez les champs de connexion, puis utilisez Ajouter et Valider.](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

Dans **Paramètres → Assistant IA → MCP**, choisissez **Ajouter un serveur**. Un serveur local exécute une commande via stdio ; un serveur distant se connecte à une URL. Le formulaire JSON utilise le format de serveur d'Oleafly :

```json title="Configuration d'un serveur local"
{
  "name": "Research tools",
  "enabled": true,
  "transport": "stdio",
  "command": "your-mcp-server",
  "args": ["--stdio"],
  "env": {}
}
```

Remplacez la commande et les arguments par ceux documentés par le serveur que vous avez installé. Les valeurs d'environnement se placent dans l'objet `env`.

```json title="Configuration d'un serveur distant"
{
  "name": "Research service",
  "enabled": true,
  "transport": "remote",
  "url": "https://your-server.example/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}
```

Remplacez l'URL et le jeton d'exemple par les informations de connexion du service. Utilisez **Valider** pour vérifier la connexion, puis examinez les outils que le serveur expose. Activez ou désactivez le serveur depuis sa ligne. Utilisez son action de modification pour changer la configuration et son action de suppression pour le déconnecter.

## Importer des configurations MCP existantes

Choisissez **Importer depuis d'autres outils**, examinez les configurations découvertes et sélectionnez les serveurs voulus. Vérifiez les chemins d'exécutables, les variables d'environnement, les URL et les identifiants avant d'importer. L'import concerne les réglages de connexion ; il n'installe pas l'exécutable du serveur pour vous.

## Tester la connexion

1. Ouvrez un petit projet d'exercice dans Oleafly.
2. Connectez le client externe avec l'extrait copié depuis l'application.
3. Demandez au client d'appeler `get_status` et de lister les fichiers du projet.
4. Demandez-lui de lire le document principal et de proposer un changement de titre.
5. Vérifiez l'action dans Oleafly avant d'approuver une écriture.
6. Compilez et examinez le PDF.

Pour un outil externe connecté dans Oleafly, commencez par une requête simple en lecture seule prise en charge par ce serveur et examinez la carte d'outil qui apparaît dans la discussion.
