{"title":"MCP Troubleshooting","slug":"troubleshooting","category":"mcp","summary":"Selesaikan masalah integrasi MCP umum — server tidak dimulai, alat tidak muncul, error autentikasi.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":556,"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":"id","translated":true,"requested_lang":"id","content_markdown":"\n# MCP Troubleshooting\n\nMasalah umum dan solusi saat mengintegrasikan Synapse MCP dengan klien LLM Anda.\n\n## Daftar Periksa Diagnostik Cepat\n\n1. ✅ Node.js 18+ terpasang? (`node --version`)\n2. ✅ Mind Key dimulai dengan `mk_`? (bukan JWT `eyJ...`)\n3. ✅ Synapse API dapat dijangkau? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key berfungsi? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ File konfigurasi adalah JSON yang valid? (tanpa koma berlebih, tanpa komentar)\n6. ✅ Klien dimulai ulang setelah perubahan konfigurasi?\n7. ✅ MCP server dimulai secara manual? (`npx -y synapse-mcp-api@latest`)\n\n## Masalah: Tidak Ada Alat yang Muncul di Klien\n\n### Gejala\n\n- Claude Desktop / Cursor / Continue menunjukkan 0 alat\n- Tidak ada ikon 🔌 atau entri \"synapse\" dalam daftar MCP server\n\n### Solusi\n\n1. **Mulai ulang klien sepenuhnya** — Cmd+Q di macOS (bukan hanya tutup jendela)\n2. **Periksa lokasi file konfigurasi**:\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. **Validasi JSON** — tempel konfigurasi ke \n4. **Periksa log klien** untuk error MCP:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **Jalankan MCP server secara manual** untuk melihat error startup:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Masalah: Error \"Mind Key invalid\"\n\n### Gejala\n\n- Alat muncul tetapi panggilan gagal dengan \"401 Unauthorized\"\n- Error: \"Mind Key fehlt oder ungültig\"\n\n### Solusi\n\n1. **Verifikasi format Mind Key** — dimulai dengan `mk_`, ~40 karakter\n2. **Tes langsung**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **Periksa env var diatur** — untuk transport stdio, env var harus dalam\n konfigurasi MCP server, bukan shell Anda\n4. **Dapatkan Mind Key baru**:\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## Masalah: npx Tidak Ditemukan\n\n### Gejala\n\n- Error: \"npx: command not found\"\n- MCP server gagal dimulai\n\n### Solusi\n\n1. **Pasang Node.js 18+**:\n - macOS: `brew install node` atau unduh dari \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: unduh dari \n2. **Mulai ulang terminal** setelah pasang\n3. **Verifikasi**: `node --version && npx --version`\n\n## Masalah: SYNAPSE_URL Tidak Dapat Dijangkau\n\n### Gejala\n\n- MCP server dimulai tetapi panggilan alat timeout\n- Error: \"fetch failed\" atau \"ECONNREFUSED\"\n\n### Solusi\n\n1. **Tes konektivitas**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Periksa firewall korporat** — mungkin memblokir HTTPS keluar\n3. **Coba URL alternatif**:\n - Produksi: `https://synapse.schaefer.zone`\n - MCP server: `https://synapse-mcp.schaefer.zone`\n4. **Untuk self-hosted**: pastikan instansi Synapse Anda berjalan dan dapat diakses\n\n## Masalah: MCP Server Crash\n\n### Gejala\n\n- MCP server keluar segera setelah dimulai\n- Log klien menunjukkan \"MCP server disconnected\"\n\n### Solusi\n\n1. **Jalankan secara manual untuk melihat error**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Periksa konflik port** — MCP server menggunakan port 13100 secara default\n3. **Bersihkan cache npx**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **Perbarui ke versi terbaru**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Masalah: Panggilan Alat Mengembalikan 429\n\n### Gejala\n\n- Error: \"Rate limit exceeded\"\n\n### Solusi\n\nIni seharusnya tidak terjadi dengan MCP (menggunakan autentikasi header, tanpa rate limit). Jika terjadi:\n\n1. **Periksa jika Anda menggunakan `?key=` di suatu tempat** — beralih ke autentikasi header\n2. **Verifikasi `SYNAPSE_URL`** — pastikan menunjuk ke instansi yang benar\n3. **Hubungi support** jika masalah berlanjut\n\n## Masalah: Alat Muncul tetapi Tidak Berfungsi\n\n### Gejala\n\n- Alat terdaftar di klien\n- Memanggil alat mengembalikan error atau tidak ada hasil\n\n### Solusi\n\n1. **Periksa nama alat** — harus persis (mis. `memory_recall`, bukan `memory.recall`)\n2. **Verifikasi argumen** — periksa skema input alat\n3. **Tes via API langsung**:\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. **Periksa health Synapse**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Mendapatkan Bantuan\n\nJika tidak ada di atas yang menyelesaikan masalah Anda:\n\n1. **Periksa issue yang ada**: \n2. **Buka issue baru** dengan:\n - Versi MCP server (`npx -y synapse-mcp-api@latest --version`)\n - Nama dan versi klien\n - Sistem operasi\n - Kutipan log yang relevan\n - Langkah reproduksi\n\n## Langkah Berikutnya\n\n- [Pengaturan Claude Desktop](/docs/mcp/claude-desktop)\n- [Pengaturan Claude Code](/docs/mcp/claude-code)\n- [API Errors](/docs/api/errors)\n","content_html":"

MCP Troubleshooting

\n

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

\n

Daftar Periksa Diagnostik Cepat

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

Masalah: Tidak Ada Alat yang Muncul di Klien

\n

Gejala

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

Solusi

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

Masalah: Error "Mind Key invalid"

\n

Gejala

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

Solusi

\n
    \n
  1. Verifikasi format Mind Key — dimulai dengan mk_, ~40 karakter
    2. \n
  2. Tes langsung:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  3. Periksa env var diatur — untuk transport stdio, env var harus dalam\nkonfigurasi MCP server, bukan shell Anda
    4. \n
  4. Dapatkan Mind Key baru:
    # 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

Masalah: npx Tidak Ditemukan

\n

Gejala

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

Solusi

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

Masalah: SYNAPSE_URL Tidak Dapat Dijangkau

\n

Gejala

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

Solusi

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

Masalah: MCP Server Crash

\n

Gejala

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

Solusi

\n
    \n
  1. Jalankan secara manual untuk melihat error:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Periksa konflik port — MCP server menggunakan port 13100 secara default
    3. \n
  3. Bersihkan cache npx:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. Perbarui ke versi terbaru:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

Masalah: Panggilan Alat Mengembalikan 429

\n

Gejala

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

Solusi

\n

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

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

Masalah: Alat Muncul tetapi Tidak Berfungsi

\n

Gejala

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

Solusi

\n
    \n
  1. Periksa nama alat — harus persis (mis. memory_recall, bukan memory.recall)
    2. \n
  2. Verifikasi argumen — periksa skema input alat
    3. \n
  3. Tes via API langsung:
    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. Periksa health Synapse:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Mendapatkan Bantuan

\n

Jika tidak ada di atas yang menyelesaikan masalah Anda:

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

Langkah Berikutnya

\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"]}