Comment faire lire vos notes et bases de connaissances osFoundry à Codex CLI via MCP

À la fin, Codex CLI pourra consulter la Note de spécification, la base de connaissances du support et les Records de bugs d'un de vos projets osFoundry pendant qu'il travaille dans votre dépôt. Il les lit via le serveur MCP d'osFoundry, vous demande avant toute écriture, et chaque appel qu'il fait est listé dans osFoundry sous le Recent activity (activité récente) de la connexion. La configuration tient en une table dans ~/.codex/config.toml, une connexion dans le navigateur et un clic pour ajouter la connexion à un projet.

Qui fait quoi

Configuration

1. Créer la connexion dans osFoundry

Cliquez sur l'icône de clé dans l'en-tête d'osFoundry et ouvrez l'onglet Connected ("Connected agents", avec le nom du workspace actuel en dessous). Dans le formulaire sous "Connect in three steps" :

• Assistant : Other MCP client
• Display name : un nom que vous reconnaîtrez, par exemple Codex CLI
• Cliquez sur Add assistant (ajouter l'assistant)

La connexion apparaît comme "Setup pending. This assistant cannot read or change anything yet." Copiez la Server address :

https://api.osfoundry.io/api/v1/external-mcp

Exemple : L'onglet Connected avec la connexion Codex CLI sélectionnée

2. Ajouter le serveur à Codex

La commande d'une ligne tirée de la documentation MCP de Codex d'OpenAI :

codex mcp add osfoundry --url https://api.osfoundry.io/api/v1/external-mcp

Elle écrit une table [mcp_servers.osfoundry]. Ouvrez ~/.codex/config.toml et resserrez-la. Toutes les clés ci-dessous figurent dans cette documentation :

[mcp_servers.osfoundry]
url = "https://api.osfoundry.io/api/v1/external-mcp"
scopes = ["osfoundry:read", "osfoundry:write"]
default_tools_approval_mode = "writes"
enabled_tools = [
  "list_granted_resources",
  "list_project_resources",
  "list_note_tabs",
  "read_note_tab",
  "read_sheet_range",
  "search_knowledge_base",
  "read_knowledge_article",
  "list_record_items",
  "read_record_item",
  "edit_record_item",
]

Ce que chaque ligne apporte :

• scopes remplace ce que propose le serveur. Sans elle, Codex prend les scopes dans le challenge du serveur ou dans ses protected-resource metadata, et les métadonnées d'osFoundry en listent quatre, dont osfoundry:run. Un assistant de code qui se contente de lire et de mettre à jour des records n'a pas besoin de lancer des sessions.
• default_tools_approval_mode = "writes" fait demander une confirmation à Codex pour chaque outil qui n'est pas marqué en lecture seule. osFoundry marque ses outils avec readOnlyHint, donc les neuf outils de lecture s'exécutent sans confirmation et edit_record_item demande d'abord.
• enabled_tools garde la liste d'outils courte. Le serveur en annonce 59 ; cette liste en compte dix. Les noms sont les noms MCP bruts, sans préfixe. Un nom mal orthographié ne provoque pas d'erreur. L'outil n'est simplement pas là.

Si le serveur ne doit s'appliquer qu'à un seul dépôt, mettez la même table dans le .codex/config.toml de ce dépôt. Codex ne lit la configuration de projet que pour les projets que vous avez marqués comme fiables (trusted).

3. Se connecter

codex mcp login osfoundry

Le navigateur ouvre https://osfoundry.io/external-assistant-authorize, intitulé "Connect an agent". La page affiche l'Assistant client et "Returns to", une adresse locale puisque Codex reçoit le callback sur votre machine. Ensuite :

• Workspace to connect : choisissez-en un. Un deuxième workspace nécessite sa propre connexion.
• Requested capabilities : avec les scopes ci-dessus, vous verrez deux lignes, "Read supported resources in projects you add" et "Change supported resources where you have edit access".
• Connection : choisissez "Use pending: Codex CLI" pour que la connexion se rattache à celle de l'étape 1.
• Cochez "I approve connecting this assistant to " et cliquez sur Connect.

Sur une machine distante en SSH, codex mcp login osfoundry --no-browser affiche l'URL à la place. Vous l'ouvrez sur votre ordinateur portable et collez l'URL de redirection complète dans le terminal.

Le serveur d'osFoundry dispose d'un endpoint d'enregistrement et accepte les clients publics, donc Codex s'enregistre tout seul. Aucun client ID à coller.

4. Ajouter la connexion à un projet

De retour dans icône de clé → Connected, la connexion indique maintenant "Connected." Sous Projects, choisissez le projet et cliquez sur Add to project (ajouter au projet). Cela ouvre les Notes synchronisées du projet, ses bases de connaissances, ses canaux Record, ses Rooms cloud, ses dépôts GitNest attribués et son canal de discussion, y compris tout ce qui sera ajouté plus tard. Les autres canaux Message nécessitent chacun un Invite (invitation).

La section Tools commence avec "All supported tools are on by default." Décochez tout ce que cette connexion ne doit jamais appeler, même si quelqu'un modifie config.toml plus tard, puis cliquez sur Save tools (enregistrer les outils).

Exemple : La checklist Tools avec seulement les outils de lecture cochés, puis Save tools

5. Vérifier depuis Codex

Dans la TUI de codex, /mcp liste les serveurs actifs. osfoundry doit y figurer. Ensuite, demandez simplement avec vos mots.

Une exécution réelle

Codex n'est pas installé sur la machine où ce texte a été écrit, donc la session ci-dessous est un exemple simulé. Les noms d'outils sont ceux que le serveur réel renvoie via tools/list. Le code source de Codex préfixe les outils MCP par mcp__<server>__ dans les noms que voit le modèle, d'où leur forme ici. Le prompt, le projet et les réponses sont du contenu de démonstration.

Exemple (simulé)

> Le test qui échoue dans tests/test_refund.py attend une fenêtre de 14 jours.
  Vérifie la spec osFoundry et la KB du support avant de modifier quoi que ce soit.

• mcp__osfoundry__list_granted_resources {}
  ← 1 projet : "Billing v2"
• mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "note", "search": "remboursement"}
  ← Note "Règles de remboursement (spec)"
• mcp__osfoundry__list_note_tabs {"note_id": "…"}
  ← onglets : Note (texte), Sheet "Cas limites"
• mcp__osfoundry__read_note_tab {"note_id": "…", "tab_id": "…"}
  ← "Les remboursements sont acceptés dans les 30 jours suivant la date de facture…"
• mcp__osfoundry__search_knowledge_base {"knowledge_base_id": "…", "query": "délai de remboursement"}
  ← article "Politique de remboursement", mis à jour il y a 2 jours : 30 jours
• edited src/billing/refund.py, tests/test_refund.py
• mcp__osfoundry__edit_record_item {"record_channel_id": "…", "item_id": "…",
      "values": {"status": "Fixed"}, "expected_version": "…", "idempotency_key": "…"}
  [Codex demande : autoriser cet appel d'outil ? → oui]
  ← saved

C'était le test qui était faux, pas le code. La Note de spec et l'article de
la KB disent tous deux 30 jours. J'ai modifié le test et le commentaire de la
constante, lancé pytest (12 réussis) et passé le record "Délai de
remboursement décalé de 16 jours" à Fixed.

edit_record_item transmet la version renvoyée par read_record_item ou list_record_items, donc un record modifié entre-temps par quelqu'un d'autre est rejeté au lieu d'être écrasé. Un idempotency_key répété renvoie le premier résultat, donc un appel relancé n'écrit pas deux fois. La demande d'approbation au milieu vient de Codex, pas d'osFoundry, à cause de default_tools_approval_mode = "writes".

Où passe la limite

Codex lit osFoundry, osFoundry ne lit pas Codex. La connexion permet à Codex d'appeler des outils quand il le décide. osFoundry liste chaque appel dans Recent activity avec le nom de l'outil, la décision d'accès et l'heure, mais il ne peut ouvrir ni votre session Codex, ni votre dépôt, ni votre terminal. Votre code source ne va nulle part, sauf si Codex le place dans un argument d'outil, comme un commentaire de record.

Les deux filtres ont des rôles différents. enabled_tools dans config.toml décide de ce qui est proposé au modèle, ce qui garde le prompt court et les choix évidents. La checklist Tools d'osFoundry est l'interrupteur du propriétaire, et elle reste en vigueur quoi que dise le fichier local. Aucun des deux n'accorde d'accès à quoi que ce soit. Ça, c'est l'appartenance au projet.

L'accès est décidé à chaque appel. Chaque appel est vérifié par rapport au statut de la connexion, à son workspace, à l'appartenance actuelle au projet, au projet dans lequel se trouve l'élément à ce moment-là et à votre propre rôle dans celui-ci. Déplacez une Note vers un autre projet, retirez le projet ou cliquez sur Revoke connection (révoquer la connexion), et l'appel suivant de Codex est refusé, même si son token n'a pas expiré.

Certaines écritures sont des propositions. Le travail GitNest, les change sets, les imports de fichiers et les pull requests passent par des outils propose_… et attendent dans l'onglet Connected sous "Needs your approval", avec la cible et les fichiers listés, jusqu'à ce que vous cliquiez sur Approve ou Decline. Codex ne reçoit jamais le token de votre fournisseur Git. La configuration d'exemple ci-dessus laisse de toute façon ces outils de côté, puisque Codex a déjà votre checkout local.

Les données uniquement locales restent locales. La réponse initialize du serveur le dit : "Local-only data is unavailable to cloud clients." Les Rooms locales, les sessions Graph locales et tout ce qui n'a pas été synchronisé ne sont pas visibles via cette connexion.

Pour la suite

Pointez Codex vers une base de connaissances qui vous sert déjà à répondre aux questions, et demandez-lui de vérifier une docstring ou un message d'erreur par rapport à elle, par exemple : "La formulation de la KB pour cette erreur correspond-elle à ce qu'affiche le code ?". search_knowledge_base renvoie l'ID de l'article et la date de sa dernière mise à jour, la source est donc facile à vérifier. La façon dont osFoundry les organise est décrite sur la page des bases de connaissances.