# AI 클라이언트 연결 — Unreal Engine · AI Game Developer Wiki

Claude Code, Cursor, Copilot, Codex, Gemini 및 기타 MCP 클라이언트를 ai-game.dev 클라우드 엔드포인트 또는 로컬 서버를 통해 Unreal MCP에 연결합니다.

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

이 페이지는 AI 클라이언트가 Unreal Editor에 도달하는 방식, 로그인이 작동하는 방식, 지원되는 각 에이전트용 MCP 설정을 작성하는 방법을 설명합니다. 가장 빠른 방법만 원한다면 에디터의 **AI agent** 섹션에 있는 **Configure** 버튼([Getting started](https://ai-game.dev/ko/docs/wiki/unreal/getting-started#ai-client) 참고)이 이 모든 것을 대신 처리합니다.

## Cloud 또는 Custom: 연결 모드 선택

AI Game Developer 창의 **Connection** 섹션에는 **Custom / Cloud** 스위치가 있습니다. 동일한 설정은 `UNREAL_MCP_CONNECTION_MODE`입니다([Configuration](https://ai-game.dev/ko/docs/wiki/unreal/configuration) 참고).

|  | Cloud (기본값) | Custom |
| --- | --- | --- |
| 서버 | ai-game.dev의 호스팅 엔드포인트 | 직접 실행하는 `gamedev-mcp-server`로, 보통 `localhost`에서 실행됩니다 |
| 로그인 | ai-game.dev 계정, 디바이스 코드 흐름 | 선택 사항: 없음, 공유 토큰 또는 OAuth |
| 로컬에서 실행되는 것 | 에디터와 그 브리지 | 에디터, 그 브리지 그리고 로컬 서버 |
| 적합한 경우 | 대부분의 사용자, 여러 머신, 방화벽을 넘나드는 작업 | 완전한 로컬 구성, 오프라인 작업, CI |

## Cloud 모드

Cloud 모드에서 브리지는 ai-game.dev에 연결되고 AI 클라이언트는 동일한 엔드포인트인 `https://ai-game.dev/mcp`에 연결됩니다. 서버는 클라이언트의 도구 호출을 에디터로 라우팅합니다. 엔드포인트 자체에 대해서는 [MCP 엔드포인트 페이지](https://ai-game.dev/ko/mcp-endpoint-info)를 참고하세요.

### 디바이스 코드 흐름으로 로그인

로그인은 머신당 한 번만 하면 됩니다. 다음 중 무엇이든 사용할 수 있으며, 모두 앱, 다른 엔진 플러그인 및 CLI와 동일한 자격 증명 저장소(`~/.ai-game-dev/credentials.json`)를 공유합니다:

- 에디터에서: **Cloud**를 선택하고 **Authorize**를 클릭한 다음, 인증 페이지를 열고 창에 표시된 사용자 코드를 입력하고 승인합니다.
- 터미널에서: `unreal-mcp-cli login`.
- AI Game Dev 앱에서: 평소처럼 로그인합니다.

**Warning:** 에디터의 **Revoke**는 이 프로젝트만이 아니라 머신 전체를 로그아웃시킵니다. 자격 증명을 공유하는 모든 AI Game Dev 도구(엔진 플러그인, CLI, 데스크톱 앱)가 로그아웃되기 때문에 에디터가 먼저 확인을 요청합니다.

계정, 디바이스, 토큰의 작동 방식은 [인증 페이지](https://ai-game.dev/docs/auth)에서 다룹니다.

### 프로젝트에 고정된 URL

계정에 여러 에디터가 연결되어 있다면 일반 `https://ai-game.dev/mcp` URL을 사용하는 클라이언트가 엉뚱한 에디터에 도달할 수 있습니다. 그래서 플러그인과 `unreal-mcp-cli setup-mcp`는 기본적으로 **프로젝트에 고정된** URL을 기록합니다:

```text
https://ai-game.dev/mcp/p/<pin>
```

고정 값은 프로젝트 폴더에서 파생되므로 클라이언트는 항상 이 프로젝트의 에디터로 라우팅됩니다. 대신 일반 URL을 기록하려면 `setup-mcp --no-pin`을 사용하세요.

### 프로젝트 키

머신이 로그인되어 있으면 Cloud 설정에는 이 프로젝트에 바인딩된 `Authorization: Bearer agd_pk_…` 헤더인 **프로젝트 키**도 함께 포함됩니다. 이 키가 있으면 에이전트는 자체 로그인이 필요 없습니다. 이 키는 만료되지 않고 폐기할 수 있으며, `~/.ai-game-dev/project-keys.json`에 캐시되어 프로젝트의 모든 에이전트가 재사용합니다.

- `setup-mcp --oauth`는 대신 URL만 있는 설정을 기록합니다. 그러면 에이전트가 자체 OAuth 로그인을 수행합니다.
- `setup-mcp --regenerate-key` 또는 에디터의 AI agent 섹션에 있는 **Regenerate key** 버튼은 새 키를 생성하고, 설정된 에이전트들을 새 키로 다시 작성하며, 이전 키를 폐기합니다.
- 명시적인 `--token`이 둘 모두보다 우선합니다.

머신이 로그인되어 있지 않으면 설정에는 URL만 포함되며 에이전트가 자체적으로 로그인합니다.

## Custom 모드: 로컬 서버

Custom 모드에서 브리지는 직접 제어하는 서버, 보통 머신에서 실행 중인 공유 `gamedev-mcp-server`에 연결됩니다. 각 프로젝트는 프로젝트 경로에서 파생된 20000~29999 범위의 고정 로컬 포트를 부여받으므로, 별도 설정 없이 에디터와 CLI가 같은 포트를 사용합니다.

에디터에서 실행하려면:

1. Connection 섹션을 **Custom**으로 전환합니다.
2. **MCP server** 카드에서 **http** 전송 방식을 선택하고 **Start**를 클릭합니다. 서버 릴리스가 없으면 에디터가 고정된 서버 릴리스를 다운로드하고, 서버를 시작하며, 에디터 종료 시 중지합니다. Start 버튼은 Custom 모드와 http 전송 방식에서만 작동합니다.
3. **Authorization** 모드를 선택합니다: **none**(로컬, 익명), **token**(공유 비밀; **New**로 생성하고 **Reveal**을 길게 눌러 확인), 또는 **oauth**.

대신 터미널에서 시작하려면 `unreal-mcp-cli open ./YourProject --start-server --connection-mode Custom`을 사용하거나, `unreal-mcp-cli configure`에서 `UNREAL_MCP_START_SERVER=true`를 설정하세요.

**참고:** 로컬 서버를 에디터로 지정했는데도 창에 여전히 Cloud라고 표시된다면, 브리지가 ai-game.dev에 연결되어 있고 로컬 서버는 "No connected clients"라고 응답하는 것입니다. Custom 모드를 명시적으로 설정하세요. `unreal-mcp-cli open`에 `--host`를 전달하면 Custom이 자동으로 선택됩니다.

## setup-mcp로 클라이언트 설정 작성하기

`unreal-mcp-cli setup-mcp <agent>`는 에이전트 하나에 대한 MCP 설정 항목을 작성합니다. 프로젝트에 저장된 연결 설정을 읽으므로, 먼저 에디터에서 프로젝트를 한 번 열어야 합니다(또는 `--url`을 전달하세요).

```bash
# Claude Code: writes .mcp.json in the project
unreal-mcp-cli setup-mcp claude-code --path ./YourProject

# Cursor, with the local server over stdio instead of http
unreal-mcp-cli setup-mcp cursor --path ./YourProject --transport stdio

# Print the snippet without writing anything
unreal-mcp-cli setup-mcp vscode-copilot --path ./YourProject --dry-run

# List every agent and its config path
unreal-mcp-cli setup-mcp --list
```

`--transport stdio`를 사용하면 CLI가 고정된 `gamedev-mcp-server` 릴리스를 `<project>/Intermediate/UnrealMCP/server/`에 내려받고, 에이전트가 그 서버를 직접 시작합니다.

### 지원하는 에이전트

| 에이전트 | `setup-mcp` ID | 설정 파일 |
| --- | --- | --- |
| Claude Code | `claude-code` | `.mcp.json` (프로젝트) |
| Claude Desktop | `claude-desktop` | `claude_desktop_config.json` (사용자) |
| Cursor | `cursor` | `.cursor/mcp.json` (프로젝트) |
| Visual Studio Code (Copilot) | `vscode-copilot` | `.vscode/mcp.json` (프로젝트) |
| Visual Studio (Copilot) | `vs-copilot` | `.vs/mcp.json` (프로젝트) |
| Rider (Junie) | `rider-junie` | `.junie/mcp/mcp.json` (프로젝트) |
| GitHub Copilot CLI | `github-copilot-cli` | `~/.copilot/mcp-config.json` (사용자) |
| Gemini | `gemini` | `.gemini/settings.json` (프로젝트) |
| Antigravity | `antigravity` | `~/.gemini/` 아래의 `mcp_config.json` (사용자) |
| Cline | `cline` | VS Code의 전역 저장소에 있는 `cline_mcp_settings.json` (사용자) |
| Open Code | `open-code` | `opencode.json` (프로젝트) |
| Codex | `codex` | `.codex/config.toml` (프로젝트) |
| Kilo Code | `kilo-code` | `.kilocode/mcp.json` (프로젝트) |
| 기타 다른 MCP 클라이언트 | `custom` | `mcp.json` (프로젝트) |

에디터의 **AI agent** 드롭다운은 같은 방식의 원클릭 설정을 제공하며, 항목을 삭제하는 **Remove**, **Tutorial** 및 **Download / Docs** 링크, 스킬을 지원하는 에이전트를 위한 **Generate skill files**도 제공합니다.

## Claude Code와 Unreal Engine

Claude Code는 실행한 폴더에서 `.mcp.json`을 읽습니다. 따라서 Unreal에서 Claude Code를 사용하려면:

1. `unreal-mcp-cli setup-mcp claude-code --path ./YourProject`를 실행하세요(또는 에디터에서 Claude Code를 선택한 상태로 **Configure** 클릭).
2. 프로젝트 폴더에서 Claude Code를 시작하세요.
3. "list the actors in the current level"이라고 요청하여 Unreal 도구를 사용할 수 있는지 확인하세요.

선택적으로 `unreal-mcp-cli setup-skills --path ./YourProject`를 실행하면 Claude에게 이 프로젝트의 MCP 서버를 다루는 방법을 알려주는 Claude Code 스킬(`.claude/skills/unreal-mcp/SKILL.md`)이 작성됩니다.

## 기타 클라이언트

위에 나열되지 않은 클라이언트를 포함한 다양한 클라이언트용 설정 스니펫이 [MCP 엔드포인트 페이지](https://ai-game.dev/ko/mcp-endpoint-info)에 준비되어 있습니다. [에코시스템 개요](https://ai-game.dev/ko/docs/ecosystem)에서는 서버, 플러그인, 앱이 함께 동작하는 방식을 확인할 수 있습니다.

---

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

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