BurningTimesAi/공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md

---
type: 시행착오 아카이브
scope: Unity MCP (Model Context Protocol) 도입·연동
source_project: BurningTimes (BT3 지시)
source_date: 2026-04-21 ~ 2026-04-22
target_org: BurningTimes
target_project: EerieVillage + 차기 프로젝트
maintainer: 개발팀장 · 총괄PM
created: 2026-04-22
version: v1
related_rules: C6-1 · C11 · C16 · C23 · C30 · C34-11 · P10 · P14
related_feedback: feedback_mcp_setup_pitfalls.md
rationale: BT3 Unity MCP 도입 시 실증된 7종 트러블슈팅 타임라인·해결 순서·교훈을 조직 자산으로 영구 보존. 차기 MCP 도구 도입·신규 PC 셋업 시 첫 참조 자산
---

# BurningTimes · Unity MCP 연동 시행착오 아카이브 v1

## 1. 개요 — BT3 지시 요약

| 항목 | 값 |
|------|---|
| **지시일** | 2026-04-21 |
| **지시 내용** | "Unity MCP를 이용해 프로젝트 개발 진행" + Unity MCP 저장소 `E:\BurningTimes\코어코드\unity-mcp`에 사전 clone |
| **완결일** | 2026-04-22 |
| **소요 세션** | 약 3 세션 (경계: SessionStart hook resume 3회) |
| **최종 결과** | ✅ 완전 연동 성공 (`mcp__unityMCP__read_console` 실수신 확인) |
| **관리 방침 결정** | A안 (gitignore + setup 자동 clone) — PD 승인 |

## 2. 시행착오 타임라인 — 7단계

### 단계 1. HTTP url 방식 실패
**시도**: unity-mcp 공식 README의 "기본 권장" HTTP 설정 채택
```json
"unityMCP": {"url": "http://localhost:8080/mcp"}
```
**결과**: Claude Desktop 경고 **"유효한 MCP 서버 구성이 아닙니다: unityMCP"** (유일한 거부 이유 메시지)

**근본 원인**: Claude Desktop은 **stdio 방식만 공식 지원**. README의 "HTTP 권장"은 Claude Code·Cursor·Windsurf 등 타 클라이언트 대상이었고, Claude Desktop 호환성은 별도 명시되지 않음.

**해결**: stdio(uvx) 방식으로 전환
```json
"unityMCP": {
  "command": "<uvx.exe 절대 경로>",
  "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
}
```

**교훈**: MCP 공식 문서의 "권장" 방식 ≠ 모든 클라이언트 지원. **클라이언트별 stdio/HTTP 호환성 재확인** 필수.

---

### 단계 2. "Server disconnected" 반복 (memory·filesystem)
**증상**: JSON 문법 수정 후에도 `MCP memory / filesystem: Server disconnected` 경고 반복.

**근본 원인**:
- `memory` 서버: `C:\Users\silve\...` 경로 — **다른 PC(silve 사용자)에서 가져온 config**. 이 PC는 `sw` 사용자
- `filesystem` 서버: `D:\Dev\SurgeCoin` — **해당 프로젝트 폴더 자체 미존재**
- BT 조직 작업과 무관한 다른 프로젝트(SurgeCoin) 잔재 경로

**해결**:
- BT 작업에 불필요한 서버(filesystem·sqlite)는 config에서 제거
- memory는 `sw` 경로로 수정 유지 또는 제거 (옵션 A: minimal config 권장 채택)

**교훈**: **config는 PC별·사용자별 경로가 혼입되기 쉬움**. 다른 PC에서 복사 시 전수 경로 수정 + 불필요 서버 제거. BT 조직은 **template만 git 추적**, 실제 config는 PC별 개별 관리.

---

### 단계 3. "Could not attach" 4개 서버 동시 실패
**증상**: Claude Desktop 재시작 후에도 4개 MCP 서버(sqlite·filesystem·memory·unityMCP) 모두 `Could not attach to MCP server` 경고.

**근본 원인**: Claude Desktop **좀비 인스턴스** 잔류. 창 X 닫기는 트레이 잔존이라 이전 인스턴스가 MCP 프로세스 락. 새 인스턴스가 attach 시도하나 실패.

**해결**:
1. 작업관리자에서 `Claude.exe` 프로세스 **전수 종료** (복수 인스턴스 모두)
2. MCP 서버 잔재 프로세스(`uvx.exe`·`python.exe`·`node.exe`) 검색·종료
3. Claude Desktop 재실행

**교훈**: "창 닫기 ≠ 종료". **트레이 아이콘 우클릭 Quit** 또는 **작업관리자 전수 종료** 필수. 가이드·조직공지에 명시화.

---

### 단계 4. unityMCP "Server disconnected" 반복 — pywin32 캐시 락
**증상**: 3개 서버 disconnected 해소 후에도 `MCP unityMCP: Server disconnected` 지속.

**로그** (`%APPDATA%\Claude\logs\mcp-server-unityMCP.log`):
```
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 첫 설치 시 `mcpforunityserver` 의존성 `pywin32-311` 전개 중 **Windows Defender 실시간 스캔**이 `.pyd` 바이너리 일시 락. 또는 이전 uvx 시도 잔재 프로세스가 캐시 락.

**해결**:
1. 모든 Claude·uvx·python 프로세스 전수 종료
2. `uv cache` 삭제:
   ```powershell
   Remove-Item -Recurse -Force "$env:LOCALAPPDATA\uv\cache"
   ```
3. 수동 사전 워밍업 — Claude Desktop 밖에서 먼저 uvx 실행:
   ```powershell
   & "<uvx.exe 경로>" --from mcpforunityserver mcp-for-unity --help
   ```
   성공하면 캐시에 모든 의존성 완전 설치됨 (3~5분)
4. Claude Desktop 재실행 → uvx는 캐시에서 즉시 시동 (수 초)

**교훈**: Python 기반 MCP 서버는 **첫 실행 시 의존성 다운로드·설치가 수 분 소요**. Claude Desktop의 자동 시동은 타임아웃 짧아 실패 가능. **반드시 수동 사전 워밍업** 후 재시작.

---

### 단계 5. Python 서버 연결 성공 · Unity 연결 미완
**증상**: Claude Desktop에서 `mcp-installer (running)`·`unityMCP` 표시. `mcp__unityMCP__read_console` 호출 응답 수신:
```
"No Unity Editor instances found. Please ensure Unity is running with MCP for Unity bridge."
```

**근본 원인**: **Claude ↔ Python 서버는 연결**되었으나 **Python 서버 ↔ Unity Editor 미연결**. Unity Editor 실행만 하고 MCP for Unity Package 미설치.

**해결**:
1. Unity Hub에서 EerieVillage 프로젝트 열기
2. Package Manager → + → "Install package from git URL..."
3. `https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main`
4. 설치·컴파일 완료 대기

**교훈**: "MCP 서버 연결 = 도구 작동"이 아님. **대상 시스템(Unity)과의 최종 연결**까지 별도 검증 필요. 구간별 단계 체크가 효율적.

---

### 단계 6. Unity Transport HTTP → stdio 전환
**증상**: Unity MCP for Unity 창 열림. Configure 버튼 클릭 시 에러 팝업:
> **"Claude Desktop does not support HTTP transport. Switch to stdio in settings before configuring."**

**근본 원인**: Unity 쪽 Transport 기본값은 `HTTP Local`. Claude Desktop 대상 시 stdio 필요 — Unity MCP Package가 자체 검증해서 친절히 차단.

**해결**:
1. Unity MCP for Unity 창 → Transport 드롭다운 → **stdio** 선택
2. Client 드롭다운 → **Claude Desktop** 선택
3. Configure 버튼 재클릭 → 성공

**교훈**: MCP 도구 양쪽(서버·클라이언트) **Transport 일치 필수**. Unity MCP Package는 자체 검증 로직 있어 에러 메시지가 정확한 방향 제시.

---

### 단계 7. 연동 완전 성공 검증
**시점**: 2026-04-22
**명령**: `mcp__unityMCP__read_console action=get count=5`
**응답**:
```json
{
  "success": true,
  "message": "Retrieved 5 log entries.",
  "data": [
    "MCP-FOR-UNITY: Setup marked as completed",
    "MCP-FOR-UNITY: Started local HTTP server in terminal: <uvx> --offline --from mcpforunityserver==9.6.6 mcp-for-unity --transport http --http-url http://127.0.0.1:8080 ...",
    "[WebSocket] Receive loop error: ...",
    ...
  ]
}
```

**검증 포인트**:
- ✅ Unity Editor 실체 로그 수신
- ✅ `mcpforunityserver==9.6.6` 실행 확인
- ⚠️ WebSocket 경고 3건 — Configure 전환 시점 임시 재연결 로그 (현재 연결 정상이므로 무해)

## 3. BT 조직 계승 체크리스트

### 신규 PC Unity MCP 셋업 시 (필독)
1. BT 레포 clone + `paths.local.json` 생성 + `setup_windows.ps1` 실행 → unity-mcp 자동 clone
2. `winget install astral-sh.uv` → 터미널 재시작
3. **수동 사전 워밍업** (필수): `uvx --from mcpforunityserver mcp-for-unity --help` (3~5분)
4. Unity Editor + Package Manager로 MCP for Unity 설치
5. MCP for Unity 창 → **Transport: stdio** + Server Start + Client: Claude Desktop + Configure
6. Claude Desktop **트레이 Quit** 후 재실행
7. 연동 검증: "Unity Console 로그 읽어줘" 요청 → 실수신 확인

### 차기 MCP 도구 도입 시
1. 공식 README의 "권장 방식"이 HTTP이면 **Claude Desktop 호환성 재확인**
2. Python 기반 서버는 **uvx 수동 사전 워밍업** 우선
3. 재시작은 **트레이 Quit** 체크
4. 연동 검증은 **실체 도구 호출**로 판정 (UI 표시만으로 성공 단정 금지)

## 4. PM 보고 안건 (Phase 3 이관 검토)

- **Unity MCP 편집 표준 워크플로우 v2** 조직공지 정식 발행 (`2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md` 완료)
- **C23 정직성 관점 재발 방지**: 단계 5·6 같이 "MCP 서버 연결 = 도구 작동" 오인 차단 — 체크리스트에 실체 검증 단계 고정화
- **ToolSearch·Agent 권한 추가 반영** (`.claude/settings.json` commit `6550dc7`): 차기 MCP 도구 도입 시 유사 자동 승인 패턴 적용 검토
- **C34-11 Agent 경계 재확인**: Unity MCP 도구 호출 시 PC별 경로 하드코딩 금지 — `$UNITY_PROJECT_ROOT` 변수 활용 표준 유지

## 5. 참조 원본

### 대화로그·로그
- `공유/대화로그/조직운영/2026-04-21.md` — BT3 지시·집행·트러블슈팅 세션 경위
- `%APPDATA%\Claude\logs\mcp-server-unityMCP.log` — pywin32 락 에러 로그 (로컬)
- `%APPDATA%\Claude\logs\main.log` — Claude Desktop MCP 전반 로그 (로컬)

### 관련 자산
- `공유/개발팀_자산/Unity_MCP_연동_가이드_v1.md` (v2 개정본)
- `공유/개발팀_자산/claude_desktop_config.example.json` (stdio 기본)
- `공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md`
- `memory/org/feedback_mcp_setup_pitfalls.md` — 재발 방지 SOT (본 아카이브 축약판)
- `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md` — 이전 Unity MCP v1 경험 계승

### 커밋 타임라인
- `aa61028` — Unity MCP 도입 셋업 PM 집행분
- `6550dc7` — ToolSearch·Agent 권한 자동 승인 추가
- (본 세션 후속 commit) — BT3 완료 + 조직 자산 축적