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ü? (node --version)
2. ✅ Mind Key mk_ ile mi başlıyor? (JWT eyJ... değil)
3. ✅ Synapse API erişilebilir mi? (curl https://synapse.schaefer.zone/health)
4. ✅ Mind Key çalışıyor mu? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
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? (npx -y synapse-mcp-api@latest)

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: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Cursor: ~/.cursor/config.json
   • Continue: ~/.continue/config.json
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: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. MCP sunucusunu manuel çalıştırın — başlangıç hatalarını görmek için:

   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

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 — mk_ ile başlar, ~40 karakter
2. Doğrudan test edin:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

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:

   # Login to get JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Create new mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

Sorun: npx Bulunamadı

Belirtiler

• Hata: "npx: command not found"
• MCP sunucusu başlatılamıyor

Çözümler

1. Node.js 18+ yükleyin:
   • macOS: brew install node veya https://nodejs.org'dan indirin
   • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows: https://nodejs.org'dan indirin
2. Yükledikten sonra terminali yeniden başlatın
3. Doğrulayın: node --version && npx --version

Sorun: SYNAPSE_URL 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:

   curl https://synapse.schaefer.zone/health

2. Kurumsal güvenlik duvarını kontrol edin — giden HTTPS'yi engelliyor olabilir
3. Alternatif URL deneyin:
   • Üretim: https://synapse.schaefer.zone
   • MCP sunucusu: https://synapse-mcp.schaefer.zone
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:

   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest

2. Port çakışmalarını kontrol edin — MCP sunucusu varsayılan olarak 13100 portunu kullanır
3. npx önbelleğini temizleyin:

   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx

4. En son sürüme güncelleyin:

   npx -y synapse-mcp-api@latest --version

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 ?key= kullanıp kullanmadığınızı kontrol edin — header kimlik doğrulamasına geçin
2. SYNAPSE_URL'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. memory.recall değil memory_recall)
2. Argümanları doğrulayın — aracın giriş şemasını kontrol edin
3. Doğrudan API ile test edin:

   curl -X POST https://synapse.schaefer.zone/memory \
     -H "Authorization: Bearer mk_..." \
     -H "Content-Type: application/json" \
     -d '{"category":"fact","key":"test","content":"hello"}'

4. Synapse sağlığını kontrol edin:

   curl https://synapse.schaefer.zone/health

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ü (npx -y synapse-mcp-api@latest --version)
   • İ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ı