# MCP Troubleshooting
SUMMARY: Selesaikan masalah integrasi MCP umum — server tidak dimulai, alat tidak muncul, error autentikasi.

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 Troubleshooting
Masalah umum dan solusi saat mengintegrasikan Synapse MCP dengan klien LLM Anda.
Daftar Periksa Diagnostik Cepat
1. ✅ Node.js 18+ terpasang? ()
2. ✅ Mind Key dimulai dengan ? (bukan JWT )
3. ✅ Synapse API dapat dijangkau? ()
4. ✅ Mind Key berfungsi? ()
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? ()
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: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. Validasi JSON — tempel konfigurasi ke <https://jsonlint.com>
4. Periksa log klien untuk error MCP:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. Jalankan MCP server secara manual untuk melihat error startup:
   [CODE BLOCK]
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 , 40 karakter
2. Tes langsung:
   [CODE BLOCK]
3. Periksa env var diatur — untuk transport stdio, env var harus dalam
   konfigurasi MCP server, bukan shell Anda
4. Dapatkan Mind Key baru:
   [CODE BLOCK]
Masalah: npx Tidak Ditemukan
Gejala
- Error: "npx: command not found"
- MCP server gagal dimulai
Solusi
1. Pasang Node.js 18+:
   - macOS:  atau unduh dari <https://nodejs.org>
   - Linux: 
   - Windows: unduh dari <https://nodejs.org>
2. Mulai ulang terminal setelah pasang
3. Verifikasi: 
Masalah: SYNAPSEURL Tidak Dapat Dijangkau
Gejala
- MCP server dimulai tetapi panggilan alat timeout
- Error: "fetch failed" atau "ECONNREFUSED"
Solusi
1. Tes konektivitas:
   [CODE BLOCK]
2. Periksa firewall korporat — mungkin memblokir HTTPS keluar
3. Coba URL alternatif:
   - Produksi: 
   - MCP server: 
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:
   [CODE BLOCK]
2. Periksa konflik port — MCP server menggunakan port 13100 secara default
3. Bersihkan cache npx:
   [CODE BLOCK]
4. Perbarui ke versi terbaru:
   [CODE BLOCK]
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  di suatu tempat — beralih ke autentikasi header
2. Verifikasi  — 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. , bukan )
2. Verifikasi argumen — periksa skema input alat
3. Tes via API langsung:
   [CODE BLOCK]
4. Periksa health Synapse:
   [CODE BLOCK]
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 ()
   - Nama dan versi klien
   - Sistem operasi
   - Kutipan log yang relevan
   - Langkah reproduksi
Langkah Berikutnya
- Pengaturan Claude Desktop
- Pengaturan Claude Code
- API Errors