Come far leggere a Codex CLI le note e le knowledge base di osFoundry tramite MCP

Alla fine, Codex CLI potrà consultare la Note con le specifiche, la knowledge base del supporto e i Record dei bug di uno dei tuoi progetti osFoundry mentre lavora nel tuo repository. Li legge tramite il server MCP di osFoundry, ti chiede conferma prima di qualsiasi scrittura, e ogni chiamata che fa viene elencata in osFoundry nella Recent activity (attività recente) della connessione. La configurazione è una tabella in ~/.codex/config.toml, un accesso dal browser e un clic per aggiungere la connessione a un progetto.

Chi fa cosa

	Lato Codex	Lato osFoundry
Accesso	Il tuo solito accesso a Codex, invariato. Codex conserva il token OAuth di osFoundry	Il tuo account osFoundry approva la connessione una volta, per un workspace
Chi esegue il modello	Codex, sulla tua macchina, con il tuo piano Codex	Nessuno. Su questo percorso non c'è alcun modello né chiave di un provider
Dove girano i tool	Codex invia la chiamata al tool via HTTPS	api.osfoundry.io la esegue dopo aver controllato l'accesso
Quali tool vede Codex	enabled_tools / disabled_tools in config.toml	La checklist Tools della connessione
Cosa può raggiungere	Ciò che il server restituisce	I progetti a cui hai aggiunto la connessione, più i canali in cui l'hai invitata
Approvazioni	La richiesta di conferma di Codex, impostata con default_tools_approval_mode	Le modifiche a GitNest e Room restano in attesa in "Needs your approval" (in attesa della tua approvazione)
Dove restano i dati	Risposte e diff restano nella tua sessione Codex	Note, record e articoli restano in osFoundry. Gli elementi solo locali non lasciano mai il dispositivo

Configurazione

1. Crea la connessione in osFoundry

Fai clic sull'icona della chiave nell'intestazione di osFoundry e apri la scheda Connected ("Connected agents", con il nome del workspace corrente sotto). Nel modulo sotto "Connect in three steps":

• Assistant: Other MCP client
• Display name: un nome che riconoscerai, per esempio Codex CLI
• Fai clic su Add assistant (aggiungi assistente)

La connessione compare come "Setup pending. This assistant cannot read or change anything yet." Copia la Server address:

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

Esempio: La scheda Connected con la connessione Codex CLI selezionata

2. Aggiungi il server a Codex

Il comando su una riga dalla documentazione MCP di Codex di OpenAI:

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

Questo scrive una tabella [mcp_servers.osfoundry]. Apri ~/.codex/config.toml e restringila. Tutte le chiavi qui sotto sono in quella documentazione:

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

A cosa serve ogni riga:

• scopes sostituisce ciò che offre il server. Senza, Codex prende gli scope dalla challenge del server o dai suoi protected-resource metadata, e i metadati di osFoundry ne elencano quattro, tra cui osfoundry:run. Un assistente di programmazione che si limita a leggere e aggiornare record non ha bisogno di avviare sessioni.
• default_tools_approval_mode = "writes" fa chiedere conferma a Codex per ogni tool non contrassegnato come di sola lettura. osFoundry contrassegna i suoi tool con readOnlyHint, quindi i nove tool di lettura girano senza conferma e edit_record_item chiede prima.
• enabled_tools mantiene corta la lista dei tool. Il server ne annuncia 59; questa lista ne ha dieci. I nomi sono quelli MCP grezzi, senza prefisso. Un nome scritto male non genera errori. Il tool semplicemente non c'è.

Se il server deve valere solo in un repository, metti la stessa tabella nel .codex/config.toml di quel repository. Codex legge la configurazione di progetto solo per i progetti che hai contrassegnato come attendibili (trusted).

3. Accedi

codex mcp login osfoundry

Il browser apre https://osfoundry.io/external-assistant-authorize, intitolata "Connect an agent". Mostra l'Assistant client e "Returns to", che è un indirizzo locale perché Codex riceve il callback sulla tua macchina. Poi:

• Workspace to connect: scegline uno. Un secondo workspace richiede una connessione a parte.
• Requested capabilities: con gli scopes di sopra vedrai due righe, "Read supported resources in projects you add" e "Change supported resources where you have edit access".
• Connection: scegli "Use pending: Codex CLI" così l'accesso si collega alla connessione del passo 1.
• Spunta "I approve connecting this assistant to " e fai clic su Connect.

Su una macchina remota via SSH, codex mcp login osfoundry --no-browser stampa invece l'URL. Lo apri sul tuo portatile e incolli nel terminale l'URL di redirect completo.

Il server di osFoundry ha un endpoint di registrazione e accetta client pubblici, quindi Codex si registra da solo. Non devi incollare nessun client ID.

4. Aggiungi la connessione a un progetto

Tornando in icona della chiave → Connected, la connessione ora riporta "Connected." In Projects scegli il progetto e fai clic su Add to project (aggiungi al progetto). Questo apre le Note sincronizzate del progetto, le sue knowledge base, i canali Record, le Room in cloud, i repository GitNest assegnati e il suo canale di discussione, compreso tutto ciò che verrà aggiunto in seguito. Gli altri canali Message richiedono ciascuno un Invite (invito).

La sezione Tools parte con "All supported tools are on by default." Togli la spunta a tutto ciò che questa connessione non deve mai chiamare, anche se qualcuno modificherà config.toml più avanti, e fai clic su Save tools (salva tool).

Esempio: La checklist Tools con solo i tool di lettura spuntati, poi Save tools

5. Verifica da Codex

Nella TUI di codex, /mcp elenca i server attivi. osfoundry dovrebbe esserci. Poi chiedi pure con parole normali.

Un'esecuzione reale

Codex non è installato sulla macchina su cui è stato scritto questo testo, quindi la sessione qui sotto è un esempio simulato. I nomi dei tool sono quelli che il server reale restituisce con tools/list. Il codice sorgente di Codex antepone mcp__<server>__ ai tool MCP nei nomi che vede il modello, ed è per questo che qui compaiono così. Prompt, progetto e risposte sono contenuti dimostrativi.

Esempio (simulato)

> Il test che fallisce in tests/test_refund.py si aspetta una finestra di 14 giorni.
  Controlla la specifica in osFoundry e la KB del supporto prima di cambiare qualcosa.

• mcp__osfoundry__list_granted_resources {}
  ← 1 progetto: "Billing v2"
• mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "note", "search": "rimborso"}
  ← Note "Regole di rimborso (specifica)"
• mcp__osfoundry__list_note_tabs {"note_id": "…"}
  ← schede: Note (testo), Sheet "Casi limite"
• mcp__osfoundry__read_note_tab {"note_id": "…", "tab_id": "…"}
  ← "I rimborsi sono accettati entro 30 giorni dalla data della fattura…"
• mcp__osfoundry__search_knowledge_base {"knowledge_base_id": "…", "query": "termine di rimborso"}
  ← articolo "Politica di rimborso", aggiornato 2 giorni fa: 30 giorni
• 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 chiede: consentire questa chiamata al tool? → sì]
  ← saved

Era sbagliato il test, non il codice. Sia la Note con le specifiche sia
l'articolo della KB dicono 30 giorni. Ho modificato il test e il commento
della costante, eseguito pytest (12 superati) e impostato il record
"Termine di rimborso sfasato di 16 giorni" su Fixed.

edit_record_item porta con sé la versione restituita da read_record_item o list_record_items, quindi un record che qualcuno ha modificato nel frattempo viene rifiutato invece di essere sovrascritto. Un idempotency_key ripetuto restituisce il primo risultato, quindi una chiamata ritentata non scrive due volte. La richiesta di approvazione a metà viene da Codex, non da osFoundry, per via di default_tools_approval_mode = "writes".

Dov'è il confine

Codex legge osFoundry, osFoundry non legge Codex. La connessione permette a Codex di chiamare tool quando decide di farlo. osFoundry elenca ogni chiamata in Recent activity con il nome del tool, la decisione di accesso e l'ora, ma non può aprire la tua sessione Codex, il tuo repository o il tuo terminale. Il tuo codice sorgente non va da nessuna parte, a meno che Codex non lo inserisca in un argomento di un tool, come un commento a un record.

I due filtri fanno lavori diversi. enabled_tools in config.toml decide cosa viene offerto al modello, il che tiene corto il prompt e chiare le scelte. La checklist Tools in osFoundry è l'interruttore del proprietario e resta in vigore qualunque cosa dica il file locale. Nessuno dei due concede accesso a qualcosa. Quello lo decide l'appartenenza al progetto.

L'accesso viene deciso a ogni chiamata. Ogni chiamata viene verificata rispetto allo stato della connessione, al suo workspace, all'appartenenza attuale al progetto, al progetto in cui si trova ora l'elemento e al tuo ruolo in esso. Sposta una Note in un altro progetto, rimuovi il progetto o fai clic su Revoke connection (revoca connessione), e la chiamata successiva di Codex viene rifiutata anche se il suo token non è scaduto.

Alcune scritture sono proposte. Il lavoro su GitNest, i change set, le importazioni di file e le pull request passano dai tool propose_… e restano in attesa nella scheda Connected sotto "Needs your approval", con destinazione e file elencati, finché non fai clic su Approve o Decline. Codex non riceve mai il token del tuo provider Git. In ogni caso la configurazione di esempio qui sopra lascia fuori quei tool, dato che Codex ha già il tuo checkout locale.

I dati solo locali restano in locale. La risposta initialize del server lo dice: "Local-only data is unavailable to cloud clients." Le Room locali, le sessioni Graph locali e tutto ciò che non è stato sincronizzato non sono visibili attraverso questa connessione.

Prossimo passo

Punta Codex su una knowledge base che usi già per rispondere alle domande e chiedigli di confrontarci una docstring o un messaggio di errore, per esempio: "Il testo della KB per questo errore corrisponde a ciò che stampa il codice?". search_knowledge_base restituisce l'ID dell'articolo e la data dell'ultimo aggiornamento, quindi la fonte è facile da verificare. Come osFoundry le organizza è spiegato nella pagina delle knowledge base.