이 페이지는 영어에서 기계 번역되었습니다. 영어 원문 읽기.

문제 해결

일반적인 Unreal MCP 문제 해결 - 플러그인 로드 실패, 브리지 누락, 연결 중단, Unreal 도구가 없는 AI 에이전트, 오래된 빌드, 도구 오류.

2026년 11월 4일 업데이트 Markdown으로 보기

이 페이지는 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을 참고하세요.
  • 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 <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 <agent> --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/<pin>)을 사용하세요. --no-pin 없이 setup-mcp를 다시 실행하세요. Connecting AI clients를 참고하세요.

에이전트에서 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와 일반 FAQ를 참고하세요.
  • 창의 Help / Talk를 사용해 Discord에서 질문하거나, Bug Report로 GitHub 이슈를 열 수 있습니다. Unreal 버전, 운영체제, 창의 상태 표시줄, 관련 로그 줄을 포함하세요(토큰은 절대 포함하지 마세요).