{"title":"การแก้ปัญหา MCP","slug":"troubleshooting","category":"mcp","summary":"แก้ปัญหา integration MCP ทั่วไป — server ไม่เริ่ม, tool ไม่ปรากฏ, error auth","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":451,"read_minutes":2,"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":"th","translated":true,"requested_lang":"th","content_markdown":"\n# การแก้ปัญหา MCP\n\nปัญหาและวิธีแก้ทั่วไปเมื่อผสานรวม Synapse MCP กับ LLM client ของคุณ\n\n## Checklist Diagnostic ด่วน\n\n1. ✅ ติดตั้ง Node.js 18+? (`node --version`)\n2. ✅ Mind Key ขึ้นต้นด้วย `mk_`? (ไม่ใช่ JWT `eyJ...`)\n3. ✅ เข้าถึง Synapse API ได้? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key ทำงาน? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Config file เป็น JSON ที่ถูกต้อง? (ไม่มี trailing comma, ไม่มี comment)\n6. ✅ รีสตาร์ท client หลังเปลี่ยน config?\n7. ✅ MCP server เริ่มด้วยตนเอง? (`npx -y synapse-mcp-api@latest`)\n\n## ปัญหา: ไม่มี tool ปรากฏใน Client\n\n### อาการ\n\n- Claude Desktop / Cursor / Continue แสดง 0 tool\n- ไม่มีไอคอน 🔌 หรือรายการ \"synapse\" ในรายการ MCP server\n\n### วิธีแก้\n\n1. **รีสตาร์ท client ให้เต็มรูปแบบ** — Cmd+Q บน macOS (ไม่ใช่แค่ปิดหน้าต่าง)\n2. **ตรวจตำแหน่ง config file**:\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. **ตรวจ JSON ให้ถูกต้อง** — วาง config ใน \n4. **ตรวจ log client** หา error MCP:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **รัน MCP server ด้วยตนเอง** เพื่อดู startup error:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## ปัญหา: Error \"Mind Key invalid\"\n\n### อาการ\n\n- tool ปรากฏแต่การเรียกล้มเหลวด้วย \"401 Unauthorized\"\n- Error: \"Mind Key fehlt oder ungültig\"\n\n### วิธีแก้\n\n1. **ตรวจรูปแบบ Mind Key** — ขึ้นต้นด้วย `mk_`, ~40 ตัวอักษร\n2. **ทดสอบโดยตรง**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **ตรวจ env var ตั้งแล้ว** — สำหรับ transport stdio, env var ต้องอยู่ใน MCP server config, ไม่ใช่ shell ของคุณ\n4. **รับ Mind Key ใหม่**:\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## ปัญหา: ไม่พบ npx\n\n### อาการ\n\n- Error: \"npx: command not found\"\n- MCP server ล้มเหลวตอนเริ่ม\n\n### วิธีแก้\n\n1. **ติดตั้ง Node.js 18+**:\n - macOS: `brew install node` หรือดาวน์โหลดจาก \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: ดาวน์โหลดจาก \n2. **รีสตาร์ท terminal** หลังติดตั้ง\n3. **ตรวจสอบ**: `node --version && npx --version`\n\n## ปัญหา: SYNAPSE_URL เข้าถึงไม่ได้\n\n### อาการ\n\n- MCP server เริ่มแต่การเรียก tool หมดเวลา\n- Error: \"fetch failed\" หรือ \"ECONNREFUSED\"\n\n### วิธีแก้\n\n1. **ทดสอบการเชื่อมต่อ**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **ตรวจ corporate firewall** — อาจบล็อก HTTPS ขาออก\n3. **ลอง URL ทางเลือก**:\n - Production: `https://synapse.schaefer.zone`\n - MCP server: `https://synapse-mcp.schaefer.zone`\n4. **สำหรับ self-hosted**: ตรวจว่า instance Synapse ของคุณรันและเข้าถึงได้\n\n## ปัญหา: MCP Server Crash\n\n### อาการ\n\n- MCP server ออกทันทีหลังเริ่ม\n- Log client แสดง \"MCP server disconnected\"\n\n### วิธีแก้\n\n1. **รันด้วยตนเองเพื่อดู error**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **ตรวจ conflict port** — MCP server ใช้ port 13100 โดยค่าเริ่มต้น\n3. **ล้าง npx cache**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **อัปเดตเป็นเวอร์ชันล่าสุด**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## ปัญหา: การเรียก Tool ส่งกลับ 429\n\n### อาการ\n\n- Error: \"Rate limit exceeded\"\n\n### วิธีแก้\n\nสิ่งนี้ไม่ควรเกิดกับ MCP (ใช้ header auth, ไม่จำกัดอัตรา) หากเกิด:\n\n1. **ตรวจว่าคุณใช้ `?key=` ที่ไหน** — เปลี่ยนเป็น header auth\n2. **ตรวจ `SYNAPSE_URL`** — ตรวจให้แน่ใจว่าชี้ไปยัง instance ที่ถูกต้อง\n3. **ติดต่อ support** หากปัญหายังคงอยู่\n\n## ปัญหา: Tool ปรากฏแต่ไม่ทำงาน\n\n### อาการ\n\n- tool อยู่ในรายการ client\n- การเรียก tool ส่งกลับ error หรือไม่มีผลลัพธ์\n\n### วิธีแก้\n\n1. **ตรวจชื่อ tool** — ต้องตรง (เช่น `memory_recall`, ไม่ใช่ `memory.recall`)\n2. **ตรวจ arguments** — ตรวจ input schema ของ tool\n3. **ทดสอบผ่าน API โดยตรง**:\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. **ตรวจสุขภาพ Synapse**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## การขอความช่วยเหลือ\n\nหากไม่มีวิธีข้างต้นแก้ปัญหาของคุณ:\n\n1. **ตรวจ issue ที่มี**: \n2. **เปิด issue ใหม่** พร้อม:\n - เวอร์ชัน MCP server (`npx -y synapse-mcp-api@latest --version`)\n - ชื่อและเวอร์ชัน client\n - ระบบปฏิบัติการ\n - ส่วนที่เกี่ยวข้องของ log\n - ขั้นตอนการ reproduce\n\n## ขั้นตอนถัดไป\n\n- [Claude Desktop Setup](/docs/mcp/claude-desktop)\n- [Claude Code Setup](/docs/mcp/claude-code)\n- [API Errors](/docs/api/errors)\n","content_html":"

การแก้ปัญหา MCP

\n

ปัญหาและวิธีแก้ทั่วไปเมื่อผสานรวม Synapse MCP กับ LLM client ของคุณ

\n

Checklist Diagnostic ด่วน

\n
    \n
  1. ✅ ติดตั้ง Node.js 18+? (node --version)
    2. \n
  2. ✅ Mind Key ขึ้นต้นด้วย mk_? (ไม่ใช่ JWT eyJ...)
    3. \n
  3. ✅ เข้าถึง Synapse API ได้? (curl https://synapse.schaefer.zone/health)
    4. \n
  4. ✅ Mind Key ทำงาน? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
    5. \n
  5. ✅ Config file เป็น JSON ที่ถูกต้อง? (ไม่มี trailing comma, ไม่มี comment)
    6. \n
  6. ✅ รีสตาร์ท client หลังเปลี่ยน config?
    7. \n
  7. ✅ MCP server เริ่มด้วยตนเอง? (npx -y synapse-mcp-api@latest)
    8. \n
\n

ปัญหา: ไม่มี tool ปรากฏใน Client

\n

อาการ

\n
    \n
  • Claude Desktop / Cursor / Continue แสดง 0 tool
    • \n
  • ไม่มีไอคอน 🔌 หรือรายการ "synapse" ในรายการ MCP server
    • \n
\n

วิธีแก้

\n
    \n
  1. รีสตาร์ท client ให้เต็มรูปแบบ — Cmd+Q บน macOS (ไม่ใช่แค่ปิดหน้าต่าง)
    2. \n
  2. ตรวจตำแหน่ง config file:
      \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. ตรวจ JSON ให้ถูกต้อง — วาง config ใน https://jsonlint.com
    4. \n
  4. ตรวจ log client หา error MCP:
      \n
    • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
      • \n
    • Cursor: View → Output → MCP
      • \n
    \n
    5. \n
  5. รัน MCP server ด้วยตนเอง เพื่อดู startup error:
    SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
    6. \n
\n

ปัญหา: Error "Mind Key invalid"

\n

อาการ

\n
    \n
  • tool ปรากฏแต่การเรียกล้มเหลวด้วย "401 Unauthorized"
    • \n
  • Error: "Mind Key fehlt oder ungültig"
    • \n
\n

วิธีแก้

\n
    \n
  1. ตรวจรูปแบบ Mind Key — ขึ้นต้นด้วย mk_, ~40 ตัวอักษร
    2. \n
  2. ทดสอบโดยตรง:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  3. ตรวจ env var ตั้งแล้ว — สำหรับ transport stdio, env var ต้องอยู่ใน MCP server config, ไม่ใช่ shell ของคุณ
    4. \n
  4. รับ Mind Key ใหม่:
    # 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

ปัญหา: ไม่พบ npx

\n

อาการ

\n
    \n
  • Error: "npx: command not found"
    • \n
  • MCP server ล้มเหลวตอนเริ่ม
    • \n
\n

วิธีแก้

\n
    \n
  1. ติดตั้ง Node.js 18+:
      \n
    • macOS: brew install node หรือดาวน์โหลดจาก https://nodejs.org
      • \n
    • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
      • \n
    • Windows: ดาวน์โหลดจาก https://nodejs.org
      • \n
    \n
    2. \n
  2. รีสตาร์ท terminal หลังติดตั้ง
    3. \n
  3. ตรวจสอบ: node --version && npx --version
    4. \n
\n

ปัญหา: SYNAPSE_URL เข้าถึงไม่ได้

\n

อาการ

\n
    \n
  • MCP server เริ่มแต่การเรียก tool หมดเวลา
    • \n
  • Error: "fetch failed" หรือ "ECONNREFUSED"
    • \n
\n

วิธีแก้

\n
    \n
  1. ทดสอบการเชื่อมต่อ:
    curl https://synapse.schaefer.zone/health
    2. \n
  2. ตรวจ corporate firewall — อาจบล็อก HTTPS ขาออก
    3. \n
  3. ลอง URL ทางเลือก:
      \n
    • Production: https://synapse.schaefer.zone
      • \n
    • MCP server: https://synapse-mcp.schaefer.zone
      • \n
    \n
    4. \n
  4. สำหรับ self-hosted: ตรวจว่า instance Synapse ของคุณรันและเข้าถึงได้
    5. \n
\n

ปัญหา: MCP Server Crash

\n

อาการ

\n
    \n
  • MCP server ออกทันทีหลังเริ่ม
    • \n
  • Log client แสดง "MCP server disconnected"
    • \n
\n

วิธีแก้

\n
    \n
  1. รันด้วยตนเองเพื่อดู error:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. ตรวจ conflict port — MCP server ใช้ port 13100 โดยค่าเริ่มต้น
    3. \n
  3. ล้าง npx cache:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. อัปเดตเป็นเวอร์ชันล่าสุด:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

ปัญหา: การเรียก Tool ส่งกลับ 429

\n

อาการ

\n
    \n
  • Error: "Rate limit exceeded"
    • \n
\n

วิธีแก้

\n

สิ่งนี้ไม่ควรเกิดกับ MCP (ใช้ header auth, ไม่จำกัดอัตรา) หากเกิด:

\n
    \n
  1. ตรวจว่าคุณใช้ ?key= ที่ไหน — เปลี่ยนเป็น header auth
    2. \n
  2. ตรวจ SYNAPSE_URL — ตรวจให้แน่ใจว่าชี้ไปยัง instance ที่ถูกต้อง
    3. \n
  3. ติดต่อ support หากปัญหายังคงอยู่
    4. \n
\n

ปัญหา: Tool ปรากฏแต่ไม่ทำงาน

\n

อาการ

\n
    \n
  • tool อยู่ในรายการ client
    • \n
  • การเรียก tool ส่งกลับ error หรือไม่มีผลลัพธ์
    • \n
\n

วิธีแก้

\n
    \n
  1. ตรวจชื่อ tool — ต้องตรง (เช่น memory_recall, ไม่ใช่ memory.recall)
    2. \n
  2. ตรวจ arguments — ตรวจ input schema ของ tool
    3. \n
  3. ทดสอบผ่าน API โดยตรง:
    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. ตรวจสุขภาพ Synapse:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

การขอความช่วยเหลือ

\n

หากไม่มีวิธีข้างต้นแก้ปัญหาของคุณ:

\n
    \n
  1. ตรวจ issue ที่มี: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
    2. \n
  2. เปิด issue ใหม่ พร้อม:
      \n
    • เวอร์ชัน MCP server (npx -y synapse-mcp-api@latest --version)
      • \n
    • ชื่อและเวอร์ชัน client
      • \n
    • ระบบปฏิบัติการ
      • \n
    • ส่วนที่เกี่ยวข้องของ log
      • \n
    • ขั้นตอนการ reproduce
      • \n
    \n
    3. \n
\n

ขั้นตอนถัดไป

\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"]}