การแก้ปัญหา MCP

ปัญหาและวิธีแก้ทั่วไปเมื่อผสานรวม Synapse MCP กับ LLM client ของคุณ

Checklist Diagnostic ด่วน

1. ✅ ติดตั้ง Node.js 18+? (node --version)
2. ✅ Mind Key ขึ้นต้นด้วย mk_? (ไม่ใช่ JWT eyJ...)
3. ✅ เข้าถึง Synapse API ได้? (curl https://synapse.schaefer.zone/health)
4. ✅ Mind Key ทำงาน? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
5. ✅ Config file เป็น JSON ที่ถูกต้อง? (ไม่มี trailing comma, ไม่มี comment)
6. ✅ รีสตาร์ท client หลังเปลี่ยน config?
7. ✅ MCP server เริ่มด้วยตนเอง? (npx -y synapse-mcp-api@latest)

ปัญหา: ไม่มี tool ปรากฏใน Client

อาการ

• Claude Desktop / Cursor / Continue แสดง 0 tool
• ไม่มีไอคอน 🔌 หรือรายการ "synapse" ในรายการ MCP server

วิธีแก้

1. รีสตาร์ท client ให้เต็มรูปแบบ — Cmd+Q บน macOS (ไม่ใช่แค่ปิดหน้าต่าง)
2. ตรวจตำแหน่ง config file:
   • 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. ตรวจ JSON ให้ถูกต้อง — วาง config ใน https://jsonlint.com
4. ตรวจ log client หา error MCP:
   • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. รัน MCP server ด้วยตนเอง เพื่อดู startup error:

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

ปัญหา: Error "Mind Key invalid"

อาการ

• tool ปรากฏแต่การเรียกล้มเหลวด้วย "401 Unauthorized"
• Error: "Mind Key fehlt oder ungültig"

วิธีแก้

1. ตรวจรูปแบบ Mind Key — ขึ้นต้นด้วย mk_, ~40 ตัวอักษร
2. ทดสอบโดยตรง:

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

3. ตรวจ env var ตั้งแล้ว — สำหรับ transport stdio, env var ต้องอยู่ใน MCP server config, ไม่ใช่ shell ของคุณ
4. รับ Mind Key ใหม่:

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

ปัญหา: ไม่พบ npx

อาการ

• Error: "npx: command not found"
• MCP server ล้มเหลวตอนเริ่ม

วิธีแก้

1. ติดตั้ง Node.js 18+:
   • macOS: brew install node หรือดาวน์โหลดจาก https://nodejs.org
   • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows: ดาวน์โหลดจาก https://nodejs.org
2. รีสตาร์ท terminal หลังติดตั้ง
3. ตรวจสอบ: node --version && npx --version

ปัญหา: SYNAPSE_URL เข้าถึงไม่ได้

อาการ

• MCP server เริ่มแต่การเรียก tool หมดเวลา
• Error: "fetch failed" หรือ "ECONNREFUSED"

วิธีแก้

1. ทดสอบการเชื่อมต่อ:

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

2. ตรวจ corporate firewall — อาจบล็อก HTTPS ขาออก
3. ลอง URL ทางเลือก:
   • Production: https://synapse.schaefer.zone
   • MCP server: https://synapse-mcp.schaefer.zone
4. สำหรับ self-hosted: ตรวจว่า instance Synapse ของคุณรันและเข้าถึงได้

ปัญหา: MCP Server Crash

อาการ

• MCP server ออกทันทีหลังเริ่ม
• Log client แสดง "MCP server disconnected"

วิธีแก้

1. รันด้วยตนเองเพื่อดู error:

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

2. ตรวจ conflict port — MCP server ใช้ port 13100 โดยค่าเริ่มต้น
3. ล้าง npx cache:

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

4. อัปเดตเป็นเวอร์ชันล่าสุด:

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

ปัญหา: การเรียก Tool ส่งกลับ 429

อาการ

• Error: "Rate limit exceeded"

วิธีแก้

สิ่งนี้ไม่ควรเกิดกับ MCP (ใช้ header auth, ไม่จำกัดอัตรา) หากเกิด:

1. ตรวจว่าคุณใช้ ?key= ที่ไหน — เปลี่ยนเป็น header auth
2. ตรวจ SYNAPSE_URL — ตรวจให้แน่ใจว่าชี้ไปยัง instance ที่ถูกต้อง
3. ติดต่อ support หากปัญหายังคงอยู่

ปัญหา: Tool ปรากฏแต่ไม่ทำงาน

อาการ

• tool อยู่ในรายการ client
• การเรียก tool ส่งกลับ error หรือไม่มีผลลัพธ์

วิธีแก้

1. ตรวจชื่อ tool — ต้องตรง (เช่น memory_recall, ไม่ใช่ memory.recall)
2. ตรวจ arguments — ตรวจ input schema ของ tool
3. ทดสอบผ่าน API โดยตรง:

   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. ตรวจสุขภาพ Synapse:

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

การขอความช่วยเหลือ

หากไม่มีวิธีข้างต้นแก้ปัญหาของคุณ:

1. ตรวจ issue ที่มี: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
2. เปิด issue ใหม่ พร้อม:
   • เวอร์ชัน MCP server (npx -y synapse-mcp-api@latest --version)
   • ชื่อและเวอร์ชัน client
   • ระบบปฏิบัติการ
   • ส่วนที่เกี่ยวข้องของ log
   • ขั้นตอนการ reproduce

ขั้นตอนถัดไป

• Claude Desktop Setup
• Claude Code Setup
• API Errors