Connexions
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.
Activer le serveur
Section intitulée « Activer le serveur »- Ouvrez Paramètres → Intégrations → Oleafly MCP.
- 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
Section intitulée « Connecter votre client »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
Section intitulée « Claude Code »claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"Claude Desktop
Section intitulée « Claude Desktop »Ajoutez ceci à claude_desktop_config.json (pont stdio via mcp-remote, car Desktop privilégie stdio) :
{ "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
Section intitulée « 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 (s’ouvre dans un nouvel onglet) 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
Section intitulée « Cursor / VS Code »Dans .cursor/mcp.json (ou la configuration MCP de votre client) :
{ "mcpServers": { "oleafly": { "url": "http://127.0.0.1:5323/mcp", "headers": { "Authorization": "Bearer <token>" } } }}Grok CLI
Section intitulée « Grok CLI »Dans ~/.grok/config.toml :
[mcp_servers.oleafly]url = "http://127.0.0.1:5323/mcp"headers = { Authorization = "Bearer <token>" }Codex CLI
Section intitulée « 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 :
[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
Section intitulée « 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
Section intitulé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 |
| 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
Section intitulée « 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
Section intitulée « 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_figurel’enveloppe dans un environnementfigure. - En Typst, la figure est du balisage Typst, comme une toile CeTZ ou un diagramme fletcher, rendu avec la version Typst du projet.
insert_figurel’enveloppe dans#figure, place le label après elle et déplace ses lignes#importau-dessus. - Dans un projet Markdown, les deux outils renvoient une erreur et ne modifient rien.
load_image fonctionne dans tous les projets.
Application
Section intitulée « Application »| Outil | Ce qu’il fait |
|---|---|
toggle_theme | Bascule entre le mode clair et le mode sombre |
Compétences
Section intitulée « 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.
Ces outils sont disponibles tant que Notes est activé dans Paramètres → Expérimentation, comme le décrit Activer 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é
Section intitulée « 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êteOriginde navigateur sont rejetées, etHostdoit ê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é
Section intitulée « 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
Section intitulé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
Section intitulée « 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
Section intitulée « Ajouter des outils externes à Oleafly »
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 détaille les étapes.
Configurer un serveur externe à la main
Section intitulée « Configurer un serveur externe à la main »
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 :
{ "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.
{ "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
Section intitulée « 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
Section intitulée « Tester la connexion »- Ouvrez un petit projet d’exercice dans Oleafly.
- Connectez le client externe avec l’extrait copié depuis l’application.
- Demandez au client d’appeler
get_statuset de lister les fichiers du projet. - Demandez-lui de lire le document principal et de proposer un changement de titre.
- Vérifiez l’action dans Oleafly avant d’approuver une écriture.
- 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.