# 문제 해결 — Unreal Engine · AI Game Developer Wiki 일반적인 Unreal MCP 문제 해결 - 플러그인 로드 실패, 브리지 누락, 연결 중단, Unreal 도구가 없는 AI 에이전트, 오래된 빌드, 도구 오류. 이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/unreal/troubleshooting). 이 페이지는 Unreal MCP에서 사람들이 가장 자주 겪는 문제와 해결 방법을 정리한 것입니다. 먼저 빠른 점검을 확인한 뒤 해당 섹션으로 이동하세요. ## 빠른 점검 1. **플러그인이 로드되었나요?** 에디터가 시작된 후 Output Log에 `[Unreal-MCP] plugin loaded`가 있어야 합니다. 2. **창에 무엇이 표시되나요?** **Tools**, **AI Game Developer**를 열고 상태 줄(Connected, Connecting, Reconnecting, Disconnected 또는 No MCP bridge)을 확인하세요. 3. **CLI에는 어떻게 보이나요?** `unreal-mcp-cli status --path ./YourProject`를 실행하세요. 4. **로그를 읽으세요.** 창의 **Open log file**을 사용하거나, Output Log를 `LogUnrealMcp` 카테고리로 필터링하거나, 에이전트에 `console | where Verbosity == "Error"`를 요청하세요. ## 플러그인이 로드되지 않는 경우 `[Unreal-MCP] plugin loaded` 줄이 없다면 에디터 모듈이 시작되지 못한 것입니다. - Output Log에서 플러그인의 시작 오류나 손상된 `.uplugin`을 찾아보세요. - 프로젝트가 정상 동작하는 컴파일러 툴체인을 갖춘 **C++ 프로젝트**인지 확인하세요. [Installation](https://ai-game.dev/ko/docs/wiki/unreal/installation#requirements)을 참고하세요. - Unreal이 모듈이 없다거나 플러그인이 호환되지 않는다고 하면 재빌드를 허용하거나, `unreal-mcp-cli open ./YourProject`로 프로젝트를 여세요. 이 명령은 네이티브 모듈을 먼저 빌드하고 해당 프롬프트를 닫아줍니다. ## 업데이트가 적용되지 않는 경우 플러그인 소스가 바뀌었는데 이전 `Intermediate/` 폴더가 남아 있으면 Unreal의 증분 빌드가 예전 플러그인 코드를 유지할 수 있습니다. - `unreal-mcp-cli update ./YourProject`로 업데이트하세요. 이 명령은 기본적으로 빌드 캐시를 정리합니다. - 수동으로 복사한 경우: 에디터를 닫고 `Plugins/UnrealMCP/Intermediate/`와 `Plugins/UnrealMCP/Binaries/` 안의 C++ 파일을 삭제한 뒤(`Binaries/ThirdParty/`는 유지) 다시 여세요. ## "No MCP bridge" 또는 브리지가 계속 재시작되는 경우 플러그인에는 브리지 프로세스 `unreal-mcp-bridge`가 필요합니다. 창에 브리지 상태와 재시작 횟수가 표시됩니다. - 로그에 `no sidecar binary resolved for rid `가 나오면 브리지를 찾지 못한 것입니다. - **앱 또는 CLI 설치:** 브리지가 함께 포함되어 있습니다. `unreal-mcp-cli install-plugin ./YourProject`로(또는 앱에서) 다시 설치하세요. 패키지에 사용 중인 플랫폼이 없을 수 있습니다. - **소스 체크아웃:** `unreal-mcp-cli bootstrap-local ./YourProject`로 브리지를 빌드하거나 `UNREAL_MCP_BRIDGE_PATH`를 설정하세요. - 원인을 해결한 후 창 하단의 **Restart bridge**를 클릭하세요. ## "Connecting" 또는 "Reconnecting"에서 멈추는 경우 - **Cloud 모드:** 로그인되어 있는지 확인하세요. 창에 "Sign in required"가 표시되면 저장된 로그인이 만료된 것입니다. **Authorize**를 클릭하고 새 코드를 승인하세요. - 해당 머신이 ai-game.dev에 접속할 수 있는지(프록시 또는 방화벽 규칙) 확인하세요. - **Custom 모드:** 로컬 서버가 실행 중인지(MCP 서버 카드의 **Start** 또는 `--start-server`)와 **Server URL**이 해당 서버를 가리키는지 확인하세요. - **Disconnect** 후 **Connect**를 사용하거나 **Restart bridge**를 사용하세요. ## 로컬 서버가 "No connected clients"라고 표시하는 경우 로컬 `gamedev-mcp-server`가 `No connected clients. Retrying`을 기록한 뒤 HTTP 500으로 응답한다면, 에디터가 아직 **Cloud** 모드에 있고 로컬 서버 대신 ai-game.dev에 연결되어 있는 것입니다. 창에서 **Custom**으로 전환하거나, `UNREAL_MCP_CONNECTION_MODE=Custom`을 설정하거나, `unreal-mcp-cli open`에 `--connection-mode Custom`(또는 `--host`)을 전달하세요. ## AI 에이전트에 Unreal 도구가 없는 경우 - 에이전트 설정을 확인하세요: `unreal-mcp-cli setup-mcp --path ./YourProject --dry-run`을 실행해 비교하거나, AI agent 섹션에서 **Configure**(또는 **Reconfigure**)를 클릭하세요. - 설정을 변경한 후 에이전트를 재시작하거나 다시 로드하세요. 많은 클라이언트가 시작 시에만 MCP 설정을 읽습니다. - Claude Code는 실행한 폴더의 `.mcp.json`을 읽으므로 프로젝트 폴더에서 실행하세요. - 에디터를 한 번도 열기 전에 `setup-mcp`로 설정했다면, 설정이 클라우드 대신 `localhost`를 가리킬 수 있습니다. 프로젝트를 한 번 연 뒤 `setup-mcp`를 다시 실행하거나 `--url`을 전달하세요. - Connection 섹션의 **AI agents** 행을 확인하세요. 에이전트가 목록에 없다면 에디터와 같은 서버에 연결되지 않은 것입니다. - **MCP Tools** 창에서 도구를 숨겼거나 `UNREAL_MCP_TOOLS`를 설정했다면 에이전트가 보는 도구가 줄어듭니다. ## 에이전트가 잘못된 에디터에 연결되는 경우 한 계정에 여러 에디터가 있다면 `setup-mcp`가 기본으로 기록하는 프로젝트 고정 URL(`/mcp/p/`)을 사용하세요. `--no-pin` 없이 `setup-mcp`를 다시 실행하세요. [Connecting AI clients](https://ai-game.dev/ko/docs/wiki/unreal/connecting-ai-clients#pinned-url)를 참고하세요. ## 에이전트에서 401 오류가 발생하는 경우 - Cloud 모드에서는 URL만 있는 설정이라면 에이전트가 직접 로그인해야 합니다. 에이전트가 자체적으로 OAuth 로그인을 수행하도록 하거나, 머신에서 로그인(`unreal-mcp-cli login`)한 뒤 `setup-mcp`를 다시 실행해 설정에 프로젝트 키가 포함되도록 하세요. - 프로젝트 키가 폐기되었다면 에디터의 **Regenerate key** 또는 `setup-mcp --regenerate-key`를 사용하세요. - **token** 인증을 사용하는 Custom 모드에서는 설정이 에디터와 동일한 토큰을 포함해야 합니다. 새 토큰을 생성한 뒤 **Reconfigure**를 사용하세요. ## 도구 호출 시간 초과 도구 호출 하나는 기본적으로 5분 동안 실행될 수 있습니다. 긴 Python 스크립트나 큰 임포트의 경우 `UNREAL_MCP_TOOL_TIMEOUT`(밀리초)을 높이세요. `python-execute`에는 에이전트가 호출마다 설정할 수 있는 자체 `timeout`(기본 30초)도 있습니다. ## 스크린샷 도구가 오류를 반환함 픽셀 캡처에는 GPU 기반 에디터가 필요합니다. `-nullrhi`에서는 스크린샷 도구가 구조화된 오류를 반환합니다. `unreal-mcp-cli exec`와 `open --headless`는 화면 밖에서 렌더링하는 에디터를 시작하므로, 여기서는 캡처가 정상적으로 동작합니다. ## Python 도구 실패 `python-execute`는 Unreal MCP가 활성화하는 Unreal의 Python Editor Script Plugin을 사용합니다. Python을 사용할 수 없다면 **Edit, Plugins**에서 플러그인이 활성화되어 있는지 확인하세요. 오류는 에이전트가 보낸 코드인 `snippet.py`의 줄을 가리킵니다. ## 확장이 표시되지 않음 - 확장 기능은 Unreal Engine 5.7 이상과 Unreal MCP 0.26.0 이상이 필요합니다. - 설치 후 확장을 컴파일해야 합니다. 에디터를 다시 열거나, `--build`를 사용하거나, Extensions 섹션에서 \*\*Compile (Live Coding)\*\*을 사용하세요. - Extensions 섹션에서 확장이 활성화되어 있는지 확인하세요. ## 그래도 해결되지 않나요? - [FAQ](https://ai-game.dev/ko/docs/wiki/unreal/faq)와 일반 [FAQ](https://ai-game.dev/docs/faq)를 참고하세요. - 창의 **Help / Talk**를 사용해 Discord에서 질문하거나, **Bug Report**로 GitHub 이슈를 열 수 있습니다. Unreal 버전, 운영체제, 창의 상태 표시줄, 관련 로그 줄을 포함하세요(토큰은 절대 포함하지 마세요). --- Source (HTML): https://ai-game.dev/ko/docs/wiki/unreal/troubleshooting Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/unreal/troubleshooting