So liest Codex CLI deine osFoundry-Notes und Wissensdatenbanken über MCP

Am Ende kann Codex CLI die Spezifikations-Note, die Support-Wissensdatenbank und die Bug-Records in einem deiner osFoundry-Projekte nachschlagen, während es in deinem Repository arbeitet. Es liest sie über den MCP-Server von osFoundry, fragt dich vor allem, was schreibt, und jeder Aufruf wird in osFoundry unter Recent activity (letzte Aktivität) der Verbindung aufgeführt. Die Einrichtung besteht aus einer Tabelle in ~/.codex/config.toml, einer Anmeldung im Browser und einem Klick, um die Verbindung zu einem Projekt hinzuzufügen.

Wer macht was

	Seite von Codex	Seite von osFoundry
Anmeldung	Deine gewohnte Codex-Anmeldung, unverändert. Codex verwahrt das OAuth-Token von osFoundry	Dein osFoundry-Konto genehmigt die Verbindung einmal, für einen Workspace
Wer das Modell ausführt	Codex, auf deinem Rechner, mit deinem eigenen Codex-Plan	Niemand. Auf diesem Weg gibt es kein Modell und keinen Provider-Key
Wo die Tools laufen	Codex schickt den Tool-Aufruf per HTTPS	api.osfoundry.io führt ihn aus und prüft vorher den Zugriff
Welche Tools Codex sieht	enabled_tools / disabled_tools in config.toml	Die Tools-Checkliste der Verbindung
Was erreichbar ist	Was der Server zurückgibt	Projekte, denen du die Verbindung hinzugefügt hast, plus Channels, in die du sie eingeladen hast
Freigaben	Codex' eigene Rückfrage, festgelegt über default_tools_approval_mode	Änderungen an GitNest und Room warten unter "Needs your approval" (wartet auf deine Freigabe)
Wo die Daten bleiben	Antworten und Diffs bleiben in deiner Codex-Sitzung	Notes, Records und Artikel bleiben in osFoundry. Rein lokale Elemente verlassen das Gerät nie

Einrichtung

1. Die Verbindung in osFoundry anlegen

Klick auf das Schlüsselsymbol im Header von osFoundry und öffne den Tab Connected ("Connected agents", darunter der Name des aktuellen Workspaces). Im Formular unter "Connect in three steps":

• Assistant: Other MCP client
• Display name: etwas, das du wiedererkennst, z. B. Codex CLI
• Klick auf Add assistant (Assistent hinzufügen)

Die Verbindung erscheint als "Setup pending. This assistant cannot read or change anything yet." Kopiere die Server address:

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

Beispiel: Der Tab Connected mit ausgewählter Verbindung Codex CLI

2. Den Server zu Codex hinzufügen

Der Einzeiler aus der MCP-Dokumentation von Codex von OpenAI:

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

Das schreibt eine Tabelle [mcp_servers.osfoundry]. Öffne ~/.codex/config.toml und zieh sie enger. Jeder Schlüssel unten steht in dieser Dokumentation:

[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",
]

Was jede Zeile bringt:

• scopes ersetzt das, was der Server anbietet. Ohne diesen Schlüssel nimmt Codex die Scopes aus der Challenge des Servers oder aus seinen Protected-Resource-Metadaten, und die Metadaten von osFoundry listen vier auf, darunter osfoundry:run. Ein Coding-Assistent, der Records nur liest und aktualisiert, muss keine Sitzungen starten.
• default_tools_approval_mode = "writes" lässt Codex bei jedem Tool nachfragen, das nicht als read-only markiert ist. osFoundry markiert seine Tools mit readOnlyHint, also laufen die neun Lese-Tools ohne Rückfrage, und edit_record_item fragt zuerst.
• enabled_tools hält die Tool-Liste kurz. Der Server bietet 59 Tools an, diese Liste hat zehn. Die Namen sind die rohen MCP-Tool-Namen, ohne Präfix. Ein Tippfehler im Namen ist kein Fehler. Das Tool fehlt dann einfach.

Soll der Server nur in einem Repository gelten, leg dieselbe Tabelle stattdessen in die .codex/config.toml dieses Repositorys. Codex liest Projektkonfiguration nur für Projekte, die du als vertrauenswürdig (trusted) markiert hast.

3. Anmelden

codex mcp login osfoundry

Der Browser öffnet https://osfoundry.io/external-assistant-authorize mit dem Titel "Connect an agent". Dort stehen der Assistant client und "Returns to". Das ist eine lokale Adresse, weil Codex den Callback auf deinem Rechner entgegennimmt. Danach:

• Workspace to connect: einen auswählen. Ein zweiter Workspace braucht eine eigene Verbindung.
• Requested capabilities: mit den scopes von oben siehst du zwei Zeilen, "Read supported resources in projects you add" und "Change supported resources where you have edit access".
• Connection: "Use pending: Codex CLI" wählen, damit die Anmeldung an die Verbindung aus Schritt 1 gebunden wird.
• "I approve connecting this assistant to " anhaken und auf Connect klicken.

Auf einem entfernten Rechner per SSH gibt codex mcp login osfoundry --no-browser stattdessen die URL aus. Du öffnest sie auf deinem Laptop und fügst die vollständige Redirect-URL wieder ins Terminal ein.

Der Server von osFoundry hat einen Registrierungs-Endpoint und akzeptiert öffentliche Clients, also registriert sich Codex selbst. Eine Client-ID musst du nicht einfügen.

4. Die Verbindung zu einem Projekt hinzufügen

Zurück unter Schlüsselsymbol → Connected steht bei der Verbindung jetzt "Connected." Wähl unter Projects das Projekt aus und klick auf Add to project (zum Projekt hinzufügen). Damit werden die synchronisierten Notes des Projekts geöffnet, seine Wissensdatenbanken, Record-Channels, Cloud-Rooms, zugewiesenen GitNest-Repositorys und sein Diskussions-Channel, einschließlich allem, was später dazukommt. Andere Message-Channels brauchen jeweils ein eigenes Invite (Einladung).

Der Abschnitt Tools beginnt mit "All supported tools are on by default." Entferne den Haken bei allem, was diese Verbindung nie aufrufen soll, selbst wenn jemand später config.toml bearbeitet, und klick auf Save tools (Tools speichern).

Beispiel: Die Tools-Checkliste, nur die Lese-Tools angehakt, dann Save tools

5. In Codex prüfen

In der TUI von codex listet /mcp die aktiven Server auf. osfoundry sollte dabei sein. Dann frag einfach in normalen Worten.

Ein echter Durchlauf

Auf dem Rechner, auf dem dieser Text entstand, ist Codex nicht installiert, daher ist die Sitzung unten ein simuliertes Beispiel. Die Tool-Namen sind die, die der Live-Server über tools/list zurückgibt. Der Quellcode von Codex stellt MCP-Tools in den Namen, die das Modell sieht, mcp__<server>__ voran, deshalb erscheinen sie hier so. Prompt, Projekt und Antworten sind Demo-Inhalte.

Beispiel (simuliert)

> Der fehlschlagende Test in tests/test_refund.py erwartet ein Fenster von 14 Tagen.
  Prüf die Spezifikation in osFoundry und die Support-KB, bevor du etwas änderst.

• mcp__osfoundry__list_granted_resources {}
  ← 1 Projekt: "Billing v2"
• mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "note", "search": "Erstattung"}
  ← Note "Erstattungsregeln (Spezifikation)"
• mcp__osfoundry__list_note_tabs {"note_id": "…"}
  ← Tabs: Note (Text), Sheet "Sonderfälle"
• mcp__osfoundry__read_note_tab {"note_id": "…", "tab_id": "…"}
  ← "Erstattungen werden innerhalb von 30 Tagen nach Rechnungsdatum angenommen…"
• mcp__osfoundry__search_knowledge_base {"knowledge_base_id": "…", "query": "Erstattungsfrist"}
  ← Artikel "Erstattungsrichtlinie", vor 2 Tagen aktualisiert: 30 Tage
• 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 fragt: diesen Tool-Aufruf erlauben? → ja]
  ← saved

Falsch war der Test, nicht der Code. Die Spezifikations-Note und der KB-Artikel
sagen beide 30 Tage. Ich habe den Test und den Kommentar der Konstante geändert,
pytest ausgeführt (12 bestanden) und den Record "Erstattungsfrist um 16 Tage
verschoben" auf Fixed gesetzt.

edit_record_item trägt die Version mit, die read_record_item oder list_record_items zurückgegeben hat. Ein Record, den in der Zwischenzeit jemand geändert hat, wird also abgelehnt statt überschrieben. Ein wiederholter idempotency_key liefert das erste Ergebnis, also schreibt ein wiederholter Aufruf nicht zweimal. Die Freigabe-Rückfrage in der Mitte kommt von Codex, nicht von osFoundry, wegen default_tools_approval_mode = "writes".

Wo die Grenze verläuft

Codex liest osFoundry, osFoundry liest Codex nicht. Die Verbindung erlaubt Codex, Tools aufzurufen, wenn es das für nötig hält. osFoundry führt jeden Aufruf in Recent activity mit Tool-Name, Zugriffsentscheidung und Uhrzeit auf, kann aber weder deine Codex-Sitzung noch dein Repository oder dein Terminal öffnen. Dein Quellcode geht nirgendwohin, es sei denn, Codex packt ihn in ein Tool-Argument, etwa einen Kommentar zu einem Record.

Die beiden Filter haben unterschiedliche Aufgaben. enabled_tools in config.toml bestimmt, was dem Modell angeboten wird. Das hält den Prompt kurz und die Auswahl eindeutig. Die Tools-Checkliste in osFoundry ist der Schalter des Eigentümers und gilt unabhängig davon, was in der lokalen Datei steht. Keiner der beiden gewährt Zugriff auf irgendetwas. Das regelt die Projektmitgliedschaft.

Über den Zugriff wird bei jedem Aufruf entschieden. Jeder Aufruf wird gegen den Status der Verbindung geprüft, ihren Workspace, die aktuelle Projektmitgliedschaft, das Projekt, in dem das Element gerade liegt, und deine eigene Rolle darin. Verschieb eine Note in ein anderes Projekt, entferne das Projekt oder klick auf Revoke connection (Verbindung widerrufen), und der nächste Aufruf von Codex wird abgelehnt, auch wenn sein Token noch nicht abgelaufen ist.

Manche Schreibvorgänge sind Vorschläge. GitNest-Arbeit, Change Sets, Dateiimporte und Pull Requests laufen über propose_…-Tools und warten im Tab Connected unter "Needs your approval", mit Ziel und Dateien aufgelistet, bis du auf Approve oder Decline klickst. Codex bekommt nie das Token deines Git-Providers. Die Beispielkonfiguration oben lässt diese Tools ohnehin weg, da Codex deinen lokalen Checkout schon hat.

Rein lokale Daten bleiben lokal. Die initialize-Antwort des Servers sagt es: "Local-only data is unavailable to cloud clients." Lokale Rooms, lokale Graph-Sitzungen und alles, was nicht synchronisiert wurde, sind über diese Verbindung nicht sichtbar.

Als Nächstes

Richte Codex auf eine Wissensdatenbank, aus der du ohnehin Fragen beantwortest, und lass es einen Docstring oder eine Fehlermeldung damit abgleichen, z. B. "Passt der Wortlaut in der KB zu diesem Fehler zu dem, was der Code ausgibt?". search_knowledge_base gibt die Artikel-ID und den Zeitpunkt der letzten Aktualisierung zurück, sodass sich die Quelle leicht prüfen lässt. Wie osFoundry sie organisiert, steht auf der Seite zu Wissensdatenbanken.