Aller au contenu
Oleaflyv0.4.12

Connexions

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.

MCP dans les deux sensDans un sens, un client MCP sur votre ordinateur, comme Claude Desktop, Cursor ou Codex, se connecte au serveur MCP d’Oleafly sur 127.0.0.1 avec un jeton porteur. Il peut lire, modifier et compiler le projet, et votre politique d’approbation décide quelles modifications vous attendent. Dans l’autre sens, l’assistant intégré d’Oleafly utilise les outils des serveurs MCP que vous ajoutez : un serveur local qui exécute une commande, ou un serveur distant à une URL.Votre client MCP utilise les outils d’OleaflyL’assistant d’Oleafly utilise d’autres serveurs MCPClient MCPClaude Desktop,Cursor, CodexOleafly MCP127.0.0.1 uniquementProjetLire, modifier, compilerJeton porteurApprobationsAssistantIntégré à OleaflyServeur localExécute une commandeServeur distantSe connecte à une URLMCP dans les deux sensDans un sens, un client MCP sur votre ordinateur, comme Claude Desktop, Cursor ou Codex, se connecte au serveur MCP d’Oleafly sur 127.0.0.1 avec un jeton porteur. Il peut lire, modifier et compiler le projet, et votre politique d’approbation décide quelles modifications vous attendent. Dans l’autre sens, l’assistant intégré d’Oleafly utilise les outils des serveurs MCP que vous ajoutez : un serveur local qui exécute une commande, ou un serveur distant à une URL.Votre client MCP utilise OleaflyL’assistant d’Oleafly utilise des serveursClient MCPClaude Desktop, CursorOleafly MCP127.0.0.1 uniquementProjetLire, modifier, compilerJeton porteurApprobationsAssistantIntégré à OleaflyServeur localExécute une commandeServeur distantSe connecte à une URL
Un client MCP sur votre ordinateur accède aux outils de projet d’Oleafly via 127.0.0.1 et un jeton. Dans l’autre sens, l’assistant d’Oleafly peut utiliser les outils des serveurs MCP que vous ajoutez.
  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.

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).

Fenêtre de terminal
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"

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"
]
}
}
}

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.

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>"
}
}
}
}

Dans ~/.grok/config.toml :

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

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 :

~/.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.

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.

OutilCe qu’il fait
get_statusVersion 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_projectsProjets avec identifiants, noms, moteurs, types, documents principaux, horodatages, couleurs, état de l’aperçu et historique d’exportation
open_projectOuvre un projet par identifiant afin que les autres outils le ciblent
list_filesArborescence des fichiers du projet
project_mapPlan, labels, citations, macros, graphe des inclusions, références non résolues
search_projectRecherche du texte dans le projet actuel
OutilCe qu’il fait
read_fileLit un fichier du projet
get_logDernier journal de compilation
get_pdf_textTexte extrait du PDF compilé
verify_pdf_pagesVé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.

OutilCe qu’il fait
write_fileÉcrit ou remplace un fichier
replace_in_fileRecherche et remplace dans un fichier
create_fileCrée un fichier ou un dossier
rename_fileRenomme ou déplace un chemin
delete_fileSupprime un fichier ou un dossier
set_main_docDéfinit le document d’entrée de la compilation
OutilCe qu’il fait
compileCompile le projet en PDF
preview_figureEffectue le rendu d’une figure isolée et renvoie une image PNG
insert_figureInsère la dernière figure prévisualisée dans le document
load_imageCharge 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.

OutilCe qu’il fait
toggle_themeBascule entre le mode clair et le mode sombre
OutilCe qu’il fait
list_skillsListe les compétences installées avec leur identifiant, leur nom, leur description et leur état d’activation
load_skillCharge les instructions complètes d’une compétence et sa liste de fichiers
read_skill_fileLit 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.

OutilCe qu’il fait
list_knowledge_notesListe 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_notesCherche dans vos notes et renvoie les identifiants, titres, tags, liens et extraits correspondants
read_note_by_idLit une note en Markdown avec son en-tête (front matter)
today_noteLit la note du jour, ou le titre qu’elle aurait si elle n’existe pas encore
list_note_tasksListe 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_backlinksListe les notes qui renvoient à une note, avec le texte autour de chaque lien
append_to_noteAjoute du Markdown à la fin d’une note ou de la note du jour
edit_note_sectionRéécrit la partie d’une note située sous un titre, ou y ajoute du texte à la fin
create_noteCré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.

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.

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.

SymptômeCe qu’il faut essayer
Certains outils sont indisponiblesLes 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 à 5323Le port préféré était indisponible, Oleafly en a donc choisi un libre. Copiez l’URL active depuis Paramètres.
HTTP 401Jeton non concordant (par exemple après une régénération). Copiez le nouveau jeton dans le client.
HTTP 403Le 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’erreursLa 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 impossibleOleafly 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.
Paramètres → Assistant IA → MCP. Ajoutez un serveur, parcourez le registre ou importez des configurations depuis un autre outil.
Paramètres → Assistant IA → MCP. Ajoutez un serveur, parcourez le registre ou importez des configurations depuis un autre outil. Ouvrir la capture complète

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.

Ajouter un serveur → Formulaire. Choisissez Commande locale ou URL distante, remplissez les champs de connexion, puis utilisez Ajouter et Valider.
Ajouter un serveur → Formulaire. Choisissez Commande locale ou URL distante, remplissez les champs de connexion, puis utilisez Ajouter et Valider. Ouvrir la capture complète

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 :

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.

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.

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.

  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.

Aperçu de l’image

Impossible de charger les réponses de l’IA

Réessayez ou cherchez dans la documentation.