{"title":"MCP 문제 해결","slug":"troubleshooting","category":"mcp","summary":"일반적인 MCP 통합 문제 해결 — 서버 시작 안 됨, 도구 나타나지 않음, 인증 오류.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":513,"read_minutes":3,"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":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# MCP 문제 해결\n\nSynapse MCP를 LLM 클라이언트와 통합할 때 일반적인 문제와 해결 방법입니다.\n\n## 빠른 진단 체크리스트\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. ✅ 구성 파일이 유효한 JSON? (후행 쉼표 없음, 주석 없음)\n6. ✅ 구성 변경 후 클라이언트 재시작?\n7. ✅ MCP 서버가 수동으로 시작? (`npx -y synapse-mcp-api@latest`)\n\n## 문제: 클라이언트에 도구가 나타나지 않음\n\n### 증상\n\n- Claude Desktop / Cursor / Continue이 0개 도구 표시\n- 🔌 아이콘이나 MCP 서버 목록에 \"synapse\" 항목 없음\n\n### 해결 방법\n\n1. **클라이언트 완전히 재시작** — macOS에서 Cmd+Q (창 닫기가 아님)\n2. **구성 파일 위치 확인**:\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 검증** — 구성을 에 붙여넣기\n4. **클라이언트 로그에서 MCP 오류 확인**:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **MCP 서버 수동 실행**하여 시작 오류 확인:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## 문제: \"Mind Key invalid\" 오류\n\n### 증상\n\n- 도구는 나타나지만 호출이 \"401 Unauthorized\"로 실패\n- 오류: \"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. **환경 변수가 설정되었는지 확인** — stdio 전송의 경우, 환경 변수가\n 셸이 아닌 MCP 서버 구성에 있어야 함\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- 오류: \"npx: command not found\"\n- MCP 서버가 시작되지 않음\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. 설치 후 **터미널 재시작**\n3. **확인**: `node --version && npx --version`\n\n## 문제: SYNAPSE_URL 접근 불가\n\n### 증상\n\n- MCP 서버는 시작되지만 도구 호출이 시간 초과\n- 오류: \"fetch failed\" 또는 \"ECONNREFUSED\"\n\n### 해결 방법\n\n1. **연결 테스트**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **기업 방화벽 확인** — 아웃바운드 HTTPS를 차단할 수 있음\n3. **대체 URL 시도**:\n - 프로덕션: `https://synapse.schaefer.zone`\n - MCP 서버: `https://synapse-mcp.schaefer.zone`\n4. **자체 호스팅의 경우**: Synapse 인스턴스가 실행 중이고 접근 가능한지 확인\n\n## 문제: MCP 서버 충돌\n\n### 증상\n\n- MCP 서버가 시작 후 즉시 종료\n- 클라이언트 로그에 \"MCP server disconnected\" 표시\n\n### 해결 방법\n\n1. **수동 실행하여 오류 확인**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **포트 충돌 확인** — MCP 서버는 기본적으로 포트 13100 사용\n3. **npx 캐시 삭제**:\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## 문제: 도구 호출이 429 반환\n\n### 증상\n\n- 오류: \"Rate limit exceeded\"\n\n### 해결 방법\n\n이는 MCP에서 발생하지 않아야 합니다 (헤더 인증 사용, 속도 제한 없음). 발생하는 경우:\n\n1. **어딘가에서 `?key=`를 사용하고 있는지 확인** — 헤더 인증으로 전환\n2. **`SYNAPSE_URL` 확인** — 올바른 인스턴스를 가리키는지 확인\n3. 문제가 지속되면 **지원팀에 연락**\n\n## 문제: 도구는 나타나지만 작동하지 않음\n\n### 증상\n\n- 클라이언트에 도구 나열됨\n- 도구 호출이 오류를 반환하거나 결과 없음\n\n### 해결 방법\n\n1. **도구 이름 확인** — 정확해야 함 (예: `memory.recall`이 아닌 `memory_recall`)\n2. **인수 확인** — 도구의 입력 스키마 확인\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. **기존 이슈 확인**: \n2. **새 이슈 열기**:\n - MCP 서버 버전 (`npx -y synapse-mcp-api@latest --version`)\n - 클라이언트 이름 및 버전\n - 운영 체제\n - 관련 로그 발췌\n - 재현 단계\n\n## 다음 단계\n\n- [Claude Desktop 설정](/docs/mcp/claude-desktop)\n- [Claude Code 설정](/docs/mcp/claude-code)\n- [API 오류](/docs/api/errors)\n","content_html":"

MCP 문제 해결

\n

Synapse MCP를 LLM 클라이언트와 통합할 때 일반적인 문제와 해결 방법입니다.

\n

빠른 진단 체크리스트

\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. ✅ 구성 파일이 유효한 JSON? (후행 쉼표 없음, 주석 없음)
    6. \n
  6. ✅ 구성 변경 후 클라이언트 재시작?
    7. \n
  7. ✅ MCP 서버가 수동으로 시작? (npx -y synapse-mcp-api@latest)
    8. \n
\n

문제: 클라이언트에 도구가 나타나지 않음

\n

증상

\n
    \n
  • Claude Desktop / Cursor / Continue이 0개 도구 표시
    • \n
  • 🔌 아이콘이나 MCP 서버 목록에 "synapse" 항목 없음
    • \n
\n

해결 방법

\n
    \n
  1. 클라이언트 완전히 재시작 — macOS에서 Cmd+Q (창 닫기가 아님)
    2. \n
  2. 구성 파일 위치 확인:
      \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 검증 — 구성을 https://jsonlint.com에 붙여넣기
    4. \n
  4. 클라이언트 로그에서 MCP 오류 확인:
      \n
    • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
      • \n
    • Cursor: View → Output → MCP
      • \n
    \n
    5. \n
  5. MCP 서버 수동 실행하여 시작 오류 확인:
    SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
    6. \n
\n

문제: "Mind Key invalid" 오류

\n

증상

\n
    \n
  • 도구는 나타나지만 호출이 "401 Unauthorized"로 실패
    • \n
  • 오류: "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. 환경 변수가 설정되었는지 확인 — stdio 전송의 경우, 환경 변수가\n셸이 아닌 MCP 서버 구성에 있어야 함
    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
  • 오류: "npx: command not found"
    • \n
  • MCP 서버가 시작되지 않음
    • \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. 설치 후 터미널 재시작
    3. \n
  3. 확인: node --version && npx --version
    4. \n
\n

문제: SYNAPSE_URL 접근 불가

\n

증상

\n
    \n
  • MCP 서버는 시작되지만 도구 호출이 시간 초과
    • \n
  • 오류: "fetch failed" 또는 "ECONNREFUSED"
    • \n
\n

해결 방법

\n
    \n
  1. 연결 테스트:
    curl https://synapse.schaefer.zone/health
    2. \n
  2. 기업 방화벽 확인 — 아웃바운드 HTTPS를 차단할 수 있음
    3. \n
  3. 대체 URL 시도:
      \n
    • 프로덕션: https://synapse.schaefer.zone
      • \n
    • MCP 서버: https://synapse-mcp.schaefer.zone
      • \n
    \n
    4. \n
  4. 자체 호스팅의 경우: Synapse 인스턴스가 실행 중이고 접근 가능한지 확인
    5. \n
\n

문제: MCP 서버 충돌

\n

증상

\n
    \n
  • MCP 서버가 시작 후 즉시 종료
    • \n
  • 클라이언트 로그에 "MCP server disconnected" 표시
    • \n
\n

해결 방법

\n
    \n
  1. 수동 실행하여 오류 확인:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. 포트 충돌 확인 — MCP 서버는 기본적으로 포트 13100 사용
    3. \n
  3. npx 캐시 삭제:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. 최신으로 업데이트:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

문제: 도구 호출이 429 반환

\n

증상

\n
    \n
  • 오류: "Rate limit exceeded"
    • \n
\n

해결 방법

\n

이는 MCP에서 발생하지 않아야 합니다 (헤더 인증 사용, 속도 제한 없음). 발생하는 경우:

\n
    \n
  1. 어딘가에서 ?key=를 사용하고 있는지 확인 — 헤더 인증으로 전환
    2. \n
  2. SYNAPSE_URL 확인 — 올바른 인스턴스를 가리키는지 확인
    3. \n
  3. 문제가 지속되면 지원팀에 연락
    4. \n
\n

문제: 도구는 나타나지만 작동하지 않음

\n

증상

\n
    \n
  • 클라이언트에 도구 나열됨
    • \n
  • 도구 호출이 오류를 반환하거나 결과 없음
    • \n
\n

해결 방법

\n
    \n
  1. 도구 이름 확인 — 정확해야 함 (예: memory.recall이 아닌 memory_recall)
    2. \n
  2. 인수 확인 — 도구의 입력 스키마 확인
    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. 기존 이슈 확인: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
    2. \n
  2. 새 이슈 열기:
      \n
    • MCP 서버 버전 (npx -y synapse-mcp-api@latest --version)
      • \n
    • 클라이언트 이름 및 버전
      • \n
    • 운영 체제
      • \n
    • 관련 로그 발췌
      • \n
    • 재현 단계
      • \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"]}