BurningTimesAi/memory/org/feedback_mcp_setup_pitfalls.md

---
name: MCP (Model Context Protocol) 도구 셋업 실전 함정 5종 — 재발 방지 SOT
description: 2026-04-21~22 BT3 Unity MCP 도입 시 실증된 셋업 함정 5종. Claude Desktop HTTP 미지원·uvx 캐시 pywin32 락·좀비 인스턴스·Transport 불일치·재시작 완전성. 차기 MCP 도입 시 첫 참조 자산
type: feedback
created: 2026-04-22
---

# MCP 도구 셋업 실전 함정 5종 — 재발 방지 SOT (v1)

## 배경

2026-04-21~22 BurningTimes 조직 BT3 지시 "Unity MCP 도입" 집행 중 다단계 트러블슈팅 발생. 최종 연동은 성공했으나 **같은 유형의 함정이 모든 MCP 도구 셋업에 재발 가능**하므로 재발 방지 SOT로 아카이브.

## 함정 1 — Claude Desktop은 HTTP `url` 방식 거부

**실증**:
```json
"unityMCP": {
  "url": "http://localhost:8080/mcp"
}
```
→ Claude Desktop 경고: "유효한 MCP 서버 구성이 아닙니다".

**근본 원인**: Claude Desktop은 공식적으로 **stdio 방식만 지원**. HTTP `url` 방식은 Claude Code·Cursor 등 다른 클라이언트 전용. unity-mcp 공식 README가 HTTP를 "기본 권장"으로 서술해도 Claude Desktop에는 해당 안 됨.

**재발 방지**:
- 신규 MCP 도구 문서에서 "HTTP 권장" 문구 보면 **클라이언트별 호환성 재확인** 필수
- Claude Desktop 대상 시 **stdio(`command`+`args`) 형식만 사용**
- Unity MCP for Unity Package의 "Transport" 설정도 Claude Desktop 대상 시 **stdio로 전환**

## 함정 2 — uvx 첫 설치 시 pywin32 캐시 락

**실증 로그**:
```
error: Failed to install: pywin32-311-cp312-cp312-win_amd64.whl (pywin32==311)
  Caused by: failed to remove directory ...pywin32-311.data:
  다른 프로세스가 파일을 사용 중이기 때문에 프로세스가 액세스 할 수 없습니다. (os error 32)
```

**근본 원인**:
- uvx는 `$LOCALAPPDATA\uv\cache`에 패키지 임시 전개 후 설치
- `pywin32`는 `.data` 하위에 `.pyd` 바이너리 포함 — Windows Defender 실시간 검사가 즉시 스캔하며 일시 락
- 또는 이전 uvx 시도의 잔재 Python 프로세스가 캐시 락

**재발 방지**:
1. **수동 사전 워밍업 필수** — Claude Desktop 자동 시동 전 `uvx --from <pkg> <entry> --help` 1회 실행
2. **Windows Defender 예외 등록** (관리자 PowerShell):
   ```powershell
   Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\uv\cache"
   ```
3. **잔재 프로세스 전수 종료** 후 재시도
4. 이는 **Python 기반 모든 MCP 서버**에 공통 (mcpforunityserver·mcp-server-sqlite·mcp-server-memory 등)

## 함정 3 — Claude Desktop 좀비 인스턴스 "Could not attach"

**실증**: 4개 MCP 서버 동시 "Could not attach to MCP server" 경고.

**근본 원인**:
- Claude Desktop 창 X 닫기는 **트레이 잔류** (Quit 아님)
- 잔재 인스턴스가 MCP 서버 프로세스 잡고 있어 새 인스턴스 attach 실패
- `uvx.exe`·`python.exe`·`node.exe` 등 MCP 서버가 띄운 프로세스도 함께 잔류

**재발 방지**:
- Claude Desktop 재시작 시 **트레이 아이콘 우클릭 → Quit** 또는 **작업관리자 전수 종료**
- 재시작 전 작업관리자에서 `Claude.exe`·`uvx.exe`·`uv.exe`·`python.exe`·`node.exe` 중 MCP 관련 프로세스 검색·종료
- "창 닫기 = 종료"가 **아니라는 점**을 모든 PC 셋업 가이드에 명시

## 함정 4 — 다른 PC에서 가져온 config의 경로 무효

**실증**:
- `C:\Users\silve\AppData\Roaming\npm\...` 경로의 memory 서버 → **silve 사용자 없는 PC에서 disconnected**
- `D:\Dev\SurgeCoin` 경로의 filesystem·sqlite → **해당 폴더 없는 PC에서 disconnected**

**근본 원인**:
- `claude_desktop_config.json`은 **PC별·사용자별 경로**가 하드코딩되기 쉬움
- 다른 PC에서 가져온 config를 그대로 쓰면 사용자명·드라이브 경로 불일치로 실패

**재발 방지**:
- **config는 PC별 별도 구성**, git 추적 금지 (BT는 `공유/개발팀_자산/claude_desktop_config.example.json` 템플릿 제공)
- Unity MCP for Unity **Configure 자동화 활용** — PC별 실경로를 Unity가 탐지·기입
- 다른 PC config 복사 시 **경로 전수 수정** 체크리스트

## 함정 5 — Unity 쪽 Transport 기본값 불일치

**실증**: Unity MCP for Unity 창의 Transport 기본값은 `HTTP Local`. 이 상태로 Claude Desktop용 Configure 누르면 에러:
> "Claude Desktop does not support HTTP transport. Switch to stdio in settings before configuring."

**근본 원인**:
- Unity Package 쪽 Transport = Python MCP 서버가 Unity와 통신하는 방식
- Claude Desktop 대상 시 Python MCP 서버가 **stdio 모드로 Claude Desktop과 통신** + Unity와도 stdio로 통신해야 함
- HTTP Local로 두면 Python 서버가 HTTP 클라이언트로 동작하여 Claude Desktop의 stdio 호출과 충돌

**재발 방지**:
- Unity MCP for Unity 창 열면 **Transport 드롭다운부터 stdio로 변경**
- Configure 누르기 전 체크리스트 4항:
  1. Transport = `stdio`
  2. Server Status = `Running`
  3. Client = `Claude Desktop`
  4. Configure 클릭

## 공통 진단 도구

### 가장 빠른 진단 — Claude Desktop MCP 로그
```
%APPDATA%\Claude\logs\mcp-server-<서버명>.log
```
서버별 로그 파일에 정확한 에러 출력됨. "Server disconnected" 같은 UI 메시지보다 **실체 원인 즉시 파악**.

### Unity 연동 검증 명령
Claude에게: "Unity Console 로그 읽어줘"
→ `mcp__unityMCP__read_console` 호출 → Unity Editor 실제 로그 수신 여부로 연동 완전성 판별.

## 차기 MCP 도입 시 체크리스트 (BT 조직 표준)

- [ ] 대상 MCP 도구 공식 README에서 **Claude Desktop 호환성** 재확인 (HTTP만 문서화되어 있으면 stdio 별도 경로 확인)
- [ ] Python 기반 서버면 **uvx 수동 사전 워밍업** (캐시 구축)
- [ ] Windows Defender 예외 등록 고려 (uv cache 경로)
- [ ] Claude Desktop 재시작은 **트레이 Quit** 필수 (창 X 아님)
- [ ] 서버 추가·변경 후 30초~1분 기다려서 Claude Desktop의 MCP 상태 UI 재확인
- [ ] 연동 검증 — 실제 도구 호출로 대상 시스템 응답 확인 (UI "Running" 표시만으로는 불충분)
- [ ] 에러 발생 시 `%APPDATA%\Claude\logs\mcp-server-*.log` 선행 확인

## 연관 자산

- **가이드**: `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` (v2 개정)
- **조직공지**: `공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md`
- **시행착오 아카이브**: `공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md`
- **이전 프로젝트 Unity MCP v1 경험**: `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md`

## 교훈 (BT 조직 원칙)

**MCP 도구 도입은 "설치" 이상의 협업 체계 구축**이다. 클라이언트 호환성·패키지 매니저 캐시·OS 보안 정책·재시작 완전성이 모두 얽혀 있어 **한 번에 성공하기 어려움**. 그러나 **같은 함정이 다음 도구에서도 반복**되므로 본 SOT를 첫 참조로 삼아 시행착오 반복 차단.