자주 묻는 질문

Unity용 AI Game Developer 플러그인인 Unity MCP에 대해 가장 많이 나오는 질문에 짧게 답합니다. 각 답변에는 자세한 내용이 담긴 페이지 링크가 있습니다.

일반#

Unity MCP란 무엇인가요?#

AI 에이전트가 Model Context Protocol을 통해 프로젝트에서 작업할 수 있게 해주는 Unity 에디터 플러그인입니다. 에이전트는 씬, GameObject, 컴포넌트, 프리팹, 에셋을 읽고 변경할 수 있으며, C# 코드를 작성하고 실행하고, 테스트를 실행하고, 스크린샷을 찍을 수 있습니다. 개요를 참고하세요.

플러그인은 무료이며 오픈 소스인가요?#

플러그인은 Apache-2.0 라이선스로 오픈 소스이며 Unity-MCP 저장소에 있습니다. Custom 모드는 로컬 서버를 실행하므로 계정이 필요 없습니다. Cloud 모드는 ai-game.dev 계정을 사용하며, 요금제는 가격 페이지에서 확인할 수 있습니다.

어떤 Unity 버전을 지원하나요?#

Unity 6을 포함해 Unity 2022.3 이상입니다.

어떤 AI 클라이언트와 함께 사용할 수 있나요?#

AI Game Developer 창에는 Claude Code, Claude Desktop, Cursor, Visual Studio Code (Copilot), Visual Studio (Copilot), Rider (Junie), GitHub Copilot CLI, Gemini, Antigravity, Cline, Open Code, Codex, Kilo Code, Zoo Code, Unity AI용 구성 도구가 있으며, 그 밖의 다른 MCP 클라이언트를 위한 사용자 지정 항목도 있습니다. AI 클라이언트 연결을 참고하세요.

직접 AI 클라이언트를 준비해야 하나요?#

아니요. AI Game Dev 데스크톱 앱에는 에이전트가 포함되어 있고, 플러그인을 설치하고 연결해 줍니다. 이미 Claude Code, Cursor 또는 다른 MCP 클라이언트를 사용 중이라면 기존 클라이언트를 그대로 사용해도 됩니다.

설정#

가장 쉬운 설치 방법은 무엇인가요?#

데스크톱 앱입니다. 데스크톱 앱 없이 사용하려면 unity-mcp-cli install-plugin을 실행하거나 OpenUPM 또는 .unitypackage 설치 프로그램을 사용하세요. 설치를 참고하세요.

플러그인 창은 어디에 있나요?#

Window > AI Game Developer — MCP, 단축키 Ctrl+Alt+A(macOS에서는 Cmd+Option+A), 또는 Scene View 툴바의 AI 버튼입니다.

Cloud 모드와 Custom 모드의 차이는 무엇인가요?#

기본값인 Cloud 모드에서는 에디터와 AI 클라이언트가 https://ai-game.dev/mcp에 연결되며 한 번만 로그인하면 됩니다. Custom 모드에서는 플러그인이 프로젝트 경로에서 파생된 포트로 로컬 MCP 서버를 실행하며, 모든 것이 사용자의 컴퓨터에 남습니다. 구성을 참고하세요.

포트를 직접 선택해야 하나요?#

아니요. 포트는 프로젝트 경로에서 파생되므로(범위 20000~29999) 프로젝트마다 고정되어 있고 프로젝트 간에는 서로 다릅니다. Server URL에서 직접 재정의할 수 있습니다.

설정은 어디에 저장되나요?#

프로젝트 내 UserSettings/AI-Game-Developer-Config.json에 저장됩니다. ai-game.dev 로그인 정보는 머신당 한 번씩 ~/.ai-game-dev/credentials.json에 저장됩니다.

여러 Unity 프로젝트를 동시에 사용할 수 있나요?#

네. 각 프로젝트에는 자체 포트가 있으며, 고정 URL(https://ai-game.dev/mcp/p/<pin>)이 각 에이전트를 올바른 에디터로 연결합니다.

사용 방법#

gameobject-create 같은 도구들은 어디로 갔나요?#

버전 1.0.0에서는 동작마다 도구가 하나씩 있던 방식을 RQL로 대체했습니다. rql-query, rql-mutate, rql-schema가 씬, GameObject, 컴포넌트, 에셋, Console, 에디터 상태를 다룹니다. 도구와 RQL을 참고하세요.

AI가 자신의 변경 사항을 실행 취소할 수 있나요?#

각 rql-mutate 호출은 하나의 Undo 단계로 기록되므로 Ctrl+Z(Cmd+Z)로 되돌릴 수 있습니다. 그보다 큰 변경에는 버전 관리를 사용하세요.

에이전트에는 왜 몇 개의 도구만 보이나요?#

컨텍스트를 절약하기 위해서입니다. 기본적으로 7개의 도구가 표시되며, 나머지는 설치되어 있지만 숨겨져 있고 이름으로 호출하면 여전히 실행됩니다. 창의 Tools > Open에서 더 표시할 수 있습니다.

나만의 도구를 추가할 수 있나요?#

네. 클래스에 [AiToolType]을, 메서드에 [AiTool]을 표시하면 됩니다. 사용자 지정 도구를 참고하세요.

Cinemachine, ProBuilder, Tilemaps 지원을 어떻게 추가하나요?#

창의 Extensions 섹션에서 해당 확장을 설치하거나 unity-mcp-cli install-extension으로 설치하세요. 확장을 참고하세요.

Play 모드에서도 작동하나요?#

네. 에이전트는 RQL(isPlaying과 같은 editor 멤버)을 통해 Play 모드에 들어가고 나올 수 있습니다. 도메인 리로드가 끝나면 연결이 다시 수립됩니다.

빌드, CI, 개인정보 보호#

플러그인이 게임 빌드에 포함되나요?#

런타임 부분은 플레이어 빌드에 컴파일되지만, 빌드가 스스로 연결되는 일은 없습니다. 게임 안에서 AI에 도구를 제공하려면 코드에서 UnityMcpPluginRuntime.Initialize(...)를 호출해 직접 활성화해야 합니다. 플러그인을 완전히 제외하려면 UNITY_MCP_EXCLUDE_FROM_COMPILATION 스크립팅 심볼을 추가하세요. 구성을 참고하세요.

CI 테스트 실행에서 플러그인을 제외하려면 어떻게 하나요?#

Unity 프로세스의 환경에 UNITY_MCP_DISABLE=1을 설정하거나 UNITY_MCP_EXCLUDE_FROM_COMPILATION 정의를 사용하세요. Configuration을 참고하세요.

AI 클라이언트 없이 스크립트로 실행할 수 있나요?#

네. unity-mcp-cli run-tool은 터미널에서 모든 도구를 호출하고, unity-mcp-cli exec는 에디터에서 C#을 실행합니다. CLI reference를 참고하세요.

어떤 데이터가 제 머신 밖으로 나가나요?#

Custom 모드에서 none 또는 token 권한 부여를 사용하면 ai-game.dev를 거치는 데이터는 없습니다. 에이전트와 Unity는 로컬 서버를 통해 통신합니다. 다만 AI 클라이언트는 여전히 대화 내용을 자체 모델 제공자에게 전송합니다. Cloud 모드에서는 도구 호출과 결과가 에이전트와 에디터 사이를 오가는 동안 ai-game.dev 서버를 거칩니다.

팀 전체에 대해 업데이트 팝업을 끄려면 어떻게 하나요?#

Edit > Project Settings > AI Game Developer에서 Disable update notifications for the entire team을 활성화하고 ProjectSettings/AI-Game-Developer-UpdateSettings.asset을 커밋하세요.

추가 도움말#

• 오류에 대해서는 문제 해결을 참고하세요.
• 사이트 전체 FAQ와 Unity 모범 사례도 참고하세요.