NerdNavis_AiDev
/
BurningTimesAi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BurningTimesAi/memory/org/feedback_mcp_setup_pitfalls.md

7.0 KiB
Raw Blame History

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

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

배경

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

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

실증:

"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): 
    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를 첫 참조로 삼아 시행착오 반복 차단.