{"title":"Khắc phục sự cố MCP","slug":"troubleshooting","category":"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.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":741,"read_minutes":4,"llm_context":"Common issues:\n1. Node.js < 18 → upgrade to 18+\n2. Mind Key invalid → check format (mk_...), get fresh via POST /minds\n3. npx not found → install Node.js\n4. Tools not appearing → restart client, check config JSON validity\n5. SYNAPSE_URL unreachable → curl /health to verify\n6. MCP server crashes → check logs, run npx manually to see error\nDebug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr\nLogs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/\n","lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Khắc phục sự cố MCP\n\nVấn đề và giải pháp phổ biến khi tích hợp Synapse MCP với LLM client của bạn.\n\n## Danh sách chẩn đoán nhanh\n\n1. ✅ Node.js 18+ đã cài đặt? (`node --version`)\n2. ✅ Mind Key bắt đầu bằng `mk_`? (không phải JWT `eyJ...`)\n3. ✅ Synapse API có thể truy cập? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key hoạt động? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ 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)\n6. ✅ Client đã khởi động lại sau thay đổi cấu hình?\n7. ✅ MCP server khởi động thủ công? (`npx -y synapse-mcp-api@latest`)\n\n## Vấn đề: Không có công cụ xuất hiện trong Client\n\n### Triệu chứng\n\n- Claude Desktop / Cursor / Continue hiển thị 0 công cụ\n- Không có biểu tượng 🔌 hoặc mục \"synapse\" trong danh sách MCP server\n\n### Giải pháp\n\n1. **Khởi động lại client hoàn toàn** — Cmd+Q trên macOS (không chỉ đóng cửa sổ)\n2. **Kiểm tra vị trí tệp cấu hình**:\n - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Claude Desktop Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - Cursor: `~/.cursor/config.json`\n - Continue: `~/.continue/config.json`\n3. **Xác thực JSON** — dán cấu hình vào \n4. **Kiểm tra nhật ký client** cho lỗi MCP:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **Chạy MCP server thủ công** để xem lỗi khởi động:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Vấn đề: Lỗi \"Mind Key invalid\"\n\n### Triệu chứng\n\n- Công cụ xuất hiện nhưng lệnh gọi thất bại với \"401 Unauthorized\"\n- Lỗi: \"Mind Key fehlt oder ungültig\"\n\n### Giải pháp\n\n1. **Xác minh định dạng Mind Key** — bắt đầu bằng `mk_`, ~40 ký tự\n2. **Kiểm tra trực tiếp**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **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\n4. **Lấy Mind Key mới**:\n ```bash\n # Login to get JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Create new mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## Vấn đề: npx Không tìm thấy\n\n### Triệu chứng\n\n- Lỗi: \"npx: command not found\"\n- MCP server thất bại khi khởi động\n\n### Giải pháp\n\n1. **Cài đặt Node.js 18+**:\n - macOS: `brew install node` hoặc tải từ \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: tải từ \n2. **Khởi động lại terminal** sau khi cài đặt\n3. **Xác minh**: `node --version && npx --version`\n\n## Vấn đề: SYNAPSE_URL Không thể truy cập\n\n### Triệu chứng\n\n- MCP server khởi động nhưng lệnh gọi công cụ hết thời gian chờ\n- Lỗi: \"fetch failed\" hoặc \"ECONNREFUSED\"\n\n### Giải pháp\n\n1. **Kiểm tra kết nối**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Kiểm tra tường lửa công ty** — có thể chặn HTTPS outbound\n3. **Thử URL thay thế**:\n - Production: `https://synapse.schaefer.zone`\n - MCP server: `https://synapse-mcp.schaefer.zone`\n4. **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\n\n## Vấn đề: MCP Server Sập\n\n### Triệu chứng\n\n- MCP server thoát ngay sau khi khởi động\n- Nhật ký client hiển thị \"MCP server disconnected\"\n\n### Giải pháp\n\n1. **Chạy thủ công để xem lỗi**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Kiểm tra xung đột cổng** — MCP server sử dụng cổng 13100 mặc định\n3. **Xóa bộ nhớ đệm npx**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **Cập nhật lên phiên bản mới nhất**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Vấn đề: Lệnh gọi công cụ trả về 429\n\n### Triệu chứng\n\n- Lỗi: \"Rate limit exceeded\"\n\n### Giải pháp\n\nĐ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độ). Nếu xảy ra:\n\n1. **Kiểm tra xem bạn có đang dùng `?key=` ở đâu không** — chuyển sang xác thực header\n2. **Xác minh `SYNAPSE_URL`** — đảm bảo nó trỏ đến thể hiện đúng\n3. **Liên hệ hỗ trợ** nếu vấn đề tiếp tục\n\n## Vấn đề: Công cụ xuất hiện nhưng không hoạt động\n\n### Triệu chứng\n\n- Công cụ được liệt kê trong client\n- Gọi công cụ trả về lỗi hoặc không có kết quả\n\n### Giải pháp\n\n1. **Kiểm tra tên công cụ** — phải chính xác (ví dụ `memory_recall`, không phải `memory.recall`)\n2. **Xác minh đối số** — kiểm tra schema đầu vào của công cụ\n3. **Kiểm tra qua API trực tiếp**:\n ```bash\n curl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer mk_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\":\"fact\",\"key\":\"test\",\"content\":\"hello\"}'\n ```\n4. **Kiểm tra sức khỏe Synapse**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Nhận trợ giúp\n\nNếu không có giải pháp nào ở trên giải quyết vấn đề của bạn:\n\n1. **Kiểm tra issue hiện có**: \n2. **Mở issue mới** với:\n - Phiên bản MCP server (`npx -y synapse-mcp-api@latest --version`)\n - Tên và phiên bản client\n - Hệ điều hành\n - Trích đoạn nhật ký liên quan\n - Các bước tái hiện\n\n## Bước tiếp theo\n\n- [Thiết lập Claude Desktop](/docs/mcp/claude-desktop)\n- [Thiết lập Claude Code](/docs/mcp/claude-code)\n- [Lỗi API](/docs/api/errors)\n","content_html":"

Khắc phục sự cố MCP

\n

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.

\n

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

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

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

\n

Triệu chứng

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

Giải pháp

\n
    \n
  1. Khởi động lại client hoàn toàn — Cmd+Q trên macOS (không chỉ đóng cửa sổ)
    2. \n
  2. Kiểm tra vị trí tệp cấu hình:
      \n
    • Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
      • \n
    • Claude Desktop Windows: %APPDATA%\\Claude\\claude_desktop_config.json
      • \n
    • Cursor: ~/.cursor/config.json
      • \n
    • Continue: ~/.continue/config.json
      • \n
    \n
    3. \n
  3. Xác thực JSON — dán cấu hình vào https://jsonlint.com
    4. \n
  4. Kiểm tra nhật ký client cho lỗi MCP:
      \n
    • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
      • \n
    • Cursor: View → Output → MCP
      • \n
    \n
    5. \n
  5. Chạy MCP server thủ công để xem lỗi khởi động:
    SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
    6. \n
\n

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

\n

Triệu chứng

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

Giải pháp

\n
    \n
  1. Xác minh định dạng Mind Key — bắt đầu bằng mk_, ~40 ký tự
    2. \n
  2. Kiểm tra trực tiếp:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  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. \n
  4. Lấy Mind Key mới:
    # Login to get JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# Create new mind\ncurl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
    5. \n
\n

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

\n

Triệu chứng

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

Giải pháp

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

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

\n

Triệu chứng

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

Giải pháp

\n
    \n
  1. Kiểm tra kết nối:
    curl https://synapse.schaefer.zone/health
    2. \n
  2. Kiểm tra tường lửa công ty — có thể chặn HTTPS outbound
    3. \n
  3. Thử URL thay thế:
      \n
    • Production: https://synapse.schaefer.zone
      • \n
    • MCP server: https://synapse-mcp.schaefer.zone
      • \n
    \n
    4. \n
  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
    5. \n
\n

Vấn đề: MCP Server Sập

\n

Triệu chứng

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

Giải pháp

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

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

\n

Triệu chứng

\n
    \n
  • Lỗi: "Rate limit exceeded"
    • \n
\n

Giải pháp

\n

Đ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độ). Nếu xảy ra:

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

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

\n

Triệu chứng

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

Giải pháp

\n
    \n
  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. \n
  2. Xác minh đối số — kiểm tra schema đầu vào của công cụ
    3. \n
  3. Kiểm tra qua API trực tiếp:
    curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer mk_..." \\\n  -H "Content-Type: application/json" \\\n  -d '{"category":"fact","key":"test","content":"hello"}'
    4. \n
  4. Kiểm tra sức khỏe Synapse:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Nhận trợ giúp

\n

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

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

Bước tiếp theo

\n\n","urls":{"html":"/docs/mcp/troubleshooting","text":"/docs/mcp/troubleshooting?format=text","json":"/docs/mcp/troubleshooting?format=json","llm":"/docs/mcp/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}