spawn npx ENOENT và 9 lỗi MCP server hay gặp: cách sửa

Bạn thêm một MCP server vào config, khởi động lại app, và không có gì xuất hiện. Hoặc server hiện lên rồi chết với dòng MCP error -32000: Connection closed.

Một dev đã gặp bốn lỗi này trong cùng một tuần, rồi đối chiếu changelog của Claude Code, khoảng 20 issue đang mở trên repo anthropics/claude-code, tài liệu debug MCP và các thread Reddit, Stack Overflow để viết thành hướng dẫn. Dưới đây là phần cốt lõi, dành cho dev Việt hay bị kẹt ở bước cấu hình.

Bốn thao tác xử lý 80% ca hỏng

Trước khi tra một mã lỗi cụ thể, tác giả khuyên làm đủ bốn việc sau:

1. Thoát hẳn client rồi mở lại. Cmd+Q trên macOS; trên Windows chuột phải icon ở khay hệ thống rồi chọn Quit. Đóng cửa sổ là chưa đủ — config chỉ nạp lại khi khởi động nguội.
2. Đưa file config qua một JSON linter. Thiếu một dấu phẩy, một dấu backslash Windows chưa escape, hoặc sai key cấp cao nhất là hỏng cả file — không có hộp thoại báo lỗi, không server nào đăng ký được.
3. Thay npx trần bằng đường dẫn tuyệt đối. Trên Mac/Linux chạy which npx rồi dán nguyên đường dẫn. Trên Windows dùng cmd /c npx hoặc trỏ thẳng vào node.exe.
4. Đọc log. Mac: tail -F ~/Library/Logs/Claude/mcp*.log. Windows: %APPDATA%\Claude\logs\. Với Claude Code CLI: chạy claude --debug=mcp rồi đọc file trong ~/.claude/debug/.

spawn npx ENOENT: vì sao terminal chạy được mà app thì không

Theo bài viết, spawn npx ENOENT là lỗi cài đặt số một và xuất hiện trong hơn 30 repo MCP. Nguyên nhân không nằm ở MCP mà nằm ở PATH.

Shell của bạn (zsh, bash) nạp ~/.zshrc hoặc ~/.bashrc khi khởi động, và đó chính là chỗ nvm thêm thư mục bin của nó vào PATH. Nên npx chạy ngon trong terminal. Nhưng app GUI như Claude Desktop không nạp các file shell đó: nó khởi động với một PATH tối thiểu /usr/bin:/bin:/usr/sbin:/sbin, không có nvm, mise, fnm hay Homebrew. Lời gọi child_process.spawn vì thế thất bại với ENOENT — viết tắt của "Error NO ENTity", nghĩa là file không tồn tại.

Hai cách sửa: dán đường dẫn tuyệt đối lấy từ which npx vào trường command trong config, hoặc thêm block env riêng cho từng server để cấp một PATH dùng được cho tiến trình con.

Điểm này đáng nhớ với anh em dùng nvm ở Việt Nam: bản thân phiên bản Node không sai, chỉ là app GUI không nhìn thấy nó. Cùng một nguyên nhân sẽ tái diễn với mọi trình quản lý phiên bản, không riêng nvm.

Mười mã lỗi được đặt tên

Hướng dẫn liệt kê mười lỗi kèm đúng chuỗi ký tự bạn nhìn thấy trên màn hình:

• MCP error -32000: Connection closed
• MCP error -32001: Request timed out
• spawn npx ENOENT
• spawn EINVAL (chỉ trên Windows)
• Server transport closed unexpectedly
• Could not attach to MCP server
• -32601 Method not found
• -32602 Invalid params
• Failed to connect khi chạy claude mcp list
• Lỗi OAuth 401 / authorization với MCP server

Bài cũng nêu một cái bẫy riêng của Windows đáng chú ý: bản Claude Desktop cài qua MSIX / Microsoft Store dùng đường dẫn ảo hoá, khiến bạn mở nhầm file config mà vẫn tưởng đang sửa đúng file. Nếu bạn sửa mãi mà không thấy thay đổi gì, hãy kiểm tra đúng chỗ này trước.

Nên làm gì tiếp

Nếu MCP server của bạn đang không kết nối, chạy tuần tự bốn bước ở trên trước khi tra mã lỗi — theo tác giả, chúng giải quyết phần lớn trường hợp. Riêng với Request timed out, hãy đọc log trước khi nghĩ đến chuyện tăng thời gian chờ — bước 4 ở trên tồn tại chính vì lý do đó.