# MCP 문제 해결
SUMMARY: 일반적인 MCP 통합 문제 해결 — 서버 시작 안 됨, 도구 나타나지 않음, 인증 오류.

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/

MCP 문제 해결
Synapse MCP를 LLM 클라이언트와 통합할 때 일반적인 문제와 해결 방법입니다.
빠른 진단 체크리스트
1. ✅ Node.js 18+ 설치? ()
2. ✅ Mind Key가 로 시작? (JWT 가 아님)
3. ✅ Synapse API 접근 가능? ()
4. ✅ Mind Key 작동? ()
5. ✅ 구성 파일이 유효한 JSON? (후행 쉼표 없음, 주석 없음)
6. ✅ 구성 변경 후 클라이언트 재시작?
7. ✅ MCP 서버가 수동으로 시작? ()
문제: 클라이언트에 도구가 나타나지 않음
증상
- Claude Desktop / Cursor / Continue이 0개 도구 표시
- 🔌 아이콘이나 MCP 서버 목록에 "synapse" 항목 없음
해결 방법
1. 클라이언트 완전히 재시작 — macOS에서 Cmd+Q (창 닫기가 아님)
2. 구성 파일 위치 확인:
   - Claude Desktop macOS: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. JSON 검증 — 구성을 <https://jsonlint.com>에 붙여넣기
4. 클라이언트 로그에서 MCP 오류 확인:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. MCP 서버 수동 실행하여 시작 오류 확인:
   [CODE BLOCK]
문제: "Mind Key invalid" 오류
증상
- 도구는 나타나지만 호출이 "401 Unauthorized"로 실패
- 오류: "Mind Key fehlt oder ungültig"
해결 방법
1. Mind Key 형식 확인 — 로 시작, 약 40자
2. 직접 테스트:
   [CODE BLOCK]
3. 환경 변수가 설정되었는지 확인 — stdio 전송의 경우, 환경 변수가
   셸이 아닌 MCP 서버 구성에 있어야 함
4. 새 Mind Key 받기:
   [CODE BLOCK]
문제: npx를 찾을 수 없음
증상
- 오류: "npx: command not found"
- MCP 서버가 시작되지 않음
해결 방법
1. Node.js 18+ 설치:
   - macOS:  또는 <https://nodejs.org>에서 다운로드
   - Linux: 
   - Windows: <https://nodejs.org>에서 다운로드
2. 설치 후 터미널 재시작
3. 확인: 
문제: SYNAPSEURL 접근 불가
증상
- MCP 서버는 시작되지만 도구 호출이 시간 초과
- 오류: "fetch failed" 또는 "ECONNREFUSED"
해결 방법
1. 연결 테스트:
   [CODE BLOCK]
2. 기업 방화벽 확인 — 아웃바운드 HTTPS를 차단할 수 있음
3. 대체 URL 시도:
   - 프로덕션: 
   - MCP 서버: 
4. 자체 호스팅의 경우: Synapse 인스턴스가 실행 중이고 접근 가능한지 확인
문제: MCP 서버 충돌
증상
- MCP 서버가 시작 후 즉시 종료
- 클라이언트 로그에 "MCP server disconnected" 표시
해결 방법
1. 수동 실행하여 오류 확인:
   [CODE BLOCK]
2. 포트 충돌 확인 — MCP 서버는 기본적으로 포트 13100 사용
3. npx 캐시 삭제:
   [CODE BLOCK]
4. 최신으로 업데이트:
   [CODE BLOCK]
문제: 도구 호출이 429 반환
증상
- 오류: "Rate limit exceeded"
해결 방법
이는 MCP에서 발생하지 않아야 합니다 (헤더 인증 사용, 속도 제한 없음). 발생하는 경우:
1. 어딘가에서 를 사용하고 있는지 확인 — 헤더 인증으로 전환
2.  확인 — 올바른 인스턴스를 가리키는지 확인
3. 문제가 지속되면 지원팀에 연락
문제: 도구는 나타나지만 작동하지 않음
증상
- 클라이언트에 도구 나열됨
- 도구 호출이 오류를 반환하거나 결과 없음
해결 방법
1. 도구 이름 확인 — 정확해야 함 (예: 이 아닌 )
2. 인수 확인 — 도구의 입력 스키마 확인
3. 직접 API로 테스트:
   [CODE BLOCK]
4. Synapse 상태 확인:
   [CODE BLOCK]
도움말 받기
위의 방법으로 문제가 해결되지 않으면:
1. 기존 이슈 확인: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. 새 이슈 열기:
   - MCP 서버 버전 ()
   - 클라이언트 이름 및 버전
   - 운영 체제
   - 관련 로그 발췌
   - 재현 단계
다음 단계
- Claude Desktop 설정
- Claude Code 설정
- API 오류