구성
AI Game Developer 창에서 Unity MCP 구성하기 - Cloud 및 Custom 모드, 로컬 서버, 포트, 전송 방식, 인증, 도구, 재정의, CI.
대부분의 프로젝트에는 구성이 필요 없습니다. 플러그인을 설치하고, 로그인한 뒤, 사용하는 에이전트에 맞춰 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 참고).
- 도움말 링크: 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 도구를 사용하거나 터미널에서 표시 여부를 변경할 수도 있습니다:
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를 쉼표로 구분한 목록. 나머지는 모두 숨겨짐 |
명령줄 인자가 환경 변수보다 우선합니다. 로컬 서버에 연결하는 배치 모드 에디터의 예입니다:
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-tokenunity-mcp-cli open이 이 변수들을 대신 설정합니다. CLI reference를 참고하세요.
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를 참고하세요.
MCP 서버 직접 호스팅
이 서버는 공용 GameDev-MCP-Server이며, Docker 이미지 aigamedeveloper/mcp-server로도 배포됩니다:
docker run -p 8080:8080 aigamedeveloper/mcp-server그런 다음 플러그인을 Custom으로 설정하고 Server URL을 http://localhost:8080(또는 사용하는 호스트)으로 지정한 뒤, 에이전트도 같은 주소를 가리키게 하세요. 서버는 --port, --client-transport, --authorization, --idle-timeout-seconds 같은 설정이나 대응하는 MCP_PLUGIN_* 환경 변수를 받아들입니다. 서버 문서에 전체 목록이 있습니다.
관련 페이지
- 에이전트 설정과 로그인은 AI 클라이언트 연결을 참고하세요.
- 연결 문제는 문제 해결을 참고하세요.