# การแก้ปัญหา 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:
   ```bash
   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. **ทดสอบโดยตรง**:
   ```bash
   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 ใหม่**:
   ```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"}'
   ```

## ปัญหา: ไม่พบ 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. **ทดสอบการเชื่อมต่อ**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **อัปเดตเป็นเวอร์ชันล่าสุด**:
   ```bash
   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 โดยตรง**:
   ```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. **ตรวจสุขภาพ Synapse**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [Claude Code Setup](/docs/mcp/claude-code)
- [API Errors](/docs/api/errors)