설정
Unreal MCP 설정 - AI Game Developer 창, MCP Tools 표시 여부, 프로젝트 설정 파일, .env, 그리고 모든 UNREAL_MCP_* 환경 변수를 다룹니다.
이 페이지는 현재 Unreal MCP의 모든 설정과 각 설정을 변경하는 위치를 정리합니다. 대부분의 사용자는 연결 모드와 AI 에이전트 설정만 건드리며, 나머지는 튜닝, 자동화, CI를 위한 것입니다.
설정이 저장되는 위치
Unreal MCP에는 에디터 연결을 위한 Project Settings 페이지가 없습니다. 모든 설정은 AI Game Developer 창(Tools 메뉴)에 있으며, 프로젝트별로 다음 위치에 저장됩니다:
<YourProject>/Saved/Config/UnrealMcp/ai-game-developer-config.jsonSaved/는 모든 Unreal 프로젝트 템플릿에서 버전 관리에서 제외되므로, 이 파일의 토큰은 기본적으로 저장소에 포함되지 않습니다.
설정은 다음 순서로 읽히며, 우선순위가 높은 것이 먼저입니다:
- 프로세스 환경 변수 (예:
unreal-mcp-cli open또는 셸에서 설정한 값). - 프로젝트 루트의
.env파일. - 위의 설정 파일.
- 내장 기본값.
환경 변수나 .env에서 온 값은 해당 세션 동안 파일의 값을 덮어쓰지만, 파일에 다시 기록되지는 않습니다.
AI Game Developer 창
| 섹션 | 할 수 있는 작업 |
|---|---|
| 헤더 | Log Level(Trace, Debug, Info, Warning, Error, Exception, None)을 선택하고, Open log file로 프로젝트의 로그 폴더를 열고, 플러그인 Version을 확인합니다 |
| 연결 | Custom / Cloud 전환, Cloud 모드에서 Authorize, Cancel, Revoke, Custom 모드에서 Server URL 설정, Connect / Disconnect / Stop, Unreal과 MCP 서버, 연결된 AI 에이전트의 상태 및 IPC 브리지 포트 확인 |
| MCP 서버 (Custom 모드) | 로컬 gamedev-mcp-server를 Start / Stop하고, Transport(http 또는 stdio)와 Authorization 모드(none, token, oauth)를 선택하고, New로 토큰을 생성합니다 |
| AI 에이전트 | 에이전트를 선택한 뒤 해당 MCP 항목을 Configure, Reconfigure, Remove하고, Tutorial 또는 Download / Docs를 열고, Generate skill files, 프로젝트 키에 대해 Regenerate key를 실행합니다 |
| 확장 | 설치된 확장과 사용 가능한 확장 확인, Refresh catalog, Install 또는 Update, 실행 중 확장 활성화/비활성화, Compile (Live Coding) |
| 푸터 | Help / Talk(Discord), Bug Report(GitHub), GitHub Star, Restart bridge |
연결 방법은 Connecting AI clients, 확장은 Extensions에서 확인하세요.
MCP Tools 창: 도구별 표시 여부
Tools → MCP Tools를 엽니다. 창에는 등록된 모든 도구의 제목, 패밀리, 설명과 도구별 Visible 체크박스, 그리고 "27 / 27 tools visible" 같은 요약이 표시됩니다.
- Visible은
tools/list에서 해당 도구가 AI 에이전트에 나열되는지를 결정합니다. 필요 없는 도구를 숨기면 에이전트의 도구 목록이 짧게 유지되어 토큰을 절약할 수 있습니다. - 이는 접근 제어가 아닙니다. 숨긴 도구도 클라이언트가 이름으로 호출하면 여전히 실행되며,
unreal-tool-list는 숨긴 도구를 (숨김 표시와 함께) 보여 주므로 에이전트가 찾을 수 있습니다. - 선택 사항은
hiddenTools로 저장되며 에디터 재시작과 확장 재로드 후에도 유지됩니다.
도구가 아예 제공되지 않게 하려면 아래의 UNREAL_MCP_TOOLS 화이트리스트를 사용하세요.
기타 창
Tools 메뉴에는 MCP Prompts와 MCP Resources 창도 있습니다. 현재 릴리스에서는 이 창들이 비어 있음 안내 메시지를 표시하지만, 플러그인이나 확장이 등록한 프롬프트와 리소스는 AI 클라이언트에서 계속 동작합니다. Serialization Check 창은 선택한 액터나 오브젝트를 JSON으로 직렬화하여 도구가 보는 내용을 확인할 수 있게 해 줍니다.
환경 변수
플러그인은 다음 UNREAL_MCP_* 변수를 프로세스 환경이나 프로젝트의 .env 파일에서 읽습니다:
| 변수 | 용도 |
|---|---|
UNREAL_MCP_CONNECTION_MODE | Cloud(기본값) 또는 Custom |
UNREAL_MCP_HOST | Custom 모드의 서버 URL, 예: http://localhost:<port> |
UNREAL_MCP_CLOUD_URL | 클라우드 기본 URL, 기본값은 ai-game.dev |
UNREAL_MCP_TOKEN | 인증 토큰. 비밀 값이므로 절대 커밋하지 마세요 |
UNREAL_MCP_AUTH_OPTION | Custom 모드 인증: none, token 또는 oauth (이전 값 required는 token으로 읽힘) |
UNREAL_MCP_KEEP_CONNECTED | 실행 시 연결을 자동으로 복원 (기본값 true) |
UNREAL_MCP_TOOLS | 제공할 도구 화이트리스트, 비어 있으면 필터 없음 |
UNREAL_MCP_START_SERVER | true: 에디터가 로컬 서버를 직접 시작하고(Custom 모드, http 전용) 종료 시 중지합니다 |
UNREAL_MCP_TRANSPORT | http 또는 stdio |
UNREAL_MCP_LOG_LEVEL | 로그 상세 수준 |
UNREAL_MCP_TOOL_TIMEOUT | 도구 호출 한 번의 최대 시간(밀리초), 기본값 300000(5분) |
UNREAL_MCP_BRIDGE_PATH | 브리지 바이너리 경로, 번들된 것보다 우선하는 개발자용 재정의 |
UNREAL_MCP_SERVER_PATH | 로컬 gamedev-mcp-server의 경로입니다. unreal-mcp-cli가 읽으며, 서버 다운로드를 건너뜁니다 |
팁: 긴 python-execute 스크립트나 큰 에셋 임포트가 타임아웃되면 UNREAL_MCP_TOOL_TIMEOUT을 높이세요. 에디터가 도구를 시작하기 전에 타임아웃된 도구 호출은 나중에 실행되지 않고 건너뜁니다.
CLI로 .env 작성하기
unreal-mcp-cli configure는 이 값들을 <project>/.env에 쓰고 프로젝트의 .gitignore에 .env를 추가합니다:
unreal-mcp-cli configure --path ./YourProject --mode Custom --host http://localhost:23456 --start-serverUnreal 프로젝트 템플릿에는 .gitignore가 없으므로, 명령이 필요하면 새로 만듭니다. 건드리지 않으려면 --no-gitignore를 전달하세요. 모든 플래그는 CLI 레퍼런스에 있습니다.
경고: .env를 절대 커밋하지 마세요. UNREAL_MCP_TOKEN이 들어 있을 수 있습니다.
디스크에 있는 자격 증명과 키
| 파일 | 내용 |
|---|---|
~/.ai-game-dev/credentials.json | 머신 전체에 적용되는 ai-game.dev 로그인으로, 앱, 플러그인, CLI와 공유됩니다 |
~/.ai-game-dev/project-keys.json | Cloud MCP 구성에서 사용되는 캐시된 프로젝트 키 |
<project>/Saved/Config/UnrealMcp/ai-game-developer-config.json | 플러그인의 프로젝트별 설정 |
<project>/.env | 선택적 재정의 값이며, 절대 커밋되지 않습니다 |
포트
- 로컬 MCP 서버는 프로젝트 경로에서 계산된 20000~29999 사이의 고정된 프로젝트별 포트를 사용합니다. CLI도 같은 번호를 계산하므로 구성이 필요 없습니다.
- 플러그인과 그 브리지는 30000~39999 사이의 루프백 포트로 통신합니다(충돌 시 다음 빈 포트). 창에 "IPC bridge port"로 표시됩니다.
이 포트들을 네트워크에 열 필요는 없습니다. 둘 다 로컬입니다.