# MCP Sorun Giderme
SUMMARY: Yaygın MCP entegrasyon sorunlarını çözün — sunucu başlamıyor, araçlar görünmüyor, kimlik doğrulama hataları.

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

MCP Sorun Giderme
Synapse MCP'yi LLM istemcinizle entegre ederken yaygın sorunlar ve çözümler.
Hızlı Teşhis Kontrol Listesi
1. ✅ Node.js 18+ yüklü mü? ()
2. ✅ Mind Key  ile mi başlıyor? (JWT  değil)
3. ✅ Synapse API erişilebilir mi? ()
4. ✅ Mind Key çalışıyor mu? ()
5. ✅ Yapılandırma dosyası geçerli JSON mu? (sonda virgül yok, yorum yok)
6. ✅ Yapılandırma değişikliğinden sonra istemci yeniden başlatıldı mı?
7. ✅ MCP sunucusu manuel olarak başlıyor mu? ()
Sorun: İstemcide Hiç Araç Görünmüyor
Belirtiler
- Claude Desktop / Cursor / Continue 0 araç gösteriyor
- MCP sunucuları listesinde 🔌 simgesi veya "synapse" girişi yok
Çözümler
1. İstemciyi tamamen yeniden başlatın — macOS'ta Cmd+Q (sadece pencereyi kapatmak değil)
2. Yapılandırma dosyası konumunu kontrol edin:
   - Claude Desktop macOS: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. JSON'ı doğrulayın — yapılandırmayı <https://jsonlint.com>'a yapıştırın
4. İstemci loglarını MCP hataları için kontrol edin:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. MCP sunucusunu manuel çalıştırın — başlangıç hatalarını görmek için:
   [CODE BLOCK]
Sorun: "Mind Key invalid" Hatası
Belirtiler
- Araçlar görünüyor ama çağrılar "401 Unauthorized" ile başarısız oluyor
- Hata: "Mind Key fehlt oder ungültig"
Çözümler
1. Mind Key biçimini doğrulayın —  ile başlar, 40 karakter
2. Doğrudan test edin:
   [CODE BLOCK]
3. Env değişkeninin ayarlandığını kontrol edin — stdio taşıyıcısı için env değişkeni kabuğunuzda değil, MCP sunucu yapılandırmasında olmalı
4. Yeni bir Mind Key alın:
   [CODE BLOCK]
Sorun: npx Bulunamadı
Belirtiler
- Hata: "npx: command not found"
- MCP sunucusu başlatılamıyor
Çözümler
1. Node.js 18+ yükleyin:
   - macOS:  veya <https://nodejs.org>'dan indirin
   - Linux: 
   - Windows: <https://nodejs.org>'dan indirin
2. Yükledikten sonra terminali yeniden başlatın
3. Doğrulayın: 
Sorun: SYNAPSEURL Erişilemiyor
Belirtiler
- MCP sunucusu başlıyor ama araç çağrıları zaman aşımına uğruyor
- Hata: "fetch failed" veya "ECONNREFUSED"
Çözümler
1. Bağlantıyı test edin:
   [CODE BLOCK]
2. Kurumsal güvenlik duvarını kontrol edin — giden HTTPS'yi engelliyor olabilir
3. Alternatif URL deneyin:
   - Üretim: 
   - MCP sunucusu: 
4. Self-hosted için: Synapse örneğinizin çalıştığından ve erişilebilir olduğundan emin olun
Sorun: MCP Sunucusu Çöküyor
Belirtiler
- MCP sunucusu başladıktan hemen sonra çıkıyor
- İstemci logları "MCP server disconnected" gösteriyor
Çözümler
1. Hatayı görmek için manuel çalıştırın:
   [CODE BLOCK]
2. Port çakışmalarını kontrol edin — MCP sunucusu varsayılan olarak 13100 portunu kullanır
3. npx önbelleğini temizleyin:
   [CODE BLOCK]
4. En son sürüme güncelleyin:
   [CODE BLOCK]
Sorun: Araç Çağrıları 429 Döndürüyor
Belirtiler
- Hata: "Rate limit exceeded"
Çözümler
Bu MCP ile olmamalı (header kimlik doğrulaması kullanır, hız sınırı yok). Olursa:
1. Bir yerde  kullanıp kullanmadığınızı kontrol edin — header kimlik doğrulamasına geçin
2. 'i doğrulayın — doğru örneğe işaret ettiğinden emin olun
3. Sorun sürerse destekle iletişime geçin
Sorun: Araçlar Görünüyor Ama Çalışmıyor
Belirtiler
- İstemcide araçlar listeleniyor
- Bir araç çağırma hata döndürüyor veya sonuç vermiyor
Çözümler
1. Araç adını kontrol edin — tam olmalı (örn.  değil )
2. Argümanları doğrulayın — aracın giriş şemasını kontrol edin
3. Doğrudan API ile test edin:
   [CODE BLOCK]
4. Synapse sağlığını kontrol edin:
   [CODE BLOCK]
Yardım Alma
Yukarıdakiler hiçbiri sorununuzu çözmezse:
1. Mevcut issue'ları kontrol edin: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. Yeni bir issue açın — şunlarla:
   - MCP sunucu sürümü ()
   - İstemci adı ve sürümü
   - İşletim sistemi
   - İlgili log alıntıları
   - Yeniden üretme adımları
Sonraki Adımlar
- Claude Desktop Kurulumu
- Claude Code Kurulumu
- API Hataları