# Khắc phục sự cố MCP SUMMARY: Giải quyết vấn đề tích hợp MCP phổ biến — server không khởi động, công cụ không xuất hiện, lỗi xác thực. KEY CONTEXT: Common issues: 1. Node.js < 18 → upgrade to 18+ 2. Mind Key invalid → check format (mk_...), get fresh via POST /minds 3. npx not found → install Node.js 4. Tools not appearing → restart client, check config JSON validity 5. SYNAPSE_URL unreachable → curl /health to verify 6. MCP server crashes → check logs, run npx manually to see error Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/ 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? () 2. ✅ Mind Key bắt đầu bằng ? (không phải JWT ) 3. ✅ Synapse API có thể truy cập? () 4. ✅ Mind Key hoạt động? () 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? () 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: - Claude Desktop Windows: - Cursor: - Continue: 3. Xác thực JSON — dán cấu hình vào 4. Kiểm tra nhật ký client cho lỗi MCP: - Claude Desktop: (macOS) - Cursor: View → Output → MCP 5. Chạy MCP server thủ công để xem lỗi khởi động: [CODE BLOCK] 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 , 40 ký tự 2. Kiểm tra trực tiếp: [CODE BLOCK] 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: [CODE BLOCK] 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: hoặc tải từ - Linux: - Windows: tải từ 2. Khởi động lại terminal sau khi cài đặt 3. Xác minh: Vấn đề: SYNAPSEURL 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: [CODE BLOCK] 2. Kiểm tra tường lửa công ty — có thể chặn HTTPS outbound 3. Thử URL thay thế: - Production: - MCP server: 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: [CODE BLOCK] 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: [CODE BLOCK] 4. Cập nhật lên phiên bản mới nhất: [CODE BLOCK] 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 ở đâu không — chuyển sang xác thực header 2. Xác minh — đả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ụ , không phải ) 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: [CODE BLOCK] 4. Kiểm tra sức khỏe Synapse: [CODE BLOCK] 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ó: 2. Mở issue mới với: - Phiên bản MCP server () - 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