MCP | Perluas ChatGPT dan Codex | Dokumentasi ChatGPT

Model Context Protocol (MCP) menghubungkan model dengan alat dan konteks. Gunakan protokol ini untuk memberikan akses kepada ChatGPT atau Codex ke dokumentasi pihak ketiga, atau agar keduanya dapat berinteraksi dengan alat pengembang seperti browser Anda atau Figma.

ChatGPT web dapat menggunakan alat jarak jauh berbasis MCP yang disediakan oleh plugin. Setelah plugin diinstal, Chat dan Work dapat menggunakan konektor serta alat MCP jarak jauh yang disertakan. Buka tab Plugins untuk menelusuri dan mengelola alat yang tersedia. Klien Codex lokal juga dapat terhubung langsung ke server MCP dan berbagi konfigurasinya.

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

Fitur server yang didukung di bawah ini berlaku untuk server MCP 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
Server HTTP yang dapat dialirkan: 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 server MCP 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 server MCP

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 server MCP ke suatu proyek dengan .codex/config.toml (hanya proyek tepercaya).

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

Mengonfigurasi di aplikasi desktop ChatGPT

Buka Pengaturan, lalu pilih Server MCP.
Pilih Tambahkan server.
Masukkan nama, pilih STDIO atau Streamable HTTP, lalu berikan perintah atau URL server.
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.

Konfigurasikan dengan CLI

Tambahkan server MCP

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

Sebagai contoh, untuk menambahkan Context7 (server MCP 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 server MCP aktif Anda.

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 server MCP 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 server MCP 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 server MCP:

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

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:

Konfigurasi OAuth	Dukungan penerbit	Callback yang digunakan
`callback_url` tanpa `client_id`	Didukung	Callback yang dikonfigurasi digunakan untuk pendaftaran klien.
`callback_url` tanpa `client_id`	Tidak didukung	Callback yang dikonfigurasi digunakan untuk pendaftaran klien dengan tambahan ID callback khusus server.
`client_id` dan `callback_url`	Didukung	Callback yang dikonfigurasi digunakan kembali; respons otorisasi harus memuat `iss` yang cocok.
`client_id` dan `callback_url` yang diakhiri dengan ID callback yang benar	Tidak didukung	Callback yang dikonfigurasi digunakan kembali tanpa perubahan.
`client_id` dan `callback_url` yang tidak memuat ID callback yang benar	Tidak didukung	Callback yang dikonfigurasi diabaikan. Codex menggunakan `mcp_oauth_callback_url`, atau `http://127.0.0.1/callback` jika tidak ditetapkan, dengan tambahan ID callback.
`client_id` tanpa `callback_url` yang dikonfigurasi	Didukung atau tidak didukung	Codex menggunakan callback global atau default dengan tambahan ID callback khusus server.

Mekanisme fallback tidak mengubah URL callback yang tersimpan. Codex memperoleh ID callback dari URL server MCP, 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, Codex menghilangkan port listener dari URL yang ditampilkan dan disimpannya, lalu menyisipkan port listener aktif selama otorisasi. Substitusi ini tidak berlaku untuk localhost, host IPv6, URL HTTPS, atau callback yang sudah menyertakan port. Server otorisasi harus menerima port loopback variabel berdasarkan RFC 8252, Bagian 7.3.

Tetapkan mcp_oauth_callback_port untuk memilih port listener global tetap, atau tetapkan 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 atau konfigurasikan port eksplisit yang sama untuk URL callback dan listener. Callback melalui proksi dapat secara sengaja menggunakan port URL eksternal yang berbeda dari port listener lokal. URL callback lokal diikat ke antarmuka lokal; URL callback nonlokal diikat 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.

Jika server MCP mengiklankan scopes_supported, Codex memprioritaskan cakupan yang diiklankan server tersebut selama proses masuk OAuth. Jika tidak, Codex menggunakan cakupan yang dikonfigurasi dalam config.toml.

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, Codex menggunakan dokumen metadata yang dihosting oleh ChatGPT dan khusus untuk server MCP tersebut:

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

Codex memperoleh <callback_id> dari URL server MCP 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.

Dukungan untuk dokumen CIMD bersama yang stabil sedang dikembangkan dan akan segera tersedia:

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

Codex akan menggunakan dokumen stabil dengan jalur /callback bersama ketika server otorisasi mengiklankan authorization_response_iss_parameter_supported: true, menyediakan issuer yang valid dalam metadatanya, dan menyertakan iss yang cocok dalam respons otorisasi. Server tanpa respons yang terikat pada penerbit akan tetap 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

Server MCP yang disediakan plugin

Plugin yang terinstal dapat menyertakan server MCP 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"

Server HTTP MCP 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"
      }
    }
  }
}

Server MCP yang disediakan plugin mengikuti aturan pemilihan callback yang sama seperti server MCP 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 server MCP yang bermanfaat

Daftar server MCP 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).

Pencarian terbaru

Pencarian yang disarankan

Navigasi dokumentasi

Model Context Protocol