Model Context Protocol

Aplikasi desktop ChatGPT, Codex CLI, dan ekstensi IDE mendukung MCP server serta berbagi konfigurasi MCP untuk host Codex yang sama.

Fitur server yang didukung di bawah ini berlaku untuk MCP server yang dikonfigurasi pada host Codex. Alat plugin yang dihosting dapat memiliki kemampuan berbeda.

Fitur MCP yang didukung

• Server STDIO: Server yang berjalan sebagai proses lokal (dimulai oleh perintah).
  • Variabel lingkungan
• Streamable HTTP server: Server yang Anda akses melalui suatu alamat.
  • Autentikasi token Bearer
  • Autentikasi OAuth, termasuk Client ID Metadata Documents (CIMD) dan Dynamic Client Registration (DCR)
  • Autentikasi sesi ChatGPT untuk server pihak pertama tepercaya
• Instruksi server: Codex membaca bidang MCP instructions yang dikembalikan selama inisialisasi dan menggunakannya sebagai panduan untuk seluruh server bersama alat-alat server tersebut.

Jika Anda membangun atau memelihara MCP server untuk Codex, gunakan instructions untuk alur kerja lintas alat, batasan, dan batas laju yang berlaku di seluruh server. Pastikan 512 karakter pertama dapat dipahami secara mandiri agar panduan terpenting tersedia saat Codex memutuskan cara menggunakan server.

Menghubungkan Codex ke MCP server

Codex menyimpan konfigurasi MCP di config.toml bersama pengaturan konfigurasi Codex lainnya. Secara default, lokasinya adalah ~/.codex/config.toml, tetapi Anda juga dapat membatasi cakupan MCP server ke suatu proyek dengan .codex/config.toml (hanya proyek tepercaya).

Aplikasi desktop ChatGPT, Codex CLI, dan ekstensi IDE berbagi konfigurasi ini. Setelah mengonfigurasi MCP server, Anda dapat beralih di antara klien tersebut tanpa mengulangi penyiapan.

Mengonfigurasi di aplikasi desktop ChatGPT

1. Buka Pengaturan, lalu pilih MCP server.
2. Pilih Tambahkan server.
3. Masukkan nama, pilih STDIO atau Streamable HTTP, lalu berikan perintah atau URL server.
4. Simpan server, lalu pilih Mulai ulang.

Daftar server menunjukkan server mana yang diaktifkan dan mana yang memerlukan OAuth. Pilih Autentikasi ketika server OAuth mengharuskan Anda masuk. Di kotak penulisan, ketik /mcp untuk melihat server yang terhubung.

Gunakan alat berbasis MCP di ChatGPT web

Melanjutkan percakapan menggunakan akses komputer lokal dengan Work Cloud di perangkat lain tidak akan menginstal plugin atau memberikan akses ke akun yang terhubung.

Dalam akses komputer lokal dengan Work Cloud, persyaratan TOML mcp_servers untuk perusahaan di Agent Security berlaku bagi eksekutor lokal. Kontainer cloud tetap mengikuti kebijakan Work Cloud. Server dan transport MCP lokal mungkin tidak tersedia di cloud; periksa konektivitas dan autentikasi secara terpisah.

Untuk hook perusahaan dalam akses komputer lokal dengan Work Cloud:

• Hook perusahaan. Jika diaktifkan untuk ruang kerja Anda, akses komputer lokal dengan Work Cloud mendukung hook MCP yang ditentukan admin dan berjalan pada koordinator cloud (orkestrator) untuk peristiwa siklus hidup dan alat yang didukung. Hook perintah serta hook dari konfigurasi lokal atau plugin tidak didukung dengan orkestrasi cloud, meskipun alat dijalankan secara lokal.
• Audit. Sebelum mengandalkan hook ini, uji koneksi callback, pastikan peristiwa yang diterimanya, dan periksa bagaimana kegagalan memengaruhi tugas. Hook MCP tidak menyediakan jejak audit Compliance API yang lengkap.
• Batasan: Hook perintah serta hook dari konfigurasi lokal atau plugin tidak didukung dengan orkestrasi cloud, meskipun alat dijalankan secara lokal. Pengguna konsumen tidak mendapatkan dukungan hook dalam fitur ini. Jika orkestrasi dan eksekusi sama-sama dilakukan secara lokal, hook yang sudah didukung tetap berfungsi dalam utas Work dan Codex yang sepenuhnya lokal. Admin tetap dapat mengonfigurasi hook terkelola yang didukung di Agent Security untuk alur kerja tersebut.

Lihat Hook dan Referensi Konfigurasi untuk mengetahui cakupan dukungan.

Dalam percakapan ChatGPT Work yang dihosting, instal plugin untuk menggunakan konektor bawaan dan alat MCP jarak jauhnya. Setelah penginstalan, Chat dan Work dapat menggunakan alat tersebut. Administrator ruang kerja dapat mengendalikan plugin dan alat yang tersedia.

ChatGPT web tidak membaca file konfigurasi Codex lokal atau menampilkan menu perintah Codex lokal. Buka tab Plugins untuk menelusuri dan mengelola alat yang tersedia.

Konfigurasikan dengan CLI

Tambahkan MCP server

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

Sebagai contoh, untuk menambahkan Context7 (MCP server gratis untuk dokumentasi pengembang), Anda dapat menjalankan perintah berikut:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Perintah CLI lainnya

Jalankan codex mcp list untuk melihat server yang telah dikonfigurasi. Untuk melihat semua perintah MCP yang tersedia, jalankan codex mcp --help. Untuk server yang mendukung OAuth, jalankan codex mcp login <server-name>.

Antarmuka pengguna terminal (TUI)

Di TUI codex, gunakan /mcp untuk melihat MCP server aktif Anda.

Konfigurasikan di ekstensi IDE

1. Buka menu roda gigi, lalu pilih MCP server.
2. Pilih Tambahkan server.
3. Masukkan nama, pilih STDIO atau Streamable HTTP, lalu berikan perintah atau URL server.
4. Simpan server, lalu pilih Mulai ulang ekstensi.

Daftar MCP server menunjukkan server mana yang diaktifkan dan mana yang memerlukan OAuth. Pilih Autentikasi ketika server OAuth mengharuskan Anda masuk.

Mengonfigurasi dengan config.toml

Untuk kontrol yang lebih terperinci, edit ~/.codex/config.toml atau .codex/config.toml yang cakupannya dibatasi ke proyek. Lihat referensi konfigurasi untuk daftar yang dapat ditelusuri berisi setiap opsi MCP yang didukung.

Konfigurasikan setiap MCP server dengan tabel [mcp_servers.<server-name>] dalam berkas konfigurasi.

Server STDIO

• command (wajib): Perintah yang memulai server.
• args (opsional): Argumen yang diteruskan ke server.
• env (opsional): Variabel lingkungan yang ditetapkan untuk server.
• env_vars (opsional): Variabel lingkungan yang diizinkan dan diteruskan.
• cwd (opsional): Direktori kerja tempat server dimulai.
• experimental_environment (opsional): Atur ke remote untuk memulai server stdio melalui lingkungan eksekutor jarak jauh jika tersedia.

env_vars dapat memuat nama variabel biasa atau objek dengan sumber:

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

Entri string dan source = "local" dibaca dari lingkungan lokal Codex. source = "remote" dibaca dari lingkungan eksekutor jarak jauh dan memerlukan stdio MCP jarak jauh.

Server Streamable HTTP

• url (wajib): Alamat server.
• auth (opsional): Autentikasi yang dicoba setelah token bearer dan header otorisasi yang dikonfigurasi. Gunakan oauth (default) untuk kredensial OAuth MCP yang tersimpan. Gunakan chatgpt untuk memakai sesi ChatGPT saat ini bagi origin ChatGPT pihak pertama yang tepercaya, dengan OAuth tersimpan sebagai cadangan.
• bearer_token_env_var (opsional): Nama variabel lingkungan untuk token bearer yang akan dikirim dalam Authorization.
• http_headers (opsional): Pemetaan nama header ke nilai statis.
• env_http_headers (opsional): Pemetaan nama header ke nama variabel lingkungan (nilai diambil dari lingkungan).
• http_headers_helper (opsional): Perintah helper lokal yang mencetak objek JSON berisi nama header dan nilai string, seperti {"X-Auth": "temporary-token"}. Didukung untuk koneksi HTTP MCP yang dibuat dari lingkungan lokal; tidak untuk server stdio atau koneksi yang dibuat melalui lingkungan eksekusi jarak jauh.

Codex menyimpan header dari helper dalam cache untuk koneksi tersebut. Setelah POST ke origin yang sama mengembalikan 401 atau 403, Codex memperbarui header satu kali dan mencoba kembali hanya jika helper mengembalikan nilai yang berubah. Token bearer eksplisit dan kredensial OAuth lebih diprioritaskan daripada header Authorization yang diberikan oleh helper. Respons OAuth 403 yang melaporkan cakupan tidak memadai tidak memicu pembaruan helper.

Jika tidak ada sumber kredensial yang dapat ditentukan, Codex dapat terhubung ke server tanpa autentikasi. Jalankan codex mcp login <server-name> secara terpisah untuk memulai proses masuk OAuth MCP.

Opsi konfigurasi lainnya

• startup_timeout_sec (opsional): Batas waktu (detik) untuk memulai server. Default: 10.
• tool_timeout_sec (opsional): Batas waktu (detik) bagi server untuk menjalankan alat. Default: 60.
• enabled (opsional): Atur false untuk menonaktifkan server tanpa menghapusnya.
• required (opsional): Atur true agar proses awal gagal jika server aktif ini tidak dapat diinisialisasi.
• enabled_tools (opsional): Daftar alat yang diizinkan.
• disabled_tools (opsional): Daftar alat yang ditolak (diterapkan setelah enabled_tools).
• default_tools_approval_mode (opsional): Perilaku persetujuan default untuk alat dari server ini. Nilai yang didukung adalah auto, prompt, writes, dan approve. Mode writes meminta persetujuan untuk alat yang tidak ditandai hanya-baca.
• tools.<tool>.approval_mode (opsional): Penggantian perilaku persetujuan per alat.
• tools.<tool>.output_token_limit (opsional): Anggaran token positif untuk output satu alat, sebelum alokasi serialisasi standar sebesar 20%. Menggantikan anggaran pemotongan output default model untuk alat tersebut.

Pengaturan tingkat teratas mcp_optional_startup_grace_ms mengontrol berapa lama Codex menunggu MCP server opsional saat menyusun katalog alat awal. Nilai default-nya adalah 1000 milidetik. Tetapkan ke 0 untuk menunggu startup_timeout_sec setiap server sebagai gantinya. Server wajib tetap menggunakan batas waktu mulainya masing-masing.

Pendaftaran klien OAuth dan callback

Jika server otorisasi Anda memerlukan klien OAuth yang telah didaftarkan sebelumnya, berikan ID kliennya saat menambahkan MCP server:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

Untuk klien konfidensial, sertakan juga --oauth-client-secret. Baca rahasia tersebut dari variabel lingkungan:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

Opsi ini memerlukan ID klien dan rahasia yang tidak kosong. Codex menyimpan rahasia tersebut sebagai mcp_servers.example.oauth.client_secret di config.toml. Jaga kerahasiaan file tersebut dan jangan sertakan dalam kontrol versi.

Codex menampilkan URL callback lengkap untuk didaftarkan ke penyedia Anda:

OAuth callback URL: http://127.0.0.1/callback

Codex menyimpan callback bersama ID klien di config.toml untuk proses login berikutnya:

[mcp_servers.example]
url = "https://mcp.example.com"

[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"

Klien pradaftar yang baru ditambahkan hanya menggunakan callback stabil jika server otorisasi mengumumkan authorization_response_iss_parameter_supported: true dan menyediakan metadata issuer. Jika dukungan penerbit tidak diumumkan, Codex menambahkan ID callback khusus server, seperti http://127.0.0.1/callback/XuuuHAzzHOni. Klien yang sudah ada tanpa callback tersimpan tetap menggunakan pengalihan khusus ID callback mereka.

Saat login, pemilihan callback bergantung pada konfigurasi OAuth dan metadata server otorisasi:

Mekanisme fallback tidak mengubah URL callback yang tersimpan. Codex memperoleh ID callback dari URL MCP server, termasuk jalur dan string kuerinya. Aturan pemilihan yang sama berlaku untuk login otomatis maupun eksplisit.

Tetapkan mcp_oauth_callback_url saat Anda memerlukan jalur callback khusus atau URL ingress Devbox jarak jauh. Klien pradaftar yang baru ditambahkan menggunakan URL tersebut tanpa perubahan jika penyedianya mendukung identifikasi penerbit. Jika tidak, klien menggunakan URL yang dikonfigurasi dengan tambahan ID callback khusus server. Selalu daftarkan callback persis seperti yang ditampilkan oleh codex mcp add.

Untuk callback http://127.0.0.1 tanpa port eksplisit, Codex menghilangkan port listener dari URL yang ditampilkan dan disimpannya, lalu menyisipkan port listener yang aktif saat otorisasi. Penggantian ini tidak berlaku untuk localhost, host IPv6, URL HTTPS, atau callback yang sudah menyertakan port. Server otorisasi harus menerima port loopback yang bervariasi sesuai RFC 8252, Bagian 7.3.

Atur mcp_oauth_callback_port untuk memilih port listener global yang tetap, atau atur mcp_servers.<server-name>.oauth.callback_port untuk menggantinya bagi satu server. Port eksplisit dalam URL callback tidak mengonfigurasi listener. Untuk callback loopback langsung, gunakan http://127.0.0.1 tanpa port eksplisit atau konfigurasikan port eksplisit yang sama untuk URL callback dan listener. Callback melalui proksi dapat sengaja menggunakan port URL eksternal yang berbeda dari port listener lokal. URL callback lokal terikat ke antarmuka lokal; URL callback nonlokal terikat ke 0.0.0.0.

Codex memvalidasi setiap iss yang dikembalikan sebelum menukarkan kode otorisasi. Respons selalu ditolak jika iss tidak cocok. Jika dukungan penerbit diumumkan, respons juga ditolak jika iss tidak ada. Kedua kegagalan tersebut tidak menukarkan kode atau beralih ke callback lain. URL callback yang tidak valid atau dukungan penerbit yang diumumkan tanpa penerbit dalam metadata juga tetap merupakan kegagalan fatal. Lihat Autentikasi pengguna.

Atur mcp_servers.<server-name>.scopes di config.toml untuk memilih cakupan OAuth bagi suatu server. Untuk menggantinya pada satu kali login, jalankan codex mcp login <name> --scopes read,write. Jika keduanya tidak diatur, Codex menggunakan cakupan OAuth yang diumumkan jika tersedia.

Daftar kosong (scopes = []) tetap memungkinkan pustaka OAuth memilih cakupan. Pustaka tersebut juga dapat menambahkan offline_access jika server otorisasi mendukungnya.

Pendaftaran klien OAuth

Codex mendukung OAuth Client ID Metadata Documents (CIMD) dan Dynamic Client Registration (DCR). Secara default, Codex secara otomatis memilih CIMD saat server otorisasi mengiklankan client_id_metadata_document_supported: true, menyertakan none dalam token_endpoint_auth_methods_supported, dan callback menggunakan URL loopback yang didukung. Jika tidak, Codex menggunakan DCR jika tersedia. ID klien OAuth yang dikonfigurasi selalu lebih diprioritaskan dan melewati pendaftaran klien.

Untuk CIMD tanpa respons yang terikat pada penerbit, Codex CLI menggunakan dokumen metadata yang dihosting ChatGPT dan khusus untuk MCP server tersebut:

https://chatgpt.com/oauth/codex/<callback_id>/client.json

Codex memperoleh <callback_id> dari URL MCP server dan menyertakannya dalam URI pengalihan loopback, seperti http://127.0.0.1:<port>/callback/<callback_id>. Dokumen metadata mendaftarkan URI loopback yang sesuai tanpa port. Server otorisasi harus menerima port yang dipilih saat login sekaligus mencocokkan host dan jalur secara persis, sebagaimana diwajibkan oleh RFC 8252. Host, jalur, atau parameter kueri callback khusus memerlukan DCR atau ID klien OAuth yang dikonfigurasi.

Codex CLI juga mendukung dokumen CIMD bersama yang stabil:

https://chatgpt.com/oauth/codex/client.json

Codex CLI menggunakan dokumen yang stabil dengan jalur bersama /callback ketika server otorisasi mengumumkan authorization_response_iss_parameter_supported: true, menyediakan issuer yang valid dalam metadatanya, dan menyertakan iss yang sesuai dalam respons otorisasi. Server tanpa respons yang terikat pada penerbit menggunakan dokumen khusus callback.

Untuk memilih metode pendaftaran bagi satu kali login CLI, gunakan --oauth-client-registration:

codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcr

Nilai default-nya adalah auto. Pilihan pendaftaran hanya berlaku untuk login saat ini dan tidak disimpan dalam config.toml.

Contoh config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

MCP server yang disediakan plugin

Plugin yang terinstal dapat menyertakan MCP server dalam manifes pluginnya. Server tersebut dijalankan dari plugin, sehingga konfigurasi pengguna tidak menetapkan perintah transportasinya. Konfigurasi pengguna tetap dapat mengendalikan status aktif/nonaktif dan kebijakan alat di bawah plugins.<plugin>.mcp_servers.<server>.

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

HTTP MCP server yang disediakan plugin juga dapat mendeklarasikan pengaturan OAuth di .mcp.json. Manifes plugin menggunakan nama bidang camelCase clientId, callbackUrl, dan callbackPort:

{
  "mcpServers": {
    "sample": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "my-pre-registered-client",
        "callbackUrl": "http://127.0.0.1/callback/registered"
      }
    }
  }
}

MCP server yang disediakan plugin mengikuti aturan pemilihan callback yang sama seperti MCP server lainnya. Jika plugin menyediakan clientId, penyedianya tidak mendukung callback yang terikat pada penerbit, dan callbackUrl tidak memuat ID callback khusus server, Codex mengabaikan URL tersebut untuk login dan menggunakan mcp_oauth_callback_url, atau http://127.0.0.1/callback jika tidak ditetapkan, dengan tambahan ID callback. Nilai callbackUrl yang dikonfigurasi tetap tidak berubah.

oauth.callbackPort milik plugin menggantikan mcp_oauth_callback_port global; jika keduanya tidak ditetapkan, Codex memilih port sementara. Port yang disematkan dalam callbackUrl tidak menentukan port listener. Untuk callback loopback langsung dengan port tetap, konfigurasikan kedua nilai agar sama:

{
  "callbackUrl": "http://127.0.0.1:4321/callback/registered",
  "callbackPort": 4321
}

Untuk ingress jarak jauh atau proksi lain, port URL callback dan port listener lokal dapat sengaja dibuat berbeda ketika proksi meneruskan permintaan ke listener yang dikonfigurasi.

Contoh MCP server yang bermanfaat

Daftar MCP server terus bertambah. Berikut beberapa yang umum:

• OpenAI Docs MCP: Menelusuri dan membaca dokumentasi pengembang OpenAI.
• Context7: Terhubung ke dokumentasi pengembang terkini.
• Figma Lokal dan Jarak Jauh: Mengakses desain Figma Anda.
• Playwright: Mengendalikan dan memeriksa browser menggunakan Playwright.
• Chrome Developer Tools: Mengendalikan dan memeriksa Chrome.
• Sentry: Mengakses log Sentry.
• GitHub: Mengelola GitHub melampaui dukungan git (misalnya, pull request dan isu).