Cara membuat Codex CLI membaca catatan dan knowledge base osFoundry lewat MCP

Di akhir panduan ini, Codex CLI bisa membuka Note spesifikasi, knowledge base tim support, dan Record bug di salah satu proyek osFoundry Anda sambil bekerja di repositori Anda. Codex membacanya lewat server MCP osFoundry, meminta izin Anda sebelum melakukan apa pun yang menulis, dan setiap panggilan yang dibuatnya tercatat di osFoundry pada Recent activity (aktivitas terbaru) koneksi tersebut. Pengaturannya cukup satu tabel di ~/.codex/config.toml, satu kali login di browser, dan satu klik untuk menambahkan koneksi ke proyek.

Siapa mengerjakan apa

Pengaturan

1. Buat koneksi di osFoundry

Klik ikon kunci di header osFoundry dan buka tab Connected ("Connected agents", dengan nama workspace saat ini di bawahnya). Di formulir di bawah "Connect in three steps":

• Assistant: Other MCP client
• Display name: nama yang mudah Anda kenali, misalnya Codex CLI
• Klik Add assistant (tambah asisten)

Koneksi muncul dengan status "Setup pending. This assistant cannot read or change anything yet." Salin Server address:

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

Contoh: Tab Connected dengan koneksi Codex CLI terpilih

2. Tambahkan server ke Codex

Perintah satu baris dari dokumentasi MCP Codex milik OpenAI:

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

Perintah itu menulis tabel [mcp_servers.osfoundry]. Buka ~/.codex/config.toml dan perketat. Semua key di bawah ini ada di dokumentasi tersebut:

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

Fungsi setiap baris:

• scopes menggantikan apa yang ditawarkan server. Tanpa baris ini, Codex mengambil scope dari challenge server atau dari protected-resource metadata-nya, dan metadata osFoundry mencantumkan empat scope, termasuk osfoundry:run. Asisten coding yang hanya membaca dan memperbarui record tidak perlu menjalankan sesi.
• default_tools_approval_mode = "writes" membuat Codex meminta konfirmasi untuk setiap tool yang tidak ditandai read-only. osFoundry menandai tool-nya dengan readOnlyHint, jadi sembilan tool baca berjalan tanpa prompt dan edit_record_item bertanya lebih dulu.
• enabled_tools menjaga daftar tool tetap pendek. Server menawarkan 59 tool; daftar ini berisi sepuluh. Namanya adalah nama tool MCP mentah, tanpa prefiks. Salah ketik nama tidak menimbulkan error. Tool-nya hanya tidak ada.

Kalau server hanya boleh berlaku di satu repositori, taruh tabel yang sama di .codex/config.toml milik repositori itu. Codex hanya membaca konfigurasi proyek untuk proyek yang sudah Anda tandai sebagai tepercaya (trusted).

3. Login

codex mcp login osfoundry 

Browser membuka https://osfoundry.io/external-assistant-authorize dengan judul "Connect an agent". Halaman itu menampilkan Assistant client dan "Returns to", yaitu alamat lokal karena Codex menangkap callback di mesin Anda. Lalu:

• Workspace to connect: pilih satu. Workspace kedua perlu koneksi sendiri.
• Requested capabilities: dengan scopes di atas, Anda akan melihat dua baris, "Read supported resources in projects you add" dan "Change supported resources where you have edit access".
• Connection: pilih "Use pending: Codex CLI" supaya login terhubung ke koneksi dari langkah 1.
• Centang "I approve connecting this assistant to " lalu klik Connect.

Di mesin remote lewat SSH, codex mcp login osfoundry --no-browser akan mencetak URL-nya. Buka URL itu di laptop Anda, lalu tempel URL redirect lengkapnya kembali ke terminal.

Server osFoundry punya endpoint registrasi dan menerima public client, jadi Codex mendaftarkan dirinya sendiri. Anda tidak perlu menempel client ID.

4. Tambahkan koneksi ke proyek

Kembali ke ikon kunci → Connected, koneksi sekarang bertuliskan "Connected." Di bagian Projects, pilih proyeknya lalu klik Add to project (tambah ke proyek). Ini membuka Note yang tersinkron di proyek itu, knowledge base, channel Record, Room cloud, repositori GitNest yang ditetapkan, dan channel diskusinya, termasuk apa pun yang ditambahkan nanti. Channel Message lain perlu di-Invite (undang) satu per satu.

Bagian Tools dimulai dengan "All supported tools are on by default." Hapus centang pada apa pun yang tidak boleh pernah dipanggil koneksi ini, bahkan jika nanti ada yang mengedit config.toml, lalu klik Save tools (simpan tool).

Contoh: Checklist Tools dengan hanya tool baca yang dicentang, lalu Save tools

5. Periksa dari Codex

Di TUI codex, /mcp menampilkan daftar server yang aktif. osfoundry seharusnya ada di sana. Setelah itu, minta saja dengan kalimat biasa.

Contoh jalannya

Codex tidak terpasang di mesin tempat tulisan ini dibuat, jadi sesi di bawah ini adalah contoh simulasi. Nama tool-nya adalah yang dikembalikan server live dari tools/list. Kode sumber Codex menambahkan prefiks mcp__<server>__ pada tool MCP di nama yang dilihat model, karena itu tampilannya seperti ini. Prompt, proyek, dan jawabannya adalah konten demo.

Contoh (simulasi) > Test yang gagal di tests/test_refund.py mengharapkan jangka waktu 14 hari. Cek spesifikasi di osFoundry dan KB support sebelum mengubah apa pun. • mcp__osfoundry__list_granted_resources {} ← 1 proyek: "Billing v2" • mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "note", "search": "refund"} ← Note "Aturan refund (spesifikasi)" • mcp__osfoundry__list_note_tabs {"note_id": "…"} ← tab: Note (teks), Sheet "Kasus khusus" • mcp__osfoundry__read_note_tab {"note_id": "…", "tab_id": "…"} ← "Refund diterima dalam 30 hari sejak tanggal invoice…" • mcp__osfoundry__search_knowledge_base {"knowledge_base_id": "…", "query": "batas waktu refund"} ← artikel "Kebijakan refund", diperbarui 2 hari lalu: 30 hari • 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 bertanya: izinkan panggilan tool ini? → ya] ← saved Yang salah adalah test-nya, bukan kodenya. Note spesifikasi dan artikel KB sama-sama menyebut 30 hari. Saya mengubah test dan komentar konstantanya, menjalankan pytest (12 lulus), dan mengubah record "Batas waktu refund meleset 16 hari" menjadi Fixed. 

edit_record_item membawa versi yang dikembalikan read_record_item atau list_record_items, sehingga record yang sudah diubah orang lain di antara waktu itu akan ditolak alih-alih ditimpa. idempotency_key yang diulang mengembalikan hasil pertama, sehingga panggilan yang dicoba ulang tidak menulis dua kali. Prompt persetujuan di tengah berasal dari Codex, bukan osFoundry, karena default_tools_approval_mode = "writes".

Di mana batasnya

Codex membaca osFoundry, osFoundry tidak membaca Codex. Koneksi ini memungkinkan Codex memanggil tool ketika ia memutuskan untuk melakukannya. osFoundry mencatat setiap panggilan di Recent activity beserta nama tool, keputusan akses, dan waktunya, tetapi tidak bisa membuka sesi Codex, repositori, atau terminal Anda. Kode sumber Anda tidak pergi ke mana pun kecuali Codex memasukkannya ke argumen tool, misalnya komentar pada record.

Dua filter punya tugas yang berbeda. enabled_tools di config.toml menentukan apa yang ditawarkan ke model, sehingga prompt tetap pendek dan pilihannya jelas. Checklist Tools di osFoundry adalah sakelar milik pemilik, dan tetap berlaku apa pun isi file lokal. Tidak satu pun dari keduanya memberi akses ke apa pun. Itu ditentukan oleh keanggotaan proyek.

Akses diputuskan per panggilan. Setiap panggilan diperiksa terhadap status koneksi, workspace-nya, keanggotaan proyek saat ini, proyek tempat item itu berada sekarang, dan peran Anda sendiri di dalamnya. Pindahkan Note ke proyek lain, hapus proyeknya, atau klik Revoke connection (cabut koneksi), maka panggilan Codex berikutnya akan ditolak walaupun token-nya belum kedaluwarsa.

Sebagian penulisan berupa usulan. Pekerjaan GitNest, change set, impor file, dan pull request melewati tool propose_… dan menunggu di tab Connected di bawah "Needs your approval", lengkap dengan target dan daftar file, sampai Anda mengklik Approve atau Decline. Codex tidak pernah menerima token penyedia Git Anda. Contoh konfigurasi di atas memang tidak menyertakan tool-tool itu, karena Codex sudah punya checkout lokal Anda.

Data yang hanya lokal tetap lokal. Balasan initialize dari server menyebutkannya: "Local-only data is unavailable to cloud clients." Room lokal, sesi Graph lokal, dan apa pun yang belum tersinkron tidak terlihat lewat koneksi ini.

Selanjutnya

Arahkan Codex ke knowledge base yang sudah Anda pakai untuk menjawab pertanyaan, lalu minta ia mencocokkan docstring atau pesan error dengannya, misalnya "Apakah kalimat di KB untuk error ini sama dengan yang dicetak kode?". search_knowledge_base mengembalikan ID artikel dan kapan terakhir diperbarui, jadi sumbernya mudah diverifikasi. Cara osFoundry mengatur knowledge base ada di halaman knowledge base.