Model Context Protocol

ChatGPT masaüstü uygulaması, Codex CLI ve IDE uzantısı MCP sunucularını destekler ve aynı Codex ana makinesi için MCP yapılandırmasını paylaşır.

Aşağıda belirtilen desteklenen sunucu özellikleri, bir Codex ana makinesinde yapılandırılmış MCP sunucuları için geçerlidir. Barındırılan eklenti araçlarının yetenekleri farklı olabilir.

Desteklenen MCP özellikleri

• STDIO sunucuları: Yerel bir işlem olarak çalışan (bir komutla başlatılan) sunucular.
  • Ortam değişkenleri
• Akış destekli HTTP sunucuları: Bir adres üzerinden eriştiğiniz sunucular.
  • Bearer belirteciyle kimlik doğrulama
  • Client ID Metadata Documents (CIMD) ve Dynamic Client Registration (DCR) dâhil OAuth kimlik doğrulaması
  • Güvenilir birinci taraf sunucular için ChatGPT oturumuyla kimlik doğrulama
• Sunucu talimatları: Codex, başlatma sırasında döndürülen MCP instructions alanını okur ve sunucunun araçlarının yanı sıra sunucu genelinde geçerli yönlendirme olarak kullanır.

Codex için bir MCP sunucusu geliştiriyor veya bakımını yapıyorsanız sunucu genelinde geçerli olan araçlar arası iş akışları, kısıtlamalar ve hız sınırları için instructions kullanın. Codex sunucuyu nasıl kullanacağına karar verirken en önemli yönlendirmenin erişilebilir olması için ilk 512 karakteri kendi başına anlaşılır tutun.

Codex'i bir MCP sunucusuna bağlama

Codex, MCP yapılandırmasını diğer Codex yapılandırma ayarlarıyla birlikte config.toml içinde saklar. Varsayılan olarak bu konum ~/.codex/config.toml şeklindedir; ancak MCP sunucularını .codex/config.toml ile bir proje kapsamında da yapılandırabilirsiniz (yalnızca güvenilir projeler).

ChatGPT masaüstü uygulaması, Codex CLI ve IDE uzantısı bu yapılandırmayı paylaşır. MCP sunucularınızı yapılandırdıktan sonra kurulumu yeniden yapmadan bu istemciler arasında geçiş yapabilirsiniz.

ChatGPT masaüstü uygulamasında yapılandırma

1. Settings'i açın, ardından MCP servers'ı seçin.
2. Add server'ı seçin.
3. Bir ad girin, STDIO veya Streamable HTTP seçeneğini belirleyin ve sunucunun komutunu veya URL'sini sağlayın.
4. Sunucuyu kaydedin, ardından Restart'ı seçin.

Sunucu listesi, hangi sunucuların etkin olduğunu ve hangilerinin OAuth gerektirdiğini gösterir. Bir OAuth sunucusu oturum açılmasını gerektirdiğinde Authenticate'i seçin. Bağlı sunucuları görüntülemek için oluşturucuya /mcp yazın.

ChatGPT web'de MCP destekli araçları kullanma

Barındırılan bir ChatGPT Work sohbetinde, eklentiyle birlikte gelen bağlayıcıları ve uzak MCP araçlarını kullanmak için bir eklenti yükleyin. Yüklemeden sonra Chat ve Work bu araçları kullanabilir. Çalışma alanı yöneticileri hangi eklenti ve araçların kullanılabilir olduğunu denetleyebilir.

ChatGPT web, yerel Codex yapılandırma dosyalarını okumaz veya yerel Codex komut menüsünü sunmaz. Kullanılabilir araçlara göz atmak ve bunları yönetmek için Plugins sekmesini açın.

CLI ile yapılandırma

MCP sunucusu ekleme

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

Örneğin, geliştirici belgeleri için ücretsiz bir MCP sunucusu olan Context7'yi eklemek üzere aşağıdaki komutu çalıştırabilirsiniz:

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

Diğer CLI komutları

Yapılandırılmış sunucuları görmek için codex mcp list komutunu çalıştırın. Kullanılabilir tüm MCP komutlarını görmek için codex mcp --help komutunu çalıştırın. OAuth'ı destekleyen bir sunucu için codex mcp login <server-name> komutunu çalıştırın.

Terminal kullanıcı arayüzü (TUI)

codex TUI'da etkin MCP sunucularınızı görmek için /mcp kullanın.

IDE uzantısında yapılandırma

1. Dişli menüsünü açın, ardından MCP servers'ı seçin.
2. Add server'ı seçin.
3. Bir ad girin, STDIO veya Streamable HTTP seçeneğini belirleyin ve sunucunun komutunu veya URL'sini sağlayın.
4. Sunucuyu kaydedin, ardından Restart extension'ı seçin.

MCP sunucu listesi, hangi sunucuların etkin olduğunu ve hangilerinin OAuth gerektirdiğini gösterir. Bir OAuth sunucusu oturum açılmasını gerektirdiğinde Authenticate'i seçin.

config.toml ile yapılandırma

Daha ayrıntılı denetim için ~/.codex/config.toml dosyasını veya proje kapsamındaki .codex/config.toml dosyasını düzenleyin. Desteklenen tüm MCP seçeneklerinin aranabilir bir listesi için yapılandırma başvurusuna bakın.

Her MCP sunucusunu yapılandırma dosyasında bir [mcp_servers.<server-name>] tablosuyla yapılandırın.

STDIO sunucuları

• command (zorunlu): Sunucuyu başlatan komut.
• args (isteğe bağlı): Sunucuya geçirilecek bağımsız değişkenler.
• env (isteğe bağlı): Sunucu için ayarlanacak ortam değişkenleri.
• env_vars (isteğe bağlı): İzin verilecek ve iletilecek ortam değişkenleri.
• cwd (isteğe bağlı): Sunucunun başlatılacağı çalışma dizini.
• experimental_environment (isteğe bağlı): Kullanılabilir olduğunda stdio sunucusunu uzak bir yürütücü ortamı üzerinden başlatmak için remote olarak ayarlayın.

env_vars, düz değişken adları veya kaynak içeren nesneler barındırabilir:

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

Dize girdileri ve source = "local", Codex'in yerel ortamından okur. source = "remote", uzak yürütücü ortamından okur ve uzak MCP stdio gerektirir.

Akış destekli HTTP sunucuları

• url (zorunlu): Sunucu adresi.
• auth (isteğe bağlı): Yapılandırılmış bearer belirteçleri ve yetkilendirme üstbilgilerinden sonra denenecek kimlik doğrulama yöntemi. Saklanan MCP OAuth kimlik bilgileri için oauth (varsayılan) kullanın. Güvenilir birinci taraf ChatGPT kaynağında mevcut ChatGPT oturumunu kullanmak ve saklanan OAuth'ı yedek olarak tutmak için chatgpt kullanın.
• bearer_token_env_var (isteğe bağlı): Authorization içinde gönderilecek bearer belirtecinin ortam değişkeni adı.
• http_headers (isteğe bağlı): Üstbilgi adlarını statik değerlerle eşleyen harita.
• env_http_headers (isteğe bağlı): Üstbilgi adlarını ortam değişkeni adlarıyla eşleyen harita (değerler ortamdan alınır).
• http_headers_helper (isteğe bağlı): Üstbilgi adları ile dize değerlerinden oluşan bir JSON nesnesi yazdıran yerel komut; örneğin {"X-Auth": "temporary-token"}. Yerel ortamdan kurulan HTTP MCP bağlantıları için desteklenir; stdio sunucuları veya uzak bir yürütme ortamı üzerinden kurulan bağlantılar için desteklenmez.

Codex, yardımcı üstbilgilerini bağlantı için önbelleğe alır. Aynı kaynaklı bir POST isteği 401 veya 403 döndürdükten sonra üstbilgileri bir kez yeniler ve yalnızca yardımcı değişmiş değerler döndürürse yeniden dener. Açıkça belirtilen bearer belirteçleri ve OAuth kimlik bilgileri, yardımcı tarafından sağlanan Authorization üstbilgisine göre önceliklidir. Yetersiz kapsam bildiren bir OAuth 403 yanıtı yardımcı yenilemesini tetiklemez.

Hiçbir kimlik bilgisi kaynağı çözümlenemezse Codex, sunucuya kimlik doğrulaması olmadan bağlanabilir. MCP OAuth oturum açma işlemini başlatmak için codex mcp login <server-name> komutunu ayrıca çalıştırın.

Diğer yapılandırma seçenekleri

• startup_timeout_sec (isteğe bağlı): Sunucunun başlaması için zaman aşımı (saniye). Varsayılan: 10.
• tool_timeout_sec (isteğe bağlı): Sunucunun bir aracı çalıştırması için zaman aşımı (saniye). Varsayılan: 60.
• enabled (isteğe bağlı): Bir sunucuyu silmeden devre dışı bırakmak için false olarak ayarlayın.
• required (isteğe bağlı): Bu etkin sunucu başlatılamazsa başlangıcın başarısız olması için true olarak ayarlayın.
• enabled_tools (isteğe bağlı): Araç izin listesi.
• disabled_tools (isteğe bağlı): Araç engelleme listesi (enabled_tools sonrasında uygulanır).
• default_tools_approval_mode (isteğe bağlı): Bu sunucudaki araçlar için varsayılan onay davranışı. Desteklenen değerler auto, prompt, writes ve approve şeklindedir. writes modu, salt okunur olarak işaretlenmemiş araçlar için onay ister.
• tools.<tool>.approval_mode (isteğe bağlı): Araç başına onay davranışı geçersiz kılma ayarı.
• tools.<tool>.output_token_limit (isteğe bağlı): Standart %20 serileştirme payından önce, tek bir aracın çıktısı için pozitif belirteç bütçesi. Modelin o araca yönelik varsayılan çıktı kısaltma bütçesini geçersiz kılar.

Üst düzey mcp_optional_startup_grace_ms ayarı, Codex'in ilk araç kataloğunu oluştururken isteğe bağlı MCP sunucularını ne kadar bekleyeceğini denetler. Varsayılan değer 1000 milisaniyedir. Her sunucunun startup_timeout_sec değerini beklemek için bunu 0 olarak ayarlayın. Zorunlu sunucular yine kendi başlangıç zaman aşımlarını kullanır.

OAuth istemci kaydı ve geri çağrılar

Yetkilendirme sunucunuz önceden kaydedilmiş bir OAuth istemcisi gerektiriyorsa MCP sunucusunu eklerken istemci kimliğini sağlayın:

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

Codex, sağlayıcınıza kaydetmeniz gereken eksiksiz geri çağrı URL'sini görüntüler:

OAuth callback URL: http://127.0.0.1/callback

Codex, daha sonraki oturum açma işlemleri için geri çağrıyı istemci kimliğiyle birlikte config.toml içinde saklar:

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

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

Yeni eklenen önceden kaydedilmiş istemciler, yalnızca yetkilendirme sunucusu authorization_response_iss_parameter_supported: true desteğini duyurur ve bir meta veri issuer sağlarsa kararlı bir geri çağrı kullanır. Sağlayıcı desteği duyurulmazsa Codex, http://127.0.0.1/callback/XuuuHAzzHOni gibi sunucuya özgü bir geri çağrı kimliği ekler. Kayıtlı bir geri çağrısı olmayan mevcut istemciler, geri çağrı kimliğine özgü yönlendirmelerini kullanmayı sürdürür.

Oturum açma sırasında geri çağrı seçimi, OAuth yapılandırmasına ve yetkilendirme sunucusunun meta verilerine bağlıdır:

Geri dönüş mekanizması, saklanan geri çağrı URL'sini değiştirmez. Codex, geri çağrı kimliğini yolu ve sorgu dizesi dâhil MCP sunucusu URL'sinden türetir. Aynı seçim kuralları otomatik ve açık oturum açma işlemleri için geçerlidir.

Özel bir geri çağrı yoluna veya uzak Devbox giriş URL'sine ihtiyacınız olduğunda mcp_oauth_callback_url ayarını yapın. Yeni eklenen önceden kaydedilmiş istemciler, sağlayıcıları sağlayıcı tanımlamasını destekliyorsa bu URL'yi değiştirmeden kullanır. Aksi takdirde yapılandırılmış URL'yi sunucuya özgü geri çağrı kimliği eklenmiş olarak kullanırlar. Daima codex mcp add tarafından görüntülenen tam geri çağrıyı kaydedin.

Bağlantı noktası içermeyen http://127.0.0.1 geri çağrılarında Codex, dinleyici bağlantı noktasını görüntülediği ve sakladığı URL'den çıkarır, ardından yetkilendirme sırasında etkin dinleyici bağlantı noktasını ekler. Bu değiştirme localhost, IPv6 ana makineleri, HTTPS URL'leri veya zaten bir bağlantı noktası içeren geri çağrılar için geçerli değildir. Yetkilendirme sunucuları, RFC 8252, Bölüm 7.3 uyarınca değişken geri döngü bağlantı noktalarını kabul etmelidir.

Sabit bir genel dinleyici bağlantı noktası seçmek için mcp_oauth_callback_port ayarını yapın veya tek bir sunucu için geçersiz kılmak üzere mcp_servers.<server-name>.oauth.callback_port ayarını yapın. Geri çağrı URL'sinde açıkça belirtilen bağlantı noktası, dinleyiciyi yapılandırmaz. Doğrudan bir geri döngü geri çağrısı için bağlantı noktası içermeyen http://127.0.0.1 kullanın veya hem geri çağrı URL'si hem de dinleyici için aynı açık bağlantı noktasını yapılandırın. Proxy üzerinden geçen bir geri çağrı, yerel dinleyici bağlantı noktasından farklı bir harici URL bağlantı noktasını bilinçli olarak kullanabilir. Yerel geri çağrı URL'leri yerel arayüze bağlanır; yerel olmayan geri çağrı URL'leri 0.0.0.0 adresine bağlanır.

Codex, yetkilendirme kodunu takas etmeden önce döndürülen tüm iss değerlerini doğrular. Eşleşmeyen bir iss her zaman yanıtın reddedilmesine yol açar. Sağlayıcı desteği duyurulduğunda eksik bir iss değeri de yanıtın reddedilmesine yol açar. Her iki hatada da kod takas edilmez veya başka bir geri çağrıya dönülmez. Hatalı biçimlendirilmiş bir geri çağrı URL'si ya da meta veri sağlayıcısı olmadan duyurulan sağlayıcı desteği de kesin hata olarak kalır. Bkz. Kullanıcıların kimliğini doğrulama.

MCP sunucusu scopes_supported değerini duyurursa Codex, OAuth oturum açma sırasında sunucunun duyurduğu bu kapsamları tercih eder. Aksi takdirde Codex, config.toml içinde yapılandırılmış kapsamlara geri döner.

OAuth istemci kaydı

Codex, OAuth Client ID Metadata Documents (CIMD) ve Dynamic Client Registration'ı (DCR) destekler. Codex varsayılan olarak yetkilendirme sunucusu client_id_metadata_document_supported: true desteğini duyurduğunda, token_endpoint_auth_methods_supported içinde none bulunduğunda ve geri çağrı desteklenen bir geri döngü URL'si kullandığında otomatik olarak CIMD'yi seçer. Aksi takdirde Codex, kullanılabiliyorsa DCR'yi kullanır. Yapılandırılmış bir OAuth istemci kimliği her zaman önceliklidir ve istemci kaydını atlar.

Codex, CIMD için MCP sunucusuna özgü, ChatGPT tarafından barındırılan bir meta veri belgesi kullanır:

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

Codex, <callback_id> değerini MCP sunucusu URL'sinden türetir ve bunu http://127.0.0.1:<port>/callback/<callback_id> gibi geri döngü yönlendirme URI'sine ekler. Meta veri belgesi, eşleşen geri döngü URI'sini bağlantı noktası olmadan kaydeder. Yetkilendirme sunucuları, RFC 8252 gereğince ana makine ve yolu tam olarak eşleştirirken oturum açma sırasında seçilen bağlantı noktasını kabul etmelidir. Özel geri çağrı ana makineleri, yolları veya sorgu parametreleri DCR ya da yapılandırılmış bir OAuth istemci kimliği gerektirir.

Kararlı ve paylaşılan bir CIMD belgesi desteği geliştirilmekte olup yakında kullanıma sunulacaktır:

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

Codex, yetkilendirme sunucusu authorization_response_iss_parameter_supported: true desteğini duyurduğunda, meta verilerinde geçerli bir issuer sağladığında ve yetkilendirme yanıtlarında eşleşen bir iss içerdiğinde, paylaşılan /callback yoluna sahip kararlı belgeyi kullanacaktır. Sağlayıcıya bağlı yanıtları olmayan sunucular, geri çağrıya özgü belgeyi kullanmaya devam edecektir.

Tek bir CLI oturum açma işlemi için kayıt yöntemi seçmek üzere --oauth-client-registration kullanın:

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

Varsayılan değer auto şeklindedir. Kayıt seçimleri yalnızca mevcut oturum açma işlemi için geçerlidir ve config.toml içinde saklanmaz.

config.toml örnekleri

[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

Eklentiler tarafından sağlanan MCP sunucuları

Yüklü eklentiler, eklenti bildirimlerinde MCP sunucularını paketleyebilir. Bu sunucular eklentiden başlatıldığından kullanıcı yapılandırması aktarım komutlarını ayarlamaz. Kullanıcı yapılandırması, plugins.<plugin>.mcp_servers.<server> altında açma/kapatma durumunu ve araç politikasını yine de denetleyebilir.

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

Eklentiler tarafından sağlanan HTTP MCP sunucuları, OAuth ayarlarını .mcp.json içinde de bildirebilir. Eklenti bildirimleri clientId, callbackUrl ve callbackPort camelCase alan adlarını kullanır:

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

Eklentiler tarafından sağlanan MCP sunucuları, diğer MCP sunucularıyla aynı geri çağrı seçimi kurallarını izler. Bir eklenti clientId sağlıyorsa, sağlayıcısı sağlayıcıya bağlı geri çağrıları desteklemiyorsa ve callbackUrl sunucuya özgü geri çağrı kimliğini içermiyorsa Codex, oturum açma sırasında bu URL'yi yok sayar ve geri çağrı kimliği eklenmiş şekilde mcp_oauth_callback_url veya ayarlanmamışsa http://127.0.0.1/callback kullanır. Yapılandırılmış callbackUrl değişmeden kalır.

Bir eklentinin oauth.callbackPort değeri, genel mcp_oauth_callback_port değerini geçersiz kılar; ikisi de ayarlanmamışsa Codex geçici bir bağlantı noktası seçer. callbackUrl içine gömülü bağlantı noktası, dinleyici bağlantı noktasını seçmez. Sabit bağlantı noktasına sahip doğrudan bir geri döngü geri çağrısı için iki değeri de eşleşecek şekilde yapılandırın:

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

Uzak giriş veya başka bir proxy için, proxy yapılandırılmış dinleyiciye yönlendirme yaptığında geri çağrı URL'sinin bağlantı noktası ile yerel dinleyici bağlantı noktası bilinçli olarak farklı olabilir.

Yararlı MCP sunucusu örnekleri

MCP sunucularının listesi büyümeye devam ediyor. Yaygın örneklerden bazıları şunlardır:

• OpenAI Docs MCP: OpenAI geliştirici belgelerinde arama yapın ve bunları okuyun.
• Context7: Güncel geliştirici belgelerine bağlanın.
• Figma Yerel ve Uzak: Figma tasarımlarınıza erişin.
• Playwright: Playwright kullanarak bir tarayıcıyı denetleyin ve inceleyin.
• Chrome Developer Tools: Chrome'u denetleyin ve inceleyin.
• Sentry: Sentry günlüklerine erişin.
• GitHub: GitHub'ı git tarafından desteklenenlerin ötesinde yönetin (örneğin pull request'ler ve sorunlar).