
Unity 공식 MCP를 Codex로 사용하기 전에: Prefab·Console·Scene 조작의 안전 설계와 평가 방법
요약
Unity 공식 MCP Server를 활용하여 AI(Codex 등)가 Unity Editor의 Scene, Prefab, Console을 조작할 때 필요한 안전 설계 및 평가 방법을 다룹니다. 단순 코드 작성을 넘어 에디터 상태를 제어하는 과정에서의 권한 설계와 단계별 검증 절차를 제안합니다.
핵심 포인트
- Unity 공식 MCP Server를 통한 에디터 제어 및 AI 연동 방법 제시
- Console 읽기부터 Prefab 생성까지 단계별 안전 설계 및 평가 프로세스
- Assistant와 MCP Server 간의 설정 방향(Client vs Server) 구분 주의
- 실무 도입을 위한 자동 복구 및 수동 개입 등 정밀한 평가 지표 필요
서론
생성형 AI에게 C# 코드를 작성하게 하고, 차이점(diff)을 확인하여 Unity로 되돌리는 흐름은 이미 드문 일이 아닙니다. 하지만 Unity 개발에서는 Hierarchy 편집, Component 설정, Prefab 저장, Scene 전환, 컴파일 후 Console 확인까지 포함되어야 비로소 작업이 완료됩니다. 리포지토리 내의 파일만 보는 AI는 이러한 Editor 상태를 알 수 없습니다.
여기서 주목받는 것이 Unity 공식의 Unity MCP Server입니다. 외부 AI 클라이언트에서 Unity Editor로 접속하여 Scene, GameObject, Asset, Script, Console 등을 MCP Tool로서 다룰 수 있습니다.
본고에서는 Unity 공식 MCP를 Codex로부터 안전하게 사용하기 위한 접속 절차, 권한 설계, 실패 시 복구 방침, 도입 여부의 평가 방법을 정리합니다. 주제로 삼는 것은 다음 3가지 태스크입니다.
- Unity Console 읽기 및 최소 차분의 에러 수정
- Sandbox Scene 생성·편집·저장
- 지정된 구조의 Prefab 생성
평가 순서는 먼저 읽기 중심인 Console, 다음으로 버리기 쉬운 Sandbox Scene, 마지막으로 Asset으로 남는 Prefab 순으로 합니다. 갑자기 쓰기 범위가 넓은 작업으로 진행하지 않고, 전 단계에서 접속 대상·Tool 제한·재관측 절차가 성립했을 때만 다음 단계로 진행합니다.
목적은 한 번 작동한 데모를 보고 "실무에서도 쓸 수 있다"라고 성급하게 판단하지 않는 것입니다. 최초 성공, 자동 복구, 수동 개입, 대상 외 변경, Editor 정지까지 나누어 기록하여, 도입해도 좋은 조작 범위를 판단할 수 있는 상태를 만듭니다.
이 기사에서 말하는 "Unity 공식 MCP"
본고에서 다루는 것은 Unity의 com.unity.ai.assistant 패키지에 포함된 Unity MCP Server입니다. 커뮤니티 제작의 동명 또는 유사 MCP 서버는 대상으로 하지 않습니다.
2026년 7월 15일 시점의 공식 문서에서는 Assistant 2.14.0-pre.1을 안내하고 있으며, Unity 6 (6000.0) 이후를 전제로 합니다. Unity AI는 Open Beta 상태이며, Unity Cloud에 접속된 프로젝트와 유효한 Trial 또는 Subscription이 필요합니다. Unity 공식 블로그에서는 MCP Server 자체는 Unity AI Credits를 소비하지 않는다고 설명되어 있습니다. Beta/pre-release이므로 평가 시에는 버전을 고정합니다.
공식 문서가 나타내는 구성은 다음과 같습니다.
Codex (MCP 클라이언트)
│ MCP 통신 (stdio)
Unity Relay (~/.unity/relay/)
...
Codex가 Relay를 기동하고, Relay가 Editor 내의 Bridge로 접속합니다. 이는 Unity MCP의 개요에 기반한 사양입니다.
Assistant 2.14.0-pre.1에서 AI > Assistant MCP Extensions는 Unity Assistant가 외부 MCP 서버를 이용하는 설정이며, AI > Unity MCP Server는 Unity의 기능을 외부 클라이언트에 공개하는 설정입니다. 방향이 반대이므로 혼동하지 않도록 주의해야 합니다.
화면 명칭은 패키지 버전에 따라 달라집니다. 예를 들어 Unity Assistant 2.7.0-pre.3의 공식 문서에서는 동일한 입구가 AI > MCP Client와 AI > Unity MCP였습니다. 블로그 스크린샷이나 다른 버전을 참조할 때는 문구의 완전 일치가 아니라 "Assistant가 외부 Tool을 사용하는 쪽"인지 "Unity를 외부로 공개하는 쪽"인지로 판별합니다.
또한, Unity_ManageScene이나 Unity_ReadConsole은 클라이언트에 공개되는 Tool 이름입니다. 공식 트러블슈팅의 get_components는 조작 이름으로 취급하며, 어떤 Tool의 입력에 대응하는지는 Codex가 발견한 스키마를 통해 확인합니다.
평가 환경을 고정하기
MCP 연동은 Unity, Assistant 패키지, Codex, OS, 대상 프로젝트의 조합에 따라 결과가 달라집니다. 성공률만 적어 놓아도 환경을 모르면 비교할 수 없습니다. 최소한 다음 정보를 평가 결과와 함께 남깁니다.
| 항목 | 기록 예시 |
|---|---|
| OS | Windows 11 24H2 |
| ... |
프로젝트는 실제 운영 프로젝트의 복사본이 아니라, 평가 전용의 작은 리포지토리(Repository) 또는 일회용 워크트리(Worktree)를 준비합니다. 각 시도는 동일한 기준 커밋(Commit), 동일한 씬(Scene), 비어 있는 콘솔(Console)에서 시작하며, 시도 번호, 프롬프트(Prompt), 툴 콜(Tool Call), 디버그 로그(Debug Logs), Git 차분(Diff)을 서로 연결합니다. Library를 재사용하는 일반적인 측정과 캐시까지 초기화하는 측정을 혼용하지 않습니다.
Unity 측 설정
전제 조건은 Unity 6 이후 버전과 com.unity.ai.assistant의 도입입니다. Unity Editor를 실행한 후 다음 사항을 확인합니다.
Edit > Project Settings > AI > Unity MCP Server를 엽니다.Unity Bridge가Running상태인지 확인합니다.Show Debug Logs를 활성화합니다.Validation Level을 확인합니다. - 사용할 도구만 활성화합니다.
Assistant 2.14.0-pre.1의 공식 설정 절차에 따르면, Bridge는 Editor 로딩 시 자동으로 시작되며, Relay 실행 파일은 사용자 디렉토리 하위의 .unity/relay에 배치된다고 설명되어 있습니다. 이는 공식 문서에 기반한 기술입니다. 도입 시에는 자신의 환경에서 Running 표시와 Relay의 존재를 확인하고, 필요에 따라 화면을 기록합니다. 만약 Stopped 상태라면, Console의 컴파일 에러, 패키지 도입 상태, Relay의 유무를 확인합니다.
Validation Level은 Assistant 2.14.0-pre.1 시점에서 Unity_ManageScript의 검증 강도를 basic, standard, comprehensive, strict 중에서 선택하는 설정입니다. 코드 수정 평가 시에는 속도 차이를 기록하면서 우선 strict부터 시작합니다. 단, 이것은 Scene 및 Prefab을 포함한 MCP 전체 조작의 검증 레벨은 아닙니다. 대상 버전의 설정 레퍼런스와 실제 화면을 대조하여 확인하십시오.
Codex에 Unity MCP 등록하기
Codex의 MCP 공식 문서에 따르면, stdio 형식의 MCP 서버를 ~/.codex/config.toml 또는 신뢰할 수 있는 프로젝트의 .codex/config.toml에 등록할 수 있습니다. 우선 연결 확인만 수행하기 위해 Unity_ReadConsole만을 허용 목록(Allowlist)에 넣습니다.
다음은 OS에 의존하지 않는 플레이스홀더(Placeholder)입니다. command와 --project-path는 자신의 환경에 맞는 절대 경로로 교체해야 합니다.
[mcp_servers.unity]
command = "/absolute/path/to/unity-relay"
args = [
...
Windows에서는 TOML의 리터럴 문자열을 사용하면 백슬래시()를 이중으로 사용할 필요가 없습니다. 위의 command와 args만 다음과 같이 교체합니다.
command = 'C:\Users\name\.unity\relay\relay_win.exe'
args = ["--mcp", "--project-path", 'C:\work\UnityMcpLab']
Assistant 2.14.0-pre.1의 공식 문서에 있는 Relay 실행 파일 예시는 다음과 같습니다. 모두 필자의 관측값이 아니므로, Unity MCP 설정 화면의 Locate Server와 실제 파일로 대조하십시오.
| OS | 공식 문서의 예 |
|---|---|
| macOS Apple Silicon | ~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64 |
| ... |
~가 확장되지 않는 클라이언트도 있으므로, command에는 절대 경로를 사용합니다.
CLI를 사용한다면 다음과 같은 형태로 서버를 등록할 수 있습니다.
codex mcp add unity -- \
/absolute/path/to/unity-relay \
--mcp \
...
등록 후에는 codex mcp list와 대화형 화면의 /mcp
에서 연결 상태와 실제로 공개된 Tool을 확인합니다. 연결 확인용과 쓰기 평가용의 차이는 다음과 같습니다.
| 상태 | Codex에 공개하는 범위 | 목적 |
|---|---|---|
| 연결 확인 | Unity_ReadConsole만 | 대상 Editor, 승인, Relay, Console 읽기 확인 |
| Script 수정 | Console 읽기 + 실제 환경의 Script 편집 Tool | 최소 차분의 코드 수정 |
| Scene 편집 | 실제 환경의 Scene/GameObject 관리 Tool | Sandbox Scene만 편집 |
| Prefab 생성 | 실제 환경의 GameObject/Component 관리 + Asset/Prefab 저장 Tool | 지정 폴더로 Prefab 저장 |
표 중의 Script 편집 Tool, Scene/GameObject 관리 Tool, Asset/Prefab 저장 Tool은 개념명입니다. 고정된 공식 Tool 이름을 나타내는 것이 아닙니다. Unity의 Tools 항목과 Codex가 /mcp로 발견한 스키마를 확인하고, 해당 환경에서 표시된 정확한 Tool 이름만을 enabled_tools에 추가합니다.
Prefab 저장 Tool의 이름을 기사로부터 추측해서는 안 됩니다. Built-in Tool만으로 요구 사항을 충족할 수 없는 경우에는 Custom Tool로 전환하며, Built-in만 사용한 결과와 별도로 집계합니다.
여러 개의 Unity Editor를 연다면 대상 지정은 필수
Assistant 2.14.0-pre.1의 공식 절차에서는, Relay는 대상 지정이 없는 경우 가장 먼저 발견된 Unity Editor에 연결합니다. 여러 프로젝트, 샘플, 평가용 프로젝트를 동시에 열어두는 사용자에게는 위험한 초기 동작입니다.
대상은 다음 중 하나로 고정할 수 있습니다.
--project-path <path>또는UNITY_PROJECT_PATH--instance-id <pid>또는UNITY_INSTANCE_ID
기본적으로는 --project-path를 권장합니다. PID는 Editor 재시작 시 변경되므로, 일시적인 구분에는 편리할 수 있으나 상설 설정에는 적합하지 않습니다.
AI에게 "테스트용 Scene을 편집해줘"라고 부탁했다고 생각했는데, 다른 프로젝트의 Editor에 연결되어 있다면 큰 문제가 될 수 있습니다. Connected Clients는 대상 버전의 공식 설정 화면에 기재된 UI 이름입니다. 실제로 평가할 때는 Codex 측의 연결 표시와 Unity 측의 실제 화면을 기록하여, 대상 프로젝트가 일치한다는 것을 증거로 남깁니다.
첫 연결은 Unity 측에서 승인할 것
외부 MCP 클라이언트로부터의 직접 연결은 공식 절차상, 최초에 Unity 측의 승인이 필요합니다. Assistant 2.14.0-pre.1의 패키지 문서에서는 Pending Connections에 표시된 클라이언트를 확인하고, Allow로 승인하거나 Revoke Access로 거부한다고 설명되어 있습니다. 승인된 클라이언트는 이후 세션에서 자동으로 재연결됩니다.
한편, 2026년 5월 11일에 공개된 Unity 공식 블로그에서는 동일한 승인 조작을 Accept라고 표기하고 있습니다. 또한 다른 버전에서는 설정 페이지 자체의 이름도 다릅니다. Allow라는 문자열만 찾지 말고, 대상 버전의 Pending Connections에 있는 승인 조작을 확인하십시오. 거부 측을 포함한 표시 문구도 도입 시의 실제 화면을 기록합니다.
이 승인은 중요하지만, 만능 권한 관리는 아닙니다. "이 Codex 클라이언트로부터의 연결을 허용했다"라는 경계일 뿐이며, "Prefab 생성은 허용하지만 Scene 삭제는 금지한다"와 같은 조작 단위의 제한은 별도의 레이어에서 설계해야 합니다.
평가에서는 성공을 4단계로 나눈다
AI의 "완료했습니다"가 아니라, Unity의 실제 상태로 판정합니다.
| 판정 | 조건 |
|---|---|
| 최초 성공 | 첫 번째 지시만으로 모든 조건을 충족하며, 추가적인 저장·확인 지시도 불필요 |
| ... |
수동 개입 성공을 자동화 성공에 섞지 말고, 최종적으로 사람이 고칠 수 있더라도 실패 시도는 남깁니다.
기록하는 지표
각 태스크를 동일한 초기 상태에서 10회씩 실행하며, 복구는 최대 2회까지로 제한합니다. 대상 외 변경, 연결 대상 불일치, Editor 정지가 발생한 시도는 중단합니다.
기록하는 항목은 최초 성공, 자동 복구, 수동 개입, 소요 시간, Tool Call 수, Timeout, 대상 외 차분, Editor 정지, Git 차분 파일 수, Tool 구성 (Built-in/Custom), 실제 Tool 명칭 및 주요 인자입니다.
최초 성공률 = 최초 성공 수 / 전체 시도 수
복구 포함 성공률 = (최초 성공 수 + 자동 복구 성공 수) / 전체 시도 수
수동 개입률 = 수동 개입 시도 수 / 전체 시도 수
...
10회는 일반적인 성능을 추정하기 위한 모수가 아닙니다. 자신들의 환경에서 중대한 실패를 찾아내고, 버전별 비교 조건을 통일하기 위한 최소 단위입니다. Built-in/Custom, Allowlist, 캐시 조건이 다른 시도는 동일한 모수에 섞지 않습니다.
평가 태스크 1: Unity Console을 읽게 하여 컴파일 에러를 수정하기
우선 읽기만으로 연결을 확인한다
수정 시도로 들어가기 전에, enabled_tools = ["Unity_ReadConsole"] 상태로 Console의 Error/Warning 건수와 상위 몇 건을 요약하게 합니다. 이 연결 확인은 후술할 10회의 수정 시도에 포함하지 않습니다. 이 단계에서는 파일 수정을 허용하지 않습니다. 대상 Editor가 일치하고, Unity 측에서 승인되었으며, Codex가 Unity_ReadConsole만을 발견하고 있음을 확인하면, 실제 환경의 Script 편집 Tool을 Allowlist에 추가하여 수정 평가로 진행합니다.
Console 수정의 과제
Assets/MCPTest/Scripts/Health.cs에 세미콜론 누락을 한 곳만 넣습니다.
using UnityEngine;
public sealed class Health : MonoBehaviour
{
...
C#의 난이도가 아니라, Console에서 대상을 특정하고, 최소 차분을 적용하며, Unity의 재컴파일 후에 Error가 0건이 되었는지 재확인할 수 있는지를 봅니다. 무관한 Warning을 고치기 시작하지 않는 것도 조건입니다.
Console 수정 지시문
Unity Console의 컴파일 에러를 확인하고, 원인을 해소하는 최소 차분만을 적용하십시오.
제약 사항:
- API 설계, 명명, 필드, 접근 수정자는 변경하지 말 것
...
Bridge 정지 시의 분기
공식 트러블슈팅에서는 컴파일 에러가 원인이 되어 MCP Bridge를 시작할 수 없는 경우가 있다고 설명되어 있습니다. 따라서 경로를 두 가지로 나눕니다.
| 상태 | 절차 |
|---|---|
| Bridge 가동 | Unity_ReadConsole → 최소 수정 → 컴파일 대기 → Console 재취득 |
| Bridge 정지 | Codex의 통상 파일 편집으로 저해 에러만 수정 → Unity 재컴파일 → Bridge 기동 → Console 재취득 |
코드 편집은 통상적인 리포지토리 조작, 실행 결과 관측은 Unity MCP와 분담해도 무방합니다. 성공 조건은 Error 0건, 세미콜론 추가 이외의 차분 없음, 재컴파일 후의 재확인, Bridge 상태에 따른 경로 선택입니다.
평가 시에는 난이도를 2단계로 나눈다
세미콜론 누락은 연결 루프를 확인하는 Stage A입니다. Stage B에서는 예를 들어 Rigidbody 필드에 GetComponent<Rigidbody2D>()를 대입한 타입 에러를 준비하고, 기대 차분을 GetComponent<Rigidbody>()로만 고정합니다. 모호한 결함이 아니라, 정답과 수용 조건을 미리 결정하여 별도로 집계합니다.
파일 저장만으로 완료 처리해서는 안 됩니다. Asset Import, 컴파일, Domain Reload 이후까지 관측합니다. 타임아웃 시의 재전송 조건과 즉시 정지 조건은 후술하는 공통 상태 머신을 따릅니다.
평가 태스크 2: Codex가 Scene을 편집하게 하기
Scene 편집의 과제
Assets/MCPTest/Scenes/MCP_Sandbox.unity를 신규 생성하고, 다음 Hierarchy로 편집합니다.
MCP_Sandbox (Scene)
├─ Environment
│ ├─ Floor
...
완료 조건은 다음과 같습니다.
- Scene의 저장 위치가 지정된 경로와 일치한다
- Scene 직하에
Environment,Main Camera,SpawnPoint가 있다 Environment
의 Transform은 Position/Rotation이 0, Scale이 1 -
Floor는Environment의 자식이며, Cube의 표시 Component와BoxCollider를 가짐 -Floor.localPosition = (0, -0.5, 0),localScale = (10, 1, 10)-Directional Light는 Directional 타입의Light를 가짐 -SpawnPoint는 Transform만 가지며,position = (0, 1, -4)-Main Camera는Camera를 가지며, Tag가MainCamera임 -- Scene이 저장되어 있으며, 다른 Scene으로 변경되지 않음
- Console에 Error가 없음
Scene 편집 지시문
Unity MCP로 Assets/MCPTest/Scenes/MCP_Sandbox.unity를 새로 생성하고, 다음 상태로 만드세요.
Hierarchy:
- Environment
...
Scene 편집에서 확인해야 할 포인트
Scene 편집은 외관이 맞더라도 Dirty 상태라면 Editor 종료 시 사라집니다. 저장 후 경로(Path)와 Hierarchy를 재취득하며, 다중 Scene 구성에서는 Active Scene과 각 GameObject의 소속 Scene도 확인합니다.
Transform은 World 값과 Local 값을 구분합니다. 부모-자식 관계 설정 전후로 결과가 달라지기 때문에, 지시와 판정 양측 모두에 position인지 localPosition인지를 명시합니다.
UI 계층은 평가 대상에서 제외
Assistant 2.14.0-pre.1의 공식 트러블슈팅(Troubleshooting)에는 Canvas나 UI 계층의 GameObject에 get_components 조작을 수행하면 Editor가 정지하거나 크래시(Crash)가 발생할 가능성이 있다고 기재되어 있습니다. 대상은 Canvas, CanvasScaler, GraphicRaycaster, RectTransform입니다. get_components는 문서상의 조작 명칭이며, 실제 Tool과의 대응은 발견된 스키마(Schema)를 통해 확인합니다.
대상 버전의 평가에서는 UI 계층에 대한 Component 취득, Scene 전체의 광역 열거(Enumeration)를 금지하고, 대상 Root를 한정합니다. Tool Call의 인자(Argument)를 저장하고, Editor가 멈춘 경우 마지막 호출을 특정하여 중지합니다. UI를 다루는 것은 Issue Tracker와 릴리스 노트(Release Notes)를 통해 수정되었음을 확인한 후부터입니다.
평가 태스크 3: Codex에게 Prefab을 만들게 하기
실행 전 Allowlist를 전환하기
연결 확인용인 enabled_tools = ["Unity_ReadConsole"] 상태에서는 실행할 수 없습니다. GameObject 조작, Component 설정, Asset/Prefab 저장에 필요한 Tool을 실제 환경에서 확인하여 추가합니다. 저장용 Built-in Tool이 없다면 "Built-in만으로는 실행 불가능"이라고 기록하고, Custom Tool 시도로 분리합니다.
과제 및 완료 조건
Assets/MCPTest/Prefabs/Crate.prefab
Crate
├─ Visual
...
- Root 이름은
Crate- - Root는 Transform을 제외하고
BoxCollider와Rigidbody만 가지며,Rigidbody.mass = 10- Visual은 Transform,MeshFilter,MeshRenderer만 가짐 -Visual에CreatePrimitive유래의BoxCollider등이 남아있지 않음 -Handle은 Transform만 가지며,localPosition = (0, 0.6, 0)-- 지정된 경로로 저장되며, Scene에 작업용 GameObject가 남지 않음 -
- 저장 후 Prefab을 다시 열어도 구조와 값이 유지됨 -
- Console에 Error가 없음
Prefab 생성 지시문
Unity MCP를 사용하여 Assets/MCPTest/Prefabs/Crate.prefab을 생성하세요.
요구사항:
- Root 이름: Crate
...
평가 범위는 생성, 값 설정, 저장, 사후 정리, 재로드까지입니다. 임시 GameObject 생성, 값 미설정, 좌표계 혼동, 덮어쓰기, 불필요한 Collider 추가, 저장 후 미확인을 실패로 간주합니다.
실패 시에는 Asset과 잔류물을 재관측하여 차분을 한 항목씩 수정합니다. 반복적으로 사용한다면, dryRun, 저장 위치 Allowlist(허용 목록), 덮어쓰기 방침을 가진 CreateOrValidatePrefab과 같은 Custom Tool(커스텀 툴)로 기능을 모읍니다.
평가 기록 템플릿
다음 표를 복사하여 Console, Scene, Prefab에서 각각 10행씩 채웁니다. ○×뿐만 아니라, Tool 구성과 중단 지점을 남깁니다.
| 시도 | Tool 구성 | 사용 Tool | 최초 | 복구 | 수동 | 시간 | Call | Timeout | 대상 외 차분 | 비고 |
|---|---|---|---|---|---|---|---|---|---|
| 1 | ||||||||||
| ... |
집계표는 다음과 같은 형태입니다.
| 태스크 | Tool 구성 | 최초 성공률 | 복구 포함 성공률 | 수동 개입률 | 부작용률 | 중앙값 시간 | Editor 중단 |
|---|---|---|---|---|---|---|---|
| Console 수정 | Built-in/통상 편집 | — | — | — | — | — | — |
| ... | |||||||
| 평균값뿐만 아니라 중앙값, 최대 시간, 타임아웃, Editor 중단을 나누어 확인합니다. Built-in만 사용하는 경우와 Custom Tool을 병용하는 경우는 별도의 표로 집계합니다. |
화면과 로그를 증거로 남기기
팀 내에서 도입 여부를 판단할 때나 결과를 외부에 공개할 때도 Unity MCP Server 설정 화면, Codex의 Tool 목록, Prefab의 Hierarchy/Inspector, Console 수정 전후, Scene 편집 후의 Hierarchy, 실패 시의 Debug Logs 또는 Tool Call을 남깁니다. 성공 사례뿐만 아니라, 복구에 성공한 실패와 중단된 실패도 대상입니다. 외부 공개 시에는 사용자 이름, 절대 경로, 프로젝트명, 인증 정보를 마스킹하고, 각 이미지를 시도 번호와 매칭합니다.
도입 판정의 잠정 기준
다음은 Unity나 OpenAI가 제시한 공식 기준이 아니라, 팀 내 파일럿 테스트를 위해 설정한 제안값입니다.
- 최초 성공률 80% 이상
- 자동 복구 포함 성공률 95% 이상
- 의도하지 않은 변경 0건
- Editor 중단·크래시 0건
- 수동 개입은 10회 시도당 1회 이하
- 인간이 동일한 작업을 수행했을 때의 중앙값보다 빠름
Prefab이나 Scene은 속도보다 부작용을 더 중요하게 봅니다. 9번 빠르게 성공하더라도, 단 1번 다른 Scene을 망가뜨린다면 도입 불가입니다. Console 수정은 최소한의 차분과 재컴파일(Recompile) 확인을 중요하게 봅니다.
실패로부터의 복구를 상태 머신(State Machine)으로 정의하기
자유 형식으로 "어떻게든 해봐"라고 재요청하면 시도할 때마다 복구 절차가 달라집니다. 따라서 쓰기 작업을 동반하는 평가는 다음 상태 전이로 고정합니다.
Observe → Plan → Act one step → Wait → Verify
↑ │
└─기존의 일시적 실패────────────────────┘
...
| 상태 | 수행 내용 |
|---|---|
| Observe | Active Scene, 대상 Asset, Hierarchy, Console, Bridge, Git 차분을 가져온다 |
| ... | |
| 타임아웃 시에도 동일한 조작을 즉시 재전송하지 않고 Observe로 돌아갑니다. 계속 진행할 수 있는지 여부를 AI의 자기 판단에만 맡기지 않는 것이 중요합니다. |
공통적인 즉시 중단 조건은 다음 체크리스트로 집약합니다.
- 접속 중인 프로젝트 또는 대상 Scene이 예상과 다름
- 기존 Asset을 덮어쓸 가능성이 있음
- 지정되지 않은 Scene, Asset, Script에서 차분이 발생함
- Unity Editor가 중단·크래시되어 마지막 Tool Call을 특정할 수 없음
- 타임아웃 후의 실제 상태를 재취득할 수 없어 처리 완료 여부를 판단할 수 없음
- 허용되지 않은 Tool 또는 Custom Tool이 호출됨
각 평가 태스크에서는 이 목록을 길게 반복하지 않고, 태스크 고유의 수락 조건(Acceptance Criteria)만 추가합니다.
권한 관리는 4개 계층으로 생각하기
Unity 측의 최초 승인만으로는 조작 범위를 완전히 제한할 수 없으므로, 다음 4개 계층을 중첩합니다.
제1계층: Git과 작업 환경
전용 브랜치(Branch)/worktree, 깨끗한(clean) 기준 커밋, 1태스크 1커밋을 사용합니다. 처음에는 운영(Production) Scene이 아닌 Sandbox Scene을 대상으로 하며, YAML 차분(diff)뿐만 아니라 Unity 상에서도 확인합니다.
제2계층: Codex의 Sandbox와 Approval
Sandbox는 로컬 명령(Local Command)의 범위를, Approval Policy는 사람에게 확인을 요청하는 조건을 제어합니다. Unity MCP의 Tool Call은 셸(Shell) 편집과는 별개의 경로이므로, Sandbox에만 의존하지 않습니다. 시작 시점부터 sandbox_mode = "danger-full-access"나 승인 무효를 선택하지 않고, 우선 workspace-write에 상당하는 권한과 대화형 승인(Interactive Approval)으로 시도합니다.
제3계층: Codex의 MCP 도구 제한
enabled_tools, disabled_tools, Approval Mode를 통해 공개된 도구(Tool)를 태스크 단위로 좁힙니다. 연결 확인은 Unity_ReadConsole만 수행합니다. 쓰기 작업 시에도 실제 환경에서 확인된 필요한 도구만을 허용 목록(Allowlist)에 추가합니다.
제4계층: Unity MCP Server와 Custom Tool
Unity 측에서도 불필요한 도구를 무효화하여 이중으로 제한합니다. 반복적인 업무는 허가된 폴더, 대상 Scene, 덮어쓰기 가능 여부, 생성 수, Dry Run, Undo, Validation이 포함된 CreateEnemySpawnPoint나 ValidatePrefabReferences와 같이 범위가 좁은 커스텀 도구(Custom Tool)로 집중시킵니다.
"로컬 연결이니까 데이터도 완전히 로컬이다"라고 단정할 수 없다
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기