MCP Troubleshooting

Masalah umum dan solusi saat mengintegrasikan Synapse MCP dengan klien LLM Anda.

Daftar Periksa Diagnostik Cepat

1. ✅ Node.js 18+ terpasang? (node --version)
2. ✅ Mind Key dimulai dengan mk_? (bukan JWT eyJ...)
3. ✅ Synapse API dapat dijangkau? (curl https://synapse.schaefer.zone/health)
4. ✅ Mind Key berfungsi? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
5. ✅ File konfigurasi adalah JSON yang valid? (tanpa koma berlebih, tanpa komentar)
6. ✅ Klien dimulai ulang setelah perubahan konfigurasi?
7. ✅ MCP server dimulai secara manual? (npx -y synapse-mcp-api@latest)

Masalah: Tidak Ada Alat yang Muncul di Klien

Gejala

• Claude Desktop / Cursor / Continue menunjukkan 0 alat
• Tidak ada ikon 🔌 atau entri "synapse" dalam daftar MCP server

Solusi

1. Mulai ulang klien sepenuhnya — Cmd+Q di macOS (bukan hanya tutup jendela)
2. Periksa lokasi file konfigurasi:
   • 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. Validasi JSON — tempel konfigurasi ke https://jsonlint.com
4. Periksa log klien untuk error MCP:
   • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. Jalankan MCP server secara manual untuk melihat error startup:

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

Masalah: Error "Mind Key invalid"

Gejala

• Alat muncul tetapi panggilan gagal dengan "401 Unauthorized"
• Error: "Mind Key fehlt oder ungültig"

Solusi

1. Verifikasi format Mind Key — dimulai dengan mk_, ~40 karakter
2. Tes langsung:

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

3. Periksa env var diatur — untuk transport stdio, env var harus dalam konfigurasi MCP server, bukan shell Anda
4. Dapatkan Mind Key baru:

   # 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"}'

Masalah: npx Tidak Ditemukan

Gejala

• Error: "npx: command not found"
• MCP server gagal dimulai

Solusi

1. Pasang Node.js 18+:
   • macOS: brew install node atau unduh dari https://nodejs.org
   • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows: unduh dari https://nodejs.org
2. Mulai ulang terminal setelah pasang
3. Verifikasi: node --version && npx --version

Masalah: SYNAPSE_URL Tidak Dapat Dijangkau

Gejala

• MCP server dimulai tetapi panggilan alat timeout
• Error: "fetch failed" atau "ECONNREFUSED"

Solusi

1. Tes konektivitas:

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

2. Periksa firewall korporat — mungkin memblokir HTTPS keluar
3. Coba URL alternatif:
   • Produksi: https://synapse.schaefer.zone
   • MCP server: https://synapse-mcp.schaefer.zone
4. Untuk self-hosted: pastikan instansi Synapse Anda berjalan dan dapat diakses

Masalah: MCP Server Crash

Gejala

• MCP server keluar segera setelah dimulai
• Log klien menunjukkan "MCP server disconnected"

Solusi

1. Jalankan secara manual untuk melihat error:

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

2. Periksa konflik port — MCP server menggunakan port 13100 secara default
3. Bersihkan cache npx:

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

4. Perbarui ke versi terbaru:

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

Masalah: Panggilan Alat Mengembalikan 429

Gejala

• Error: "Rate limit exceeded"

Solusi

Ini seharusnya tidak terjadi dengan MCP (menggunakan autentikasi header, tanpa rate limit). Jika terjadi:

1. Periksa jika Anda menggunakan ?key= di suatu tempat — beralih ke autentikasi header
2. Verifikasi SYNAPSE_URL — pastikan menunjuk ke instansi yang benar
3. Hubungi support jika masalah berlanjut

Masalah: Alat Muncul tetapi Tidak Berfungsi

Gejala

• Alat terdaftar di klien
• Memanggil alat mengembalikan error atau tidak ada hasil

Solusi

1. Periksa nama alat — harus persis (mis. memory_recall, bukan memory.recall)
2. Verifikasi argumen — periksa skema input alat
3. Tes via API langsung:

   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. Periksa health Synapse:

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

Mendapatkan Bantuan

Jika tidak ada di atas yang menyelesaikan masalah Anda:

1. Periksa issue yang ada: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
2. Buka issue baru dengan:
   • Versi MCP server (npx -y synapse-mcp-api@latest --version)
   • Nama dan versi klien
   • Sistem operasi
   • Kutipan log yang relevan
   • Langkah reproduksi

Langkah Berikutnya

• Pengaturan Claude Desktop
• Pengaturan Claude Code
• API Errors