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

Adres: https://agentvera.dev/blog/claude-code-mcp-kurulumu/ · Yayın: 2026-10-28

Claude Code’a MCP sunucusu ekleme: stdio ve HTTP için claude mcp add, kapsamlar, .mcp.json, /mcp ve OAuth, Claude Desktop’tan aktarma, zaman aşımı ve çıktı sınırları.

**Kısaca:**

- Sunucuyu claude mcp add ile eklersin: seçenekler addan önce gelir, yerel bir stdio sunucusunun komutu -- işaretinden sonra yazılır. Uzak sunucular --transport http ve bir URL ile eklenir.
- Kapsam, sunucunun nereye yazılacağını belirler: local (varsayılan) ve user ~/.claude.json içinde, project ise repo kökünde commit edebileceğin bir .mcp.json dosyasında tutulur.
- Oturum içinde /mcp ile durumu görür, OAuth sunucularına giriş yapar ve sunucuları kapatırsın. Açılış ve çıktı sorunlarının çoğunu MCP_TIMEOUT ve MAX_MCP_OUTPUT_TOKENS çözer.
- Claude Code, bir projenin .mcp.json sunucularını kullanmadan önce sorar. Onları repodaki her kod gibi incele, token’ları dosyaya değil ${VAR} referanslarına koy.

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](https://code.claude.com/docs/en/mcp "Claude Code MCP dokümantasyonu") alındı. MCP sana yeniyse önce [MCP sunucusu nedir](/blog/mcp-sunucusu-nedir/ "MCP sunucusu nedir") yazısına, hangi sunucuları ekleyeceğini merak ediyorsan [kodlama için en iyi MCP sunucuları](/blog/en-iyi-mcp-sunuculari/ "En iyi MCP sunucuları") listesine bak.

## Hızlı başvuru

| İş | Komut |
| --- | --- |
| Yerel (stdio) sunucu ekle | `claude mcp add <ad> -- <komut> [argümanlar...]` |
| Uzak (HTTP) sunucu ekle | `claude mcp add --transport http <ad> <url>` |
| JSON parçasından ekle | `claude mcp add-json <ad> '<json>'` |
| Ekiple paylaş | `--scope project` ekle (`.mcp.json` yazar) |
| Tüm projelerinde kullan | `--scope user` ekle |
| Sunucuları ve durumlarını listele | `claude mcp list` |
| Bir sunucunun ayrıntıları | `claude mcp get <ad>` |
| Sunucuyu kaldır | `claude mcp remove <ad>` |
| OAuth sunucusuna giriş | Oturumda `/mcp` ya da `claude mcp login <ad>` |
| Claude Desktop’tan aktar | `claude mcp add-from-claude-desktop` |
| Durum, giriş, kapatma, yeniden bağlanma | Claude Code içinde `/mcp` |

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](/sozluk/mcp/ "MCP") sunucusu Claude Code’a üç yoldan bağlanır:

| Tür | Nedir | Ne zaman |
| --- | --- | --- |
| `stdio` | Claude Code’un başlattığı ve stdin/stdout üzerinden konuştuğu yerel süreç | `npx`, `uvx`, Docker ya da kendi betiğinle çalışan sunucular |
| `http` | Streamable HTTP üzerinden uzak sunucu | Barındırılan servisler: Notion, Sentry, GitHub, Stripe ve diğerleri. Anthropic uzak sunucular için bunu öneriyor |
| `sse` | Server-Sent Events | Yalnızca eski uzak sunucular. Dokümantasyon SSE’yi kullanımdan kalkmış olarak işaretliyor |

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.

```bash
# 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:

```bash
# 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:

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

## Kapsamı seç

Her `claude mcp add` üç kapsamdan birine yazar:

| Kapsam | Bayrak | Nerede durur | Kime gelir |
| --- | --- | --- | --- |
| Local (varsayılan) | `--scope local` | `~/.claude.json`, bu projenin yolu altında | Yalnızca sana, yalnızca bu projede |
| Project | `--scope project` | Proje kökündeki `.mcp.json` | Repoyu klonlayan herkese |
| User | `--scope user` | `~/.claude.json` | Yalnızca sana, her projede |

```bash
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:

```json
{
  "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:

```bash
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](/blog/claude-code-hooks-rehberi/ "Claude Code hooks rehberi") 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:

```bash
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:

```bash
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:

```bash
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

| Belirti | Ne denemeli |
| --- | --- |
| Sunucu bağlanmıyor | Hata için `claude mcp get <ad>`, sonra `/mcp` içinde **Reconnect** |
| Yavaş sunucu açılışta zaman aşımına uğruyor | `MCP_TIMEOUT=10000 claude` ile başlat (on saniye) |
| Uzun araç çağrıları yarıda kesiliyor | Tüm sunucular için `MCP_TOOL_TIMEOUT`, tek sunucu için `.mcp.json` içinde `"timeout"` |
| Çıktı uyarısı ya da kırpılmış sonuç | Claude Code 10.000 token’ın üstünde uyarır, çıktıyı varsayılan olarak 25.000’de keser. `MAX_MCP_OUTPUT_TOKENS=50000` ile yükselt |
| Sunucunun bayrakları yok sayılıyor ya da reddediliyor | Claude Code seçeneklerini addan önce, sunucu komutunu `--` sonrasına yaz |
| `/mcp` içinde `${VAR}` uyarısı | Değişkeni Claude Code’u başlattığın kabukta tanımla ya da `:-default` ekle |
| Sunucu yüklenirken atlanıyor | Ad ayrılmış (`workspace`, `claude-in-chrome`, `computer-use` ve birkaçı daha); adını değiştir |
| Token curl’de çalışıyor, burada çalışmıyor | Yapıştırdığın token’ın sonunda boşluk ya da satır sonu var mı bak; Claude Code gizli boşluklar için uyarır |

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](/sozluk/prompt-enjeksiyonu/ "Prompt enjeksiyonu") 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](/blog/yapay-zeka-kodlama-ajani-guvenligi/ "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](/ozellikler/mcp-yoneticisi/ "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?](/blog/mcp-sunucusu-nedir/ "MCP sunucusu nedir")
- [Kodlama ajanları için en iyi MCP sunucuları](/blog/en-iyi-mcp-sunuculari/ "En iyi MCP sunucuları")
- [MCP yöneticisi](/ozellikler/mcp-yoneticisi/ "MCP yöneticisi")
- [Claude Code ajanı](/ajanlar/claude-code/ "AgentVera’da Claude Code")

## Sık sorulanlar

**Claude Code’a MCP sunucusu nasıl eklenir?** Terminalde claude mcp add çalıştır. Yerel sunucu için: claude mcp add <ad> -- <komut> [argümanlar]. Uzak sunucu için: claude mcp add --transport http <ad> <url>. Ardından bağlandığını görmek için claude mcp list ya da oturum içinde /mcp kullan.

**Claude Code MCP sunucularını nerede saklar?** Local kapsamlı (varsayılan) ve user kapsamlı sunucular ~/.claude.json içinde durur; local olanlar o projenin yolunun altına yazılır. Project kapsamlı sunucular proje kökündeki .mcp.json dosyasındadır ve bu dosyayı ekibin için commit edebilirsin.

**local, project ve user kapsamı arasındaki fark ne?** Local yalnızca senin için ve yalnızca bu projede geçerlidir. Project, .mcp.json üzerinden repoyu klonlayan herkese gelir. User yalnızca senin içindir ama makinedeki her projede çalışır. Aynı ad birden çok kapsamda varsa local, project’in; project de user’ın önüne geçer.

**OAuth kullanan bir MCP sunucusuna nasıl giriş yapılır?** Sunucuyu --transport http ile ekle, sonra Claude Code içinde /mcp çalıştırıp Authenticate seç ya da kabuktan claude mcp login <ad> komutunu kullan. Tarayıcıdaki giriş akışı tamamlar; token’ı Claude Code saklar ve yeniler.

**MCP sunucum neden zaman aşımına uğruyor ya da çıktısı kesiliyor?** Yavaş açılan sunucular daha uzun bir başlangıç süresi isteyebilir: Claude Code’u on saniye için MCP_TIMEOUT=10000 ile başlat. Araç çıktısı varsayılan olarak 25.000 token’la sınırlıdır ve 10.000’in üstünde uyarı verilir; sınırı MAX_MCP_OUTPUT_TOKENS ile yükseltebilirsin.

**Klonladığım bir repodaki .mcp.json güvenli mi?** Onu senin yazmadığın her kod gibi değerlendir. Claude Code etkileşimli oturumda proje sunucularını kullanmadan önce onay ister ve klonlanan bir repo kendi sunucularını onaylayamaz. Evet demeden önce her komutu ve URL’yi oku.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/