{"title":"MCP Sorun Giderme","slug":"troubleshooting","category":"mcp","summary":"Yaygın MCP entegrasyon sorunlarını çözün — sunucu başlamıyor, araçlar görünmüyor, kimlik doğrulama hataları.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":548,"read_minutes":3,"llm_context":"Common issues:\n1. Node.js < 18 → upgrade to 18+\n2. Mind Key invalid → check format (mk_...), get fresh via POST /minds\n3. npx not found → install Node.js\n4. Tools not appearing → restart client, check config JSON validity\n5. SYNAPSE_URL unreachable → curl /health to verify\n6. MCP server crashes → check logs, run npx manually to see error\nDebug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr\nLogs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/\n","lang":"tr","translated":true,"requested_lang":"tr","content_markdown":"\n# MCP Sorun Giderme\n\nSynapse MCP'yi LLM istemcinizle entegre ederken yaygın sorunlar ve çözümler.\n\n## Hızlı Teşhis Kontrol Listesi\n\n1. ✅ Node.js 18+ yüklü mü? (`node --version`)\n2. ✅ Mind Key `mk_` ile mi başlıyor? (JWT `eyJ...` değil)\n3. ✅ Synapse API erişilebilir mi? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key çalışıyor mu? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Yapılandırma dosyası geçerli JSON mu? (sonda virgül yok, yorum yok)\n6. ✅ Yapılandırma değişikliğinden sonra istemci yeniden başlatıldı mı?\n7. ✅ MCP sunucusu manuel olarak başlıyor mu? (`npx -y synapse-mcp-api@latest`)\n\n## Sorun: İstemcide Hiç Araç Görünmüyor\n\n### Belirtiler\n\n- Claude Desktop / Cursor / Continue 0 araç gösteriyor\n- MCP sunucuları listesinde 🔌 simgesi veya \"synapse\" girişi yok\n\n### Çözümler\n\n1. **İstemciyi tamamen yeniden başlatın** — macOS'ta Cmd+Q (sadece pencereyi kapatmak değil)\n2. **Yapılandırma dosyası konumunu kontrol edin**:\n - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Claude Desktop Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - Cursor: `~/.cursor/config.json`\n - Continue: `~/.continue/config.json`\n3. **JSON'ı doğrulayın** — yapılandırmayı 'a yapıştırın\n4. **İstemci loglarını** MCP hataları için kontrol edin:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **MCP sunucusunu manuel çalıştırın** — başlangıç hatalarını görmek için:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Sorun: \"Mind Key invalid\" Hatası\n\n### Belirtiler\n\n- Araçlar görünüyor ama çağrılar \"401 Unauthorized\" ile başarısız oluyor\n- Hata: \"Mind Key fehlt oder ungültig\"\n\n### Çözümler\n\n1. **Mind Key biçimini doğrulayın** — `mk_` ile başlar, ~40 karakter\n2. **Doğrudan test edin**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **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ı\n4. **Yeni bir Mind Key alın**:\n ```bash\n # Login to get JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Create new mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## Sorun: npx Bulunamadı\n\n### Belirtiler\n\n- Hata: \"npx: command not found\"\n- MCP sunucusu başlatılamıyor\n\n### Çözümler\n\n1. **Node.js 18+ yükleyin**:\n - macOS: `brew install node` veya 'dan indirin\n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: 'dan indirin\n2. Yükledikten sonra **terminali yeniden başlatın**\n3. **Doğrulayın**: `node --version && npx --version`\n\n## Sorun: SYNAPSE_URL Erişilemiyor\n\n### Belirtiler\n\n- MCP sunucusu başlıyor ama araç çağrıları zaman aşımına uğruyor\n- Hata: \"fetch failed\" veya \"ECONNREFUSED\"\n\n### Çözümler\n\n1. **Bağlantıyı test edin**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Kurumsal güvenlik duvarını kontrol edin** — giden HTTPS'yi engelliyor olabilir\n3. **Alternatif URL deneyin**:\n - Üretim: `https://synapse.schaefer.zone`\n - MCP sunucusu: `https://synapse-mcp.schaefer.zone`\n4. **Self-hosted için**: Synapse örneğinizin çalıştığından ve erişilebilir olduğundan emin olun\n\n## Sorun: MCP Sunucusu Çöküyor\n\n### Belirtiler\n\n- MCP sunucusu başladıktan hemen sonra çıkıyor\n- İstemci logları \"MCP server disconnected\" gösteriyor\n\n### Çözümler\n\n1. **Hatayı görmek için manuel çalıştırın**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Port çakışmalarını kontrol edin** — MCP sunucusu varsayılan olarak 13100 portunu kullanır\n3. **npx önbelleğini temizleyin**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **En son sürüme güncelleyin**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Sorun: Araç Çağrıları 429 Döndürüyor\n\n### Belirtiler\n\n- Hata: \"Rate limit exceeded\"\n\n### Çözümler\n\nBu MCP ile olmamalı (header kimlik doğrulaması kullanır, hız sınırı yok). Olursa:\n\n1. **Bir yerde `?key=` kullanıp kullanmadığınızı kontrol edin** — header kimlik doğrulamasına geçin\n2. **`SYNAPSE_URL`'i doğrulayın** — doğru örneğe işaret ettiğinden emin olun\n3. Sorun sürerse **destekle iletişime geçin**\n\n## Sorun: Araçlar Görünüyor Ama Çalışmıyor\n\n### Belirtiler\n\n- İstemcide araçlar listeleniyor\n- Bir araç çağırma hata döndürüyor veya sonuç vermiyor\n\n### Çözümler\n\n1. **Araç adını kontrol edin** — tam olmalı (örn. `memory.recall` değil `memory_recall`)\n2. **Argümanları doğrulayın** — aracın giriş şemasını kontrol edin\n3. **Doğrudan API ile test edin**:\n ```bash\n curl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer mk_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\":\"fact\",\"key\":\"test\",\"content\":\"hello\"}'\n ```\n4. **Synapse sağlığını kontrol edin**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Yardım Alma\n\nYukarıdakiler hiçbiri sorununuzu çözmezse:\n\n1. **Mevcut issue'ları kontrol edin**: \n2. **Yeni bir issue açın** — şunlarla:\n - MCP sunucu sürümü (`npx -y synapse-mcp-api@latest --version`)\n - İstemci adı ve sürümü\n - İşletim sistemi\n - İlgili log alıntıları\n - Yeniden üretme adımları\n\n## Sonraki Adımlar\n\n- [Claude Desktop Kurulumu](/docs/mcp/claude-desktop)\n- [Claude Code Kurulumu](/docs/mcp/claude-code)\n- [API Hataları](/docs/api/errors)\n","content_html":"

MCP Sorun Giderme

\n

Synapse MCP'yi LLM istemcinizle entegre ederken yaygın sorunlar ve çözümler.

\n

Hızlı Teşhis Kontrol Listesi

\n
    \n
  1. ✅ Node.js 18+ yüklü mü? (node --version)
    2. \n
  2. ✅ Mind Key mk_ ile mi başlıyor? (JWT eyJ... değil)
    3. \n
  3. ✅ Synapse API erişilebilir mi? (curl https://synapse.schaefer.zone/health)
    4. \n
  4. ✅ Mind Key çalışıyor mu? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
    5. \n
  5. ✅ Yapılandırma dosyası geçerli JSON mu? (sonda virgül yok, yorum yok)
    6. \n
  6. ✅ Yapılandırma değişikliğinden sonra istemci yeniden başlatıldı mı?
    7. \n
  7. ✅ MCP sunucusu manuel olarak başlıyor mu? (npx -y synapse-mcp-api@latest)
    8. \n
\n

Sorun: İstemcide Hiç Araç Görünmüyor

\n

Belirtiler

\n
    \n
  • Claude Desktop / Cursor / Continue 0 araç gösteriyor
    • \n
  • MCP sunucuları listesinde 🔌 simgesi veya "synapse" girişi yok
    • \n
\n

Çözümler

\n
    \n
  1. İstemciyi tamamen yeniden başlatın — macOS'ta Cmd+Q (sadece pencereyi kapatmak değil)
    2. \n
  2. Yapılandırma dosyası konumunu kontrol edin:
      \n
    • Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
      • \n
    • Claude Desktop Windows: %APPDATA%\\Claude\\claude_desktop_config.json
      • \n
    • Cursor: ~/.cursor/config.json
      • \n
    • Continue: ~/.continue/config.json
      • \n
    \n
    3. \n
  3. JSON'ı doğrulayın — yapılandırmayı https://jsonlint.com'a yapıştırın
    4. \n
  4. İstemci loglarını MCP hataları için kontrol edin:
      \n
    • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
      • \n
    • Cursor: View → Output → MCP
      • \n
    \n
    5. \n
  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
    6. \n
\n

Sorun: "Mind Key invalid" Hatası

\n

Belirtiler

\n
    \n
  • Araçlar görünüyor ama çağrılar "401 Unauthorized" ile başarısız oluyor
    • \n
  • Hata: "Mind Key fehlt oder ungültig"
    • \n
\n

Çözümler

\n
    \n
  1. Mind Key biçimini doğrulayın — mk_ ile başlar, ~40 karakter
    2. \n
  2. Doğrudan test edin:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  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. \n
  4. Yeni bir Mind Key alın:
    # Login to get JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# Create new mind\ncurl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
    5. \n
\n

Sorun: npx Bulunamadı

\n

Belirtiler

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

Çözümler

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

Sorun: SYNAPSE_URL Erişilemiyor

\n

Belirtiler

\n
    \n
  • MCP sunucusu başlıyor ama araç çağrıları zaman aşımına uğruyor
    • \n
  • Hata: "fetch failed" veya "ECONNREFUSED"
    • \n
\n

Çözümler

\n
    \n
  1. Bağlantıyı test edin:
    curl https://synapse.schaefer.zone/health
    2. \n
  2. Kurumsal güvenlik duvarını kontrol edin — giden HTTPS'yi engelliyor olabilir
    3. \n
  3. Alternatif URL deneyin:
      \n
    • Üretim: https://synapse.schaefer.zone
      • \n
    • MCP sunucusu: https://synapse-mcp.schaefer.zone
      • \n
    \n
    4. \n
  4. Self-hosted için: Synapse örneğinizin çalıştığından ve erişilebilir olduğundan emin olun
    5. \n
\n

Sorun: MCP Sunucusu Çöküyor

\n

Belirtiler

\n
    \n
  • MCP sunucusu başladıktan hemen sonra çıkıyor
    • \n
  • İstemci logları "MCP server disconnected" gösteriyor
    • \n
\n

Çözümler

\n
    \n
  1. Hatayı görmek için manuel çalıştırın:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Port çakışmalarını kontrol edin — MCP sunucusu varsayılan olarak 13100 portunu kullanır
    3. \n
  3. npx önbelleğini temizleyin:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. En son sürüme güncelleyin:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

Sorun: Araç Çağrıları 429 Döndürüyor

\n

Belirtiler

\n
    \n
  • Hata: "Rate limit exceeded"
    • \n
\n

Çözümler

\n

Bu MCP ile olmamalı (header kimlik doğrulaması kullanır, hız sınırı yok). Olursa:

\n
    \n
  1. Bir yerde ?key= kullanıp kullanmadığınızı kontrol edin — header kimlik doğrulamasına geçin
    2. \n
  2. SYNAPSE_URL'i doğrulayın — doğru örneğe işaret ettiğinden emin olun
    3. \n
  3. Sorun sürerse destekle iletişime geçin
    4. \n
\n

Sorun: Araçlar Görünüyor Ama Çalışmıyor

\n

Belirtiler

\n
    \n
  • İstemcide araçlar listeleniyor
    • \n
  • Bir araç çağırma hata döndürüyor veya sonuç vermiyor
    • \n
\n

Çözümler

\n
    \n
  1. Araç adını kontrol edin — tam olmalı (örn. memory.recall değil memory_recall)
    2. \n
  2. Argümanları doğrulayın — aracın giriş şemasını kontrol edin
    3. \n
  3. Doğrudan API ile test edin:
    curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer mk_..." \\\n  -H "Content-Type: application/json" \\\n  -d '{"category":"fact","key":"test","content":"hello"}'
    4. \n
  4. Synapse sağlığını kontrol edin:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Yardım Alma

\n

Yukarıdakiler hiçbiri sorununuzu çözmezse:

\n
    \n
  1. Mevcut issue'ları kontrol edin: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
    2. \n
  2. Yeni bir issue açın — şunlarla:
      \n
    • MCP sunucu sürümü (npx -y synapse-mcp-api@latest --version)
      • \n
    • İstemci adı ve sürümü
      • \n
    • İşletim sistemi
      • \n
    • İlgili log alıntıları
      • \n
    • Yeniden üretme adımları
      • \n
    \n
    3. \n
\n

Sonraki Adımlar

\n\n","urls":{"html":"/docs/mcp/troubleshooting","text":"/docs/mcp/troubleshooting?format=text","json":"/docs/mcp/troubleshooting?format=json","llm":"/docs/mcp/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}