Claude Code MCP kurulumu: sunucu ekleme, kapsam ve yönetim

Claude Code’da MCP kurmak için terminalde claude mcp add çalıştırırsın. Yerel bir sunucu claude mcp add <ad> -- <komut>, uzak bir sunucu claude mcp add --transport http <ad> <url> şeklinde eklenir. --scope ise sunucunun yalnızca senin için bu projede mi (local, varsayılan), .mcp.json dosyasıyla tüm ekip için mi (project), yoksa senin için her projede mi (user) geçerli olacağını belirler. Sonra oturum içinde /mcp yazıp bağlantıyı kontrol eder, OAuth kullanan sunuculara giriş yaparsın.

Bu rehber her adımı anlatıyor: bağlantı türleri, -- ayracı, ortam değişkenleri ve header’lar, kapsamlar, .mcp.json dosyasını elle yazmak, list, get ve remove komutları, OAuth, Claude Desktop’tan aktarma, zaman aşımları ve çıktı sınırları ve bir projenin sunucularına güvenmeden önce bakman gerekenler. Komutlar, Ekim 2026 itibarıyla Anthropic’in Claude Code MCP dokümantasyonundan alındı. MCP sana yeniyse önce MCP sunucusu nedir yazısına, hangi sunucuları ekleyeceğini merak ediyorsan kodlama için en iyi MCP sunucuları listesine bak.

Hızlı başvuru

Kısa bayraklar da çalışır: --transport için -t, --scope için -s, --env için -e, --header için -H.

Bağlantı türünü seç: stdio, HTTP ya da SSE

Bir MCP sunucusu Claude Code’a üç yoldan bağlanır:

Artık --transport sse yazman pek gerekmiyor. Claude Code 2.1.265’ten beri claude mcp add --transport http önce HTTP’yi dener, sunucu kabul etmezse kendiliğinden SSE’ye geçer. Daha eski sürümlerde --transport sse bayrağını açıkça vermen gerekir.

Yerel stdio sunucusu ekle

En çok takılınan kural şu: Claude Code’un kendi seçenekleri (--transport, --scope, --env) sunucu adından önce gelir, -- işaretinden sonraki her şey de olduğu gibi sunucunun komutuna geçer.

# Temel biçim
claude mcp add [seçenekler] <ad> -- <komut> [argümanlar...]

# npx ile çalışan Playwright
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Ortamında API anahtarı isteyen bir sunucu
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

-- olmadan --port 8080 gibi bir sunucu bayrağı Claude Code seçeneği sanılır ve komut hata verir. Dokümantasyondaki bir tuzak daha: --env birden çok KEY=value çifti alır; sunucu adı hemen arkasından gelirse ad da bir çift sanılıp reddedilir. Yukarıdaki örnekteki gibi araya --transport stdio gibi başka bir seçenek koy.

Claude Code her stdio sunucusunun ortamına CLAUDE_PROJECT_DIR değişkenini koyar; böylece sunucu, çalışma klasörüne bağlı kalmadan proje kökünü bulabilir.

Uzak HTTP sunucusu ekle

Uzak sunucular komut yerine bir URL alır. Sunucu API anahtarı ya da bearer token istiyorsa --header ile header ekle:

# OAuth ile giriş yapılan barındırılan bir sunucu
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Sabit token isteyen bir sunucu
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Burada yazdığın header, ayar dosyasına düz metin olarak kaydedilir. Paylaşılan her şey için OAuth’u ya da aşağıda anlatılan .mcp.json içindeki ${VAR} referansını tercih et.

Sunucunun README’sinde hazır bir JSON tanımı varsa bayraklarla uğraşma, add-json ile yapıştır. Bu komut dosyanın tamamını değil, mcpServers içinde duracak nesneyi alır:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Kapsamı seç

Her claude mcp add üç kapsamdan birine yazar:

claude mcp add --transport http stripe https://mcp.stripe.com                      # local
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Pratik kural: kişisel araçlar ve kendi kimlik bilgilerini taşıyan her şey user ya da local kapsamına; ekibin bu repoda çalışmak için ihtiyaç duyduğu sunucular project kapsamına.

Buradaki “local”, .claude/settings.local.json demek değil. Local MCP sunucuları ev klasöründeki ~/.claude.json dosyasında durur.

Aynı ad birden çok yerde tanımlıysa Claude Code en üsttekini alır ve alanları birleştirmez: önce local, sonra project, sonra user, sonra plugin sunucuları, en son claude.ai bağlayıcıları. İki kapsam aynı adı farklı adreslere bağlıyorsa claude mcp list ve /mcp seni uyarır.

.mcp.json dosyasını elle yaz

Project kapsamlı bir sunucu, düzenleyip pull request’te inceleyebileceğin bir .mcp.json dosyasından ibarettir:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} bir ortam değişkeninin değerine açılır, ${VAR:-default} ise değişken yoksa varsayılanı kullanır. Bu açılım command, args, env, url ve headers alanlarında çalışır; dosyayı token’ları commit etmeden paylaşmanın yolu da budur: her geliştirici API_KEY değerini kendi kabuğunda tanımlar. Değişken yoksa ve varsayılanı da yoksa claude mcp list ile /mcp uyarı verir ve metni açmadan bırakır.

Sunucu başına milisaniye cinsinden bir "timeout" değeri, o sunucunun araç çağrıları için kesin bir üst sınır koyar.

Sunucuları yönet: list, get, remove ve /mcp

Kabuktan:

claude mcp list          # tüm sunucular ve bağlantı durumları
claude mcp get notion    # tek bir sunucunun ayrıntıları, neden bağlanamadığı dahil
claude mcp remove notion # sunucuyu kapsamından sil

list ve get, hata ayrıntısını kimlik bilgilerini gizleyerek gösterir. Henüz onaylamadığın bir proje sunucusu, claude’u etkileşimli açıp onaylayana kadar bekliyor olarak görünür.

Oturum içinde kontrol paneli /mcp’dir. Her sunucunun durumunu ve araç sayısını gösterir; bir sunucunun menüsünden giriş yapabilir, yeniden giriş yapabilir, girişi silebilir, yeniden bağlanabilir ya da ayarını silmeden sunucuyu kapatabilirsin. /mcp reconnect all bağlanamayan tüm sunucuları tek seferde yeniden dener (Claude Code 2.1.284 ve sonrası).

Bağlanan sunucular yalnızca araç getirmez. @ yazınca dosyalarının yanında sunucunun kaynaklarını da görürsün; / yazınca da sunucunun prompt’ları /sunucuadi:promptadi (MCP) biçiminde listelenir. Araçların adı mcp__<sunucu>__<araç> şeklindedir; izin kurallarında ve hook matcher’larında bu adı kullanırsın.

OAuth sunucularına giriş yap

Sentry, Notion ya da Linear gibi barındırılan pek çok sunucu sabit token yerine OAuth kullanır. Sunucuyu header vermeden --transport http ile ekle, sonra giriş yap:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Claude Code içinde /mcp çalıştır, sunucuyu seç ve Authenticate’e bas. Tarayıcın açılır, giriş yaparsın; Claude Code token’ı saklar ve yeniler. Oturum açmadan kabuktan da yapabilirsin:

claude mcp login sentry               # tarayıcıyı açar
claude mcp login sentry --no-browser  # URL’yi yazdırır, SSH oturumları için
claude mcp logout sentry              # saklanan kimlik bilgilerini siler

Headless çalıştırmalar (claude -p) giriş ekranı gösteremez; bu yüzden önce bir kez etkileşimli oturumda giriş yap. Bazı sunucular sabit bir callback portu ya da önceden kaydedilmiş bir OAuth uygulaması ister; onlar için sunucuyu eklerken --callback-port, --client-id ve --client-secret ver. Secret maskeli girişle sorulur ya da CI’da MCP_CLIENT_SECRET değişkeninden okunur.

Sunucuları Claude Desktop’tan aktar

Sunucularını Claude Desktop uygulamasında zaten kurduysan baştan yazmana gerek yok:

claude mcp add-from-claude-desktop

Açılan pencerede hangi sunucuları aktaracağını seçersin. Ekim 2026 itibarıyla bu yalnızca macOS’ta ve WSL’de çalışıyor. User ayarına aktarmak için --scope user ekle. Sunucu adlarında yalnızca harf, rakam, tire ve alt çizgi olabilir; adında boşluk olan bir Desktop sunucusu atlanır ve raporlanır, zaten var olan bir ad ise server_1 gibi bir ek alır.

Sorun giderme

Uzun metin sonuçlarının ikinci bir sınırı var: 50.000 karakteri aşan bir sonuç doğrudan bağlama girmek yerine bir dosyaya kaydedilir.

Oturum ortasında düşen uzak sunucular artan aralıklarla beş kez yeniden denenir, ama stdio sunucuları otomatik yeniden denenmez; çöken yerel bir sunucu için /mcp’den yeniden bağlanman gerekir.

Dikkat edilecek diğer maliyet bağlam. Claude Code güncel modellerde varsayılan olarak araç aramasını (tool search) kullanır: açılışta yalnızca araç adları ve sunucu talimatları yüklenir, tam araç tanımları Claude ihtiyaç duyduğunda gelir. Bu, uzun bir sunucu listesini ucuz tutar; yine de her sunucu bozulabilecek ya da kötüye kullanılabilecek bir parça daha demek, listeyi kısa tut. Betikler için --mcp-config <dosya> tek bir çalıştırmaya ek sunucular yükler, --strict-mcp-config de Claude Code’un yalnızca bunları kullanmasını sağlar.

Güvenlik: proje sunucuları repodan gelen koddur

Repodaki bir .mcp.json herhangi bir yerel komutu başlatabilir ya da herhangi bir URL’ye bağlanabilir. Ekipler için onu kullanışlı yapan da bu, Claude Code’un ona temkinli yaklaşmasının nedeni de:

• Önce onay. Etkileşimli oturumda Claude Code, project kapsamlı sunucuları kullanmadan önce sorar. claude mcp reset-project-choices önceki cevaplarını sıfırlar.
• Repo kendini onaylayamaz. Projenin .claude/settings.json dosyasına commit edilmiş enableAllProjectMcpServers gibi ayarlar, klasöre güvenene kadar yok sayılır ve sunucu beklemede kalır. Kendi user ayarlarındaki onaylar yine geçerlidir.
• Headless çalıştırmalar sormaz. claude -p ve Agent SDK oturumlarında onay ekranı olmadığından proje sunucuları sorulmadan yüklenir. Bir sunucuyu her modda engellemek için onu disabledMcpjsonServers listesine yaz.
• Kimlik bilgileri evde kalır. Uzak bir sunucunun url ve headers alanlarında ANTHROPIC_API_KEY gibi hassas değişkenler, tanımlı olsalar bile boş açılır; böylece bir proje Anthropic anahtarını sessizce kendi sunucusuna gönderemez.
• Sunucunun döndürdüğüne de çalıştırdığı kadar az güven. Anthropic’in dokümantasyonu, dışarıdan içerik çeken sunucuların seni prompt enjeksiyonuna açık hale getirebileceği konusunda uyarıyor. Salt okunur modları ve dar yetkili token’ları tercih et.

Onaylamadan önce her sunucunun command, args ve url alanlarını bir postinstall betiğini okur gibi oku. Konunun geneli için yapay zeka kodlama ajanı güvenliği yazısına bakabilirsin.

Claude Code’dan fazlasını çalıştırıyorsan

Yukarıdaki her şey tek bir CLI için. Codex sunucularını ~/.codex/config.toml dosyasında, Gemini CLI kendi settings.json dosyasında tutar ve her aracın kendi komutları vardır. Kullandığın tek ajan Claude Code ise claude mcp add ve commit edilmiş bir .mcp.json sana yeter; burada anlatılanlar başka bir araç gerektirmez.

Birden çok kodlama CLI’ı çalıştırıyorsan listeler zamanla birbirinden ayrışır. Bu blogu yayımlayan masaüstü uygulaması AgentVera’daki MCP yöneticisi tam bu sorun için var:

• Bir kez eklenir, açılışta bağlanır. stdio, HTTP ve SSE sunucularını AgentVera’ya kaydedersin, ajanlar başlarken bağlanırlar: tüm ajanlara, seçtiklerine, bir grubun ajanlarına ya da bir ekip rolüne. Claude Code, Codex ve MCP alan diğer CLI ajanları bunları alır.
• Claude Code’un kendi ayarlarıyla uyumlu. Claude Code’un ve Codex’in ayarlarındaki sunucular sağlık durumlarıyla listelenir; onları AgentVera’ya aktarabilir ya da CLI’dan kaldırabilirsin. AgentVera’nın sunucuları da CLI ayarlarına yazılabilir.
• Tek giriş, dosyada token yok. Uzak sunucular AgentVera’nın gateway’inden geçer, OAuth sunucusuna uygulamada bir kez giriş yaparsın ve ajanın CLI’ı hiçbir header ya da token tutmaz. Gizli ortam değişkenleri ve header’lar işletim sisteminin anahtar zincirinde saklanır.
• Görünen maliyet. Bağlantı testi sunucunun araçlarını, prompt’larını ve kaynaklarını, her araç için yaklaşık token maliyetiyle listeler.

Toparlarsak

Gerçekten ihtiyacın olan tek bir sunucuyla başla ve onu işini gören en dar kapsamda claude mcp add ile ekle. claude mcp list ya da /mcp ile kontrol et, /mcp veya claude mcp login ile giriş yap; sunucuyu commit edilmiş bir .mcp.json dosyasına ancak tüm ekip ihtiyaç duyduğunda, token’lar ${VAR} referanslarında olacak şekilde taşı. Bir şey bozulduğunda claude mcp get, MCP_TIMEOUT ve MAX_MCP_OUTPUT_TOKENS sorunların çoğunu çözer.

Devamını oku:

• MCP sunucusu nedir?
• Kodlama ajanları için en iyi MCP sunucuları
• MCP yöneticisi
• Claude Code ajanı