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:

   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:

   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:

   # 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:

   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:

   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:

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

4. Cập nhật lên phiên bản mới nhất:

   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:

   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:

   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
• Thiết lập Claude Code
• Lỗi API