# MCP 문제 해결

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

## 빠른 진단 체크리스트

1. ✅ Node.js 18+ 설치? (`node --version`)
2. ✅ Mind Key가 `mk_`로 시작? (JWT `eyJ...`가 아님)
3. ✅ Synapse API 접근 가능? (`curl https://synapse.schaefer.zone/health`)
4. ✅ Mind Key 작동? (`curl -H "Authorization: Bearer mk_..." .../memory/recall`)
5. ✅ 구성 파일이 유효한 JSON? (후행 쉼표 없음, 주석 없음)
6. ✅ 구성 변경 후 클라이언트 재시작?
7. ✅ MCP 서버가 수동으로 시작? (`npx -y synapse-mcp-api@latest`)

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

### 증상

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

### 해결 방법

1. **클라이언트 완전히 재시작** — macOS에서 Cmd+Q (창 닫기가 아님)
2. **구성 파일 위치 확인**:
   - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Claude Desktop Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - Cursor: `~/.cursor/config.json`
   - Continue: `~/.continue/config.json`
3. **JSON 검증** — 구성을 <https://jsonlint.com>에 붙여넣기
4. **클라이언트 로그에서 MCP 오류 확인**:
   - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)
   - Cursor: View → Output → MCP
5. **MCP 서버 수동 실행**하여 시작 오류 확인:
   ```bash
   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
   ```

## 문제: "Mind Key invalid" 오류

### 증상

- 도구는 나타나지만 호출이 "401 Unauthorized"로 실패
- 오류: "Mind Key fehlt oder ungültig"

### 해결 방법

1. **Mind Key 형식 확인** — `mk_`로 시작, 약 40자
2. **직접 테스트**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **환경 변수가 설정되었는지 확인** — stdio 전송의 경우, 환경 변수가
   셸이 아닌 MCP 서버 구성에 있어야 함
4. **새 Mind Key 받기**:
   ```bash
   # Login to get JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Create new mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
   ```

## 문제: npx를 찾을 수 없음

### 증상

- 오류: "npx: command not found"
- MCP 서버가 시작되지 않음

### 해결 방법

1. **Node.js 18+ 설치**:
   - macOS: `brew install node` 또는 <https://nodejs.org>에서 다운로드
   - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`
   - Windows: <https://nodejs.org>에서 다운로드
2. 설치 후 **터미널 재시작**
3. **확인**: `node --version && npx --version`

## 문제: SYNAPSE_URL 접근 불가

### 증상

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

### 해결 방법

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

## 문제: MCP 서버 충돌

### 증상

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

### 해결 방법

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

## 문제: 도구 호출이 429 반환

### 증상

- 오류: "Rate limit exceeded"

### 해결 방법

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

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

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

### 증상

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

### 해결 방법

1. **도구 이름 확인** — 정확해야 함 (예: `memory.recall`이 아닌 `memory_recall`)
2. **인수 확인** — 도구의 입력 스키마 확인
3. **직접 API로 테스트**:
   ```bash
   curl -X POST https://synapse.schaefer.zone/memory \
     -H "Authorization: Bearer mk_..." \
     -H "Content-Type: application/json" \
     -d '{"category":"fact","key":"test","content":"hello"}'
   ```
4. **Synapse 상태 확인**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```

## 도움말 받기

위의 방법으로 문제가 해결되지 않으면:

1. **기존 이슈 확인**: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. **새 이슈 열기**:
   - MCP 서버 버전 (`npx -y synapse-mcp-api@latest --version`)
   - 클라이언트 이름 및 버전
   - 운영 체제
   - 관련 로그 발췌
   - 재현 단계

## 다음 단계

- [Claude Desktop 설정](/docs/mcp/claude-desktop)
- [Claude Code 설정](/docs/mcp/claude-code)
- [API 오류](/docs/api/errors)