AI 클라이언트 연결
Claude Code, Cursor, Copilot, Codex, Gemini 및 기타 MCP 클라이언트를 ai-game.dev 클라우드 엔드포인트 또는 로컬 서버를 통해 Unreal MCP에 연결합니다.
이 페이지는 AI 클라이언트가 Unreal Editor에 도달하는 방식, 로그인이 작동하는 방식, 지원되는 각 에이전트용 MCP 설정을 작성하는 방법을 설명합니다. 가장 빠른 방법만 원한다면 에디터의 AI agent 섹션에 있는 Configure 버튼(Getting started 참고)이 이 모든 것을 대신 처리합니다.
Cloud 또는 Custom: 연결 모드 선택
AI Game Developer 창의 Connection 섹션에는 Custom / Cloud 스위치가 있습니다. 동일한 설정은 UNREAL_MCP_CONNECTION_MODE입니다(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 엔드포인트 페이지를 참고하세요.
디바이스 코드 흐름으로 로그인
로그인은 머신당 한 번만 하면 됩니다. 다음 중 무엇이든 사용할 수 있으며, 모두 앱, 다른 엔진 플러그인 및 CLI와 동일한 자격 증명 저장소(~/.ai-game-dev/credentials.json)를 공유합니다:
- 에디터에서: Cloud를 선택하고 Authorize를 클릭한 다음, 인증 페이지를 열고 창에 표시된 사용자 코드를 입력하고 승인합니다.
- 터미널에서:
unreal-mcp-cli login. - AI Game Dev 앱에서: 평소처럼 로그인합니다.
Warning: 에디터의 Revoke는 이 프로젝트만이 아니라 머신 전체를 로그아웃시킵니다. 자격 증명을 공유하는 모든 AI Game Dev 도구(엔진 플러그인, CLI, 데스크톱 앱)가 로그아웃되기 때문에 에디터가 먼저 확인을 요청합니다.
계정, 디바이스, 토큰의 작동 방식은 인증 페이지에서 다룹니다.
프로젝트에 고정된 URL
계정에 여러 에디터가 연결되어 있다면 일반 https://ai-game.dev/mcp URL을 사용하는 클라이언트가 엉뚱한 에디터에 도달할 수 있습니다. 그래서 플러그인과 unreal-mcp-cli setup-mcp는 기본적으로 프로젝트에 고정된 URL을 기록합니다:
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가 같은 포트를 사용합니다.
에디터에서 실행하려면:
- Connection 섹션을 Custom으로 전환합니다.
- MCP server 카드에서 http 전송 방식을 선택하고 Start를 클릭합니다. 서버 릴리스가 없으면 에디터가 고정된 서버 릴리스를 다운로드하고, 서버를 시작하며, 에디터 종료 시 중지합니다. Start 버튼은 Custom 모드와 http 전송 방식에서만 작동합니다.
- 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을 전달하세요).
# 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를 사용하려면:
unreal-mcp-cli setup-mcp claude-code --path ./YourProject를 실행하세요(또는 에디터에서 Claude Code를 선택한 상태로 Configure 클릭).- 프로젝트 폴더에서 Claude Code를 시작하세요.
- "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 엔드포인트 페이지에 준비되어 있습니다. 에코시스템 개요에서는 서버, 플러그인, 앱이 함께 동작하는 방식을 확인할 수 있습니다.