# 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:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   # 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**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **En son sürüme güncelleyin**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [Claude Code Kurulumu](/docs/mcp/claude-code)
- [API Hataları](/docs/api/errors)