# 구성 — Unity · AI Game Developer Wiki

AI Game Developer 창에서 Unity MCP 구성하기 - Cloud 및 Custom 모드, 로컬 서버, 포트, 전송 방식, 인증, 도구, 재정의, CI.

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

대부분의 프로젝트에는 구성이 필요 없습니다. 플러그인을 설치하고, 로그인한 뒤, 사용하는 에이전트에 맞춰 **Configure**를 클릭하면 됩니다. 이 페이지에서는 AI Game Developer 창의 각 설정이 무엇을 하는지, 설정이 어디에 저장되는지, 자동화를 위해 이를 어떻게 재정의하는지, 그리고 CI와 플레이어 빌드에서 플러그인이 어떻게 동작하는지 설명합니다.

## AI Game Developer 창

**Window > AI Game Developer — MCP** (Ctrl+Alt+A, macOS에서는 Cmd+Option+A) 또는 Scene View 툴바의 **AI** 버튼으로 엽니다. 위에서 아래로 다음 항목이 있습니다:

- **Log Level**, **Timeout (ms)**, **Tool timeout (ms)**, 그리고 플러그인 **Version**.
- **Connection**: **Custom** / **Cloud** 전환 스위치와 선택한 모드의 설정.
- 연결 타임라인: **Unity**(**Connect** / **Disconnect** 버튼 포함), **MCP server**, **AI agent**.
- 각 클라이언트용 구성 도구가 있는 **AI agent** 드롭다운: **Configure** / **Remove**가 있는 **Model Context Protocol (MCP)**, 그리고 **Auto-generate**와 **Generate**가 있는 **Skills**.
- **Tools**, **Prompts**, **Resources** 카운터로, 각각 **Open** 버튼이 있습니다.
- **Extensions**: 선택적 도구 팩을 설치합니다([Extensions](https://ai-game.dev/ko/docs/wiki/unity/extensions) 참고).
- 도움말 링크: **Help / Talk**(Discord), **Bug Report**(GitHub issues), 그리고 직렬화 진단을 위한 **Check** 버튼.

## 연결 모드

### Cloud (기본값)

플러그인은 `https://ai-game.dev/mcp`에 호스팅된 서버에 연결합니다. 로컬 서버는 시작되지 않으며 URL은 편집할 수 없습니다. Cloud 모드에서는 로그인이 필요합니다. **Cloud Token** 옆의 **Authorize**를 클릭하고 브라우저에서 기기 코드를 승인하거나, `unity-mcp-cli login` 또는 AI Game Dev 앱으로 한 번 로그인하세요. **Revoke**는 해당 머신의 모든 AI Game Dev 도구에서 로그아웃합니다.

### Custom (로컬 또는 자체 서버)

플러그인은 **Server URL**에 있는 URL에 연결합니다. 기본값은 `http://localhost:<port>`의 로컬 서버이며, 플러그인이 서버(`gamedev-mcp-server`)를 대신 다운로드하고 시작하고 중지합니다. 직접 호스팅하는 원격 MCP 서버의 URL을 입력할 수도 있습니다. **Server URL**은 Unity가 서버에 연결되어 있지 않을 때만 편집할 수 있습니다.

Custom 모드에서는 다음 설정이 추가됩니다:

- **MCP server**: **Start** / **Stop** 버튼과 상태(Running, Starting, Stopping, Downloading, 또는 다른 프로세스가 이미 해당 포트를 사용 중일 때는 External). 바이너리 다운로드가 실패하면 **Download / Retry server**가 표시됩니다.
- **Transport**: `http`(권장) 또는 `stdio`. `http`를 사용하면 에이전트가 실행 중인 서버에 연결하고, 여러 에이전트가 서버를 공유할 수 있으며, 서버가 다른 머신에서 실행될 수 있습니다. `stdio`를 사용하면 에이전트가 서버를 자체 자식 프로세스로 실행하고, 하나의 에이전트만 연결할 수 있으며, Start / Stop 버튼이 비활성화됩니다.
- **Authorization Token**: `none`, `oauth` 또는 `token`.
  - `none`: 서버가 모든 연결을 허용합니다. 다른 머신에서 포트에 접근할 수 없을 때만 안전합니다.
  - `oauth`: 에이전트가 자신의 ai-game.dev 계정으로 로그인하며, 서버가 온라인으로 토큰을 검사합니다.
  - `token`: 공유 비밀 값으로, 완전히 오프라인입니다. **New**를 클릭해 토큰을 생성한 뒤 **Configure**를 클릭하세요(또는 토큰을 에이전트 설정에 직접 복사하세요).

## 포트

로컬 포트는 8080처럼 고정된 값이 아닙니다. 프로젝트 폴더에서 파생됩니다. 정규화된 프로젝트 경로의 SHA-256 해시를 **20000에서 29999** 범위로 매핑한 값입니다. 같은 프로젝트는 항상 같은 포트를 받고, 다른 프로젝트는 다른 포트를 받으므로 여러 Unity 인스턴스가 나란히 실행될 수 있습니다. CLI도 같은 공식을 사용하므로, 플래그 없이도 명령이 올바른 서버를 찾습니다.

다른 포트를 사용하려면 연결을 끊은 뒤 **Server URL**에 입력하세요(예: `http://localhost:25000`). 구성 도구는 입력한 포트를 에이전트 설정에 기록합니다.

## 설정 파일

설정은 사용자별로 `UserSettings/AI-Game-Developer-Config.json`에 저장되며 첫 실행 시 생성됩니다. 주요 키는 다음과 같습니다:

| 키 | 의미 | 기본값 |
| --- | --- | --- |
| `connectionMode` | `Cloud` 또는 `Custom` | `Cloud` |
| `host` | Custom 모드의 서버 URL | `http://localhost:<port>` |
| `token` | `token` 인증 모드에서 사용하는 공유 토큰 | 생성됨 |
| `transportMethod` | `streamableHttp` 또는 `stdio` | `streamableHttp` |
| `authOption` | `none`, `oauth` 또는 `token` | `none` |
| `keepConnected` | 서버에 자동으로 연결 | CI에서는 `true`, `false` |
| `keepServerRunning` | 로컬 서버를 시작하고 계속 실행 | CI에서는 `true`, `false` |
| `logLevel` | `Trace`, `Debug`, `Information`, `Warning`, `Error`, `Critical` | `Warning` |
| `timeoutMs` | 플러그인-서버 타임아웃 | `10000` |
| `toolTimeoutMs` | 도구 호출 하나가 실행될 수 있는 시간 | `300000` |
| `tools`, `prompts`, `resources` | 항목별 표시 여부 | 기본값 |

Cloud 자격 증명은 여기에 저장되지 않으며 `~/.ai-game-dev/credentials.json`에 있습니다. 처음부터 다시 시작하려면 **Tools > AI Game Developer > Reset Config**를 사용하세요. 기본값을 복원하고 스크립트를 다시 로드합니다.

## 도구, 프롬프트, 리소스

**Tools** 카운터는 설치된 도구 중 에이전트가 보는 도구 수와, 그것이 AI 컨텍스트에서 차지하는 토큰의 추정치를 보여줍니다. **Open**을 클릭해 개별 도구를 표시하거나 숨기세요. **MCP Prompts**와 **MCP Resources** 창도 같은 방식으로 동작합니다.

숨긴 도구가 삭제되는 것은 아닙니다. 에이전트의 도구 목록에서 사라질 뿐, 이름으로 호출되면 여전히 실행됩니다. 표시되는 도구가 적을수록 추론에 더 많은 컨텍스트가 남습니다. `tool-set-visibility` 도구를 사용하거나 터미널에서 표시 여부를 변경할 수도 있습니다:

```bash
unity-mcp-cli configure ./MyUnityProject --enable-tools screenshot-scene-view,script-read
unity-mcp-cli configure ./MyUnityProject --list
```

## 환경 변수 및 명령줄 재정의

CI와 스크립트 실행을 위해 플러그인은 시작 시 다음 변수(또는 대응하는 Unity 명령줄 인자)를 읽습니다. 재정의는 메모리에만 적용되며 설정 파일에 기록되지 않습니다.

| 변수 | 명령줄 인자 | 값 |
| --- | --- | --- |
| `UNITY_MCP_CLOUD_URL` | `-url` | 서버 URL (`UNITY_MCP_HOST`는 레거시 별칭) |
| `UNITY_MCP_CONNECTION_MODE` | `-UNITY_MCP_CONNECTION_MODE` | `Cloud` 또는 `Custom`; 루프백 URL이면 `Custom` |
| `UNITY_MCP_KEEP_CONNECTED` | `-UNITY_MCP_KEEP_CONNECTED` | `true` 또는 `false` |
| `UNITY_MCP_AUTH_OPTION` | `-auth` | `none`, `oauth` 또는 `token` |
| `UNITY_MCP_TOKEN` | `-token` | 로컬 서버 토큰 |
| `UNITY_MCP_TRANSPORT` | `-UNITY_MCP_TRANSPORT` | `stdio` 또는 `streamableHttp` |
| `UNITY_MCP_START_SERVER` | `-UNITY_MCP_START_SERVER` | `true` 또는 `false` |
| `UNITY_MCP_TOOLS` | `-UNITY_MCP_TOOLS` | 표시할 도구 id를 쉼표로 구분한 목록. 나머지는 모두 숨겨짐 |

명령줄 인자가 환경 변수보다 우선합니다. 로컬 서버에 연결하는 배치 모드 에디터의 예입니다:

```bash
Unity -batchmode -projectPath ./MyUnityProject \
  -UNITY_MCP_CLOUD_URL=http://localhost:8080 \
  -UNITY_MCP_KEEP_CONNECTED=true \
  -UNITY_MCP_AUTH_OPTION=token \
  -UNITY_MCP_TOKEN=my-secret-token
```

`unity-mcp-cli open`이 이 변수들을 대신 설정합니다. [CLI reference](https://ai-game.dev/ko/docs/wiki/unity/cli#open)를 참고하세요.

## CI에서 Unity MCP 비활성화

플러그인은 CI 환경을 감지하면 서버 다운로드와 자동 연결을 건너뜁니다. 일반적인 CI 테스트 작업에서 완전히 끄려면 두 가지 방법 중 하나를 사용하세요:

- **`UNITY_MCP_DISABLE=1`**(또는 `true`)을 Unity를 실행하는 프로세스의 환경에 설정합니다. 플러그인은 시작, 도구 등록, 서버 다운로드, NuGet 확인 및 에디터 훅을 건너뜁니다. 코드는 여전히 컴파일되므로 프로젝트는 계속 컴파일되어야 합니다.
- **Project Settings > Player > Other Settings**에서 \*\*`UNITY_MCP_EXCLUDE_FROM_COMPILATION`\*\*을 Scripting Define Symbol로 설정합니다. 이렇게 하면 모든 플러그인 어셈블리(및 업데이트된 자사 확장)가 컴파일에서 제외됩니다. 플러그인 타입을 참조하는 자체 코드에는 `#if !UNITY_MCP_EXCLUDE_FROM_COMPILATION`이 필요합니다.

`-batchmode`나 `-runTests`에서는 둘 다 자동으로 활성화되지 않습니다. 헤드리스 MCP 세션에는 플러그인이 필요하기 때문입니다.

## 플레이어 빌드와 런타임

플러그인의 런타임 어셈블리는 모든 플랫폼용으로 컴파일되므로, 위의 정의로 제외하지 않는 한 플레이어 빌드에 포함됩니다. 빌드는 스스로 연결하지 않습니다. 게임에서는 코드에서 `UnityMcpPluginRuntime.Initialize(...)`로 옵트인하며, 이렇게 해서 게임 내 도구를 AI에 노출합니다(예: AI 체스 상대). [Custom tools](https://ai-game.dev/ko/docs/wiki/unity/custom-tools#runtime)를 참고하세요.

## MCP 서버 직접 호스팅

이 서버는 공용 [GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server)이며, Docker 이미지 `aigamedeveloper/mcp-server`로도 배포됩니다:

```bash
docker run -p 8080:8080 aigamedeveloper/mcp-server
```

그런 다음 플러그인을 **Custom**으로 설정하고 **Server URL**을 `http://localhost:8080`(또는 사용하는 호스트)으로 지정한 뒤, 에이전트도 같은 주소를 가리키게 하세요. 서버는 `--port`, `--client-transport`, `--authorization`, `--idle-timeout-seconds` 같은 설정이나 대응하는 `MCP_PLUGIN_*` 환경 변수를 받아들입니다. [서버 문서](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/mcp-server.md)에 전체 목록이 있습니다.

## 관련 페이지

- 에이전트 설정과 로그인은 [AI 클라이언트 연결](https://ai-game.dev/ko/docs/wiki/unity/connecting-ai-clients)을 참고하세요.
- 연결 문제는 [문제 해결](https://ai-game.dev/ko/docs/wiki/unity/troubleshooting)을 참고하세요.

---

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

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