# 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:
   ```bash
   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**:
   ```bash
   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**:
   ```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"}'
   ```

## 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**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Perbarui ke versi terbaru**:
   ```bash
   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**:
   ```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. **Periksa health Synapse**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [Pengaturan Claude Code](/docs/mcp/claude-code)
- [API Errors](/docs/api/errors)