# Khắc phục sự cố MCP

Vấn đề và giải pháp phổ biến khi tích hợp Synapse MCP với LLM client của bạn.

## Danh sách chẩn đoán nhanh

1. ✅ Node.js 18+ đã cài đặt? (`node --version`)
2. ✅ Mind Key bắt đầu bằng `mk_`? (không phải JWT `eyJ...`)
3. ✅ Synapse API có thể truy cập? (`curl https://synapse.schaefer.zone/health`)
4. ✅ Mind Key hoạt động? (`curl -H "Authorization: Bearer mk_..." .../memory/recall`)
5. ✅ Tệp cấu hình là JSON hợp lệ? (không có dấu phẩy cuối, không có bình luận)
6. ✅ Client đã khởi động lại sau thay đổi cấu hình?
7. ✅ MCP server khởi động thủ công? (`npx -y synapse-mcp-api@latest`)

## Vấn đề: Không có công cụ xuất hiện trong Client

### Triệu chứng

- Claude Desktop / Cursor / Continue hiển thị 0 công cụ
- Không có biểu tượng 🔌 hoặc mục "synapse" trong danh sách MCP server

### Giải pháp

1. **Khởi động lại client hoàn toàn** — Cmd+Q trên macOS (không chỉ đóng cửa sổ)
2. **Kiểm tra vị trí tệp cấu hình**:
   - 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. **Xác thực JSON** — dán cấu hình vào <https://jsonlint.com>
4. **Kiểm tra nhật ký client** cho lỗi MCP:
   - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)
   - Cursor: View → Output → MCP
5. **Chạy MCP server thủ công** để xem lỗi khởi động:
   ```bash
   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
   ```

## Vấn đề: Lỗi "Mind Key invalid"

### Triệu chứng

- Công cụ xuất hiện nhưng lệnh gọi thất bại với "401 Unauthorized"
- Lỗi: "Mind Key fehlt oder ungültig"

### Giải pháp

1. **Xác minh định dạng Mind Key** — bắt đầu bằng `mk_`, ~40 ký tự
2. **Kiểm tra trực tiếp**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **Kiểm tra biến môi trường được đặt** — cho transport stdio, biến môi trường phải trong cấu hình MCP server, không phải shell của bạn
4. **Lấy Mind Key mới**:
   ```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"}'
   ```

## Vấn đề: npx Không tìm thấy

### Triệu chứng

- Lỗi: "npx: command not found"
- MCP server thất bại khi khởi động

### Giải pháp

1. **Cài đặt Node.js 18+**:
   - macOS: `brew install node` hoặc tải từ <https://nodejs.org>
   - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`
   - Windows: tải từ <https://nodejs.org>
2. **Khởi động lại terminal** sau khi cài đặt
3. **Xác minh**: `node --version && npx --version`

## Vấn đề: SYNAPSE_URL Không thể truy cập

### Triệu chứng

- MCP server khởi động nhưng lệnh gọi công cụ hết thời gian chờ
- Lỗi: "fetch failed" hoặc "ECONNREFUSED"

### Giải pháp

1. **Kiểm tra kết nối**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```
2. **Kiểm tra tường lửa công ty** — có thể chặn HTTPS outbound
3. **Thử URL thay thế**:
   - Production: `https://synapse.schaefer.zone`
   - MCP server: `https://synapse-mcp.schaefer.zone`
4. **Cho tự lưu trữ**: đảm bảo thể hiện Synapse của bạn đang chạy và có thể truy cập

## Vấn đề: MCP Server Sập

### Triệu chứng

- MCP server thoát ngay sau khi khởi động
- Nhật ký client hiển thị "MCP server disconnected"

### Giải pháp

1. **Chạy thủ công để xem lỗi**:
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **Kiểm tra xung đột cổng** — MCP server sử dụng cổng 13100 mặc định
3. **Xóa bộ nhớ đệm npx**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Cập nhật lên phiên bản mới nhất**:
   ```bash
   npx -y synapse-mcp-api@latest --version
   ```

## Vấn đề: Lệnh gọi công cụ trả về 429

### Triệu chứng

- Lỗi: "Rate limit exceeded"

### Giải pháp

Điều này không nên xảy ra với MCP (sử dụng xác thực header, không giới hạn tốc
độ). Nếu xảy ra:

1. **Kiểm tra xem bạn có đang dùng `?key=` ở đâu không** — chuyển sang xác thực header
2. **Xác minh `SYNAPSE_URL`** — đảm bảo nó trỏ đến thể hiện đúng
3. **Liên hệ hỗ trợ** nếu vấn đề tiếp tục

## Vấn đề: Công cụ xuất hiện nhưng không hoạt động

### Triệu chứng

- Công cụ được liệt kê trong client
- Gọi công cụ trả về lỗi hoặc không có kết quả

### Giải pháp

1. **Kiểm tra tên công cụ** — phải chính xác (ví dụ `memory_recall`, không phải `memory.recall`)
2. **Xác minh đối số** — kiểm tra schema đầu vào của công cụ
3. **Kiểm tra qua API trực tiếp**:
   ```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. **Kiểm tra sức khỏe Synapse**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```

## Nhận trợ giúp

Nếu không có giải pháp nào ở trên giải quyết vấn đề của bạn:

1. **Kiểm tra issue hiện có**: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. **Mở issue mới** với:
   - Phiên bản MCP server (`npx -y synapse-mcp-api@latest --version`)
   - Tên và phiên bản client
   - Hệ điều hành
   - Trích đoạn nhật ký liên quan
   - Các bước tái hiện

## Bước tiếp theo

- [Thiết lập Claude Desktop](/docs/mcp/claude-desktop)
- [Thiết lập Claude Code](/docs/mcp/claude-code)
- [Lỗi API](/docs/api/errors)