# 설정 — Unreal Engine · AI Game Developer Wiki

Unreal MCP 설정 - AI Game Developer 창, MCP Tools 표시 여부, 프로젝트 설정 파일, .env, 그리고 모든 UNREAL_MCP_* 환경 변수를 다룹니다.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/unreal/configuration).

이 페이지는 현재 Unreal MCP의 모든 설정과 각 설정을 변경하는 위치를 정리합니다. 대부분의 사용자는 연결 모드와 AI 에이전트 설정만 건드리며, 나머지는 튜닝, 자동화, CI를 위한 것입니다.

## 설정이 저장되는 위치

Unreal MCP에는 에디터 연결을 위한 Project Settings 페이지가 없습니다. 모든 설정은 **AI Game Developer** 창(Tools 메뉴)에 있으며, 프로젝트별로 다음 위치에 저장됩니다:

```text
<YourProject>/Saved/Config/UnrealMcp/ai-game-developer-config.json
```

`Saved/`는 모든 Unreal 프로젝트 템플릿에서 버전 관리에서 제외되므로, 이 파일의 토큰은 기본적으로 저장소에 포함되지 않습니다.

설정은 다음 순서로 읽히며, 우선순위가 높은 것이 먼저입니다:

1. 프로세스 환경 변수 (예: `unreal-mcp-cli open` 또는 셸에서 설정한 값).
2. 프로젝트 루트의 `.env` 파일.
3. 위의 설정 파일.
4. 내장 기본값.

환경 변수나 `.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](https://ai-game.dev/ko/docs/wiki/unreal/connecting-ai-clients), 확장은 [Extensions](https://ai-game.dev/ko/docs/wiki/unreal/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`를 추가합니다:

```bash
unreal-mcp-cli configure --path ./YourProject --mode Custom --host http://localhost:23456 --start-server
```

Unreal 프로젝트 템플릿에는 `.gitignore`가 없으므로, 명령이 필요하면 새로 만듭니다. 건드리지 않으려면 `--no-gitignore`를 전달하세요. 모든 플래그는 [CLI 레퍼런스](https://ai-game.dev/ko/docs/wiki/unreal/cli#configure)에 있습니다.

**경고:** `.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"로 표시됩니다.

이 포트들을 네트워크에 열 필요는 없습니다. 둘 다 로컬입니다.

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/unreal/configuration

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/unreal/configuration