Unity AI 입문 4: MCP 연결 실패·도구 누락·Console 오류를 나눠 고치는 법
실제 서버 응답에서 확인한 success:false를 출발점으로, 막힌 단계와 재확인 조건을 찾는 진단 가이드예요.
마지막 업데이트
메뉴나 지원 기능이 달라졌다면 아래 자료 확인일과 현재 앱 버전을 함께 봐주세요.

대표 화면은 공식 저장소에 포함된 v8.6 예시예요. 현재 10.3.0의 직접 촬영 화면이 아니에요. MIT · Media credits
AI가 “완료했어요”라고 하는데 Unity에는 바뀐 것이 없나요? 먼저 어느 단계까지 실제로 성공했는지 확인해봐요. 패키지 설치, 서버 시작, MCP 도구 목록, Unity 장면 조회, 변경과 저장은 서로 다른 단계예요. 이 글의 목표는 오류를 무작정 없애는 것이 아니라, 실패 지점과 다음에 다시 확인할 한 가지를 찾는 거예요.
기준은 MCP for Unity 10.3.0의 공식 문서·도구 정의와 범블비의 제한된 Linux 서버 실행이에요. Unity 에디터 내부 오류를 직접 재현하거나 수정한 기록은 아니에요. 먼저 연결 과정 또는 첫 장면 과정 중 마지막으로 성공한 단계에 표시해두세요.
1. 초록 표시 대신 실제 응답을 읽어요
이번 서버 시험에서는 MCP 초기화와 tools/list가 성공해 도구 48개를 받았어요. 그다음 읽기 전용 manage_scene의 get_active는 아래처럼 실패했어요. Unity 에디터를 실행하지 않은 환경이라 에디터 인스턴스를 찾을 수 없었던 거예요.
{
"success": false,
"message": "...No Unity Editor instances found. Please ensure Unity is running with MCP for Unity bridge..."
}
이것은 핵심 내용을 줄여 적은 응답 예시이며 전체 반환 구조와 같지는 않아요. 특히 이 시험의 바깥 MCP 응답에는 isError:false도 있었어요. 그래서 전송 수준에서 응답을 받았다는 것과 내부 작업의 성공을 따로 읽어야 해요. 객체를 만들었다고 보고하기 전에 도구 내용의 success와 실제 장면을 함께 확인하는 이유예요.
2. 설치 단계에서 막혔는지 확인해요
어느 화면에서 멈췄나요? Package Manager에서 설치 오류가 보이는지, MCP 창에서 서버와 세션이 각각 준비됐는지, Cursor에 도구가 표시되는지, 실제 장면 조회 응답이 돌아오는지 순서대로 확인해요. 마지막으로 성공한 화면을 기록하고 그 다음 단계만 다시 시도하세요.
Package Manager가 Error when executing git command를 보이면 먼저 새 터미널에서 git --version이 되는지 확인해요. Git 설치 후 Unity를 다시 열어 에디터가 바뀐 PATH를 읽게 하는 것이 공식 진단의 첫 갈래예요. 패키지 URL의 저장소·하위 경로·버전 태그도 연결 가이드와 대조해요.
소유권이나 DLL 충돌처럼 다른 원인이 적힌 오류라면 원문과 파일 경로를 보존해요. 다른 계정의 폴더를 무조건 신뢰하도록 설정하거나, 모든 DLL·Library·잠금 파일을 한꺼번에 지우는 방식으로 시작하지 않아요. 원본 작업을 보관한 연습 복사본에서 원인에 맞는 공식 해결 문서를 확인해요. 설치 오류가 남은 상태에서는 AI 대화문을 바꿔도 패키지 컴파일이 해결되지 않아요.
3. 서버와 Unity 연결을 나눠봐요
uv --version이 응답하지 않으면 서버 실행 도구가 준비되지 않은 상태예요. 터미널에서는 되는데 Unity에서 못 찾으면 실행 파일 위치와 에디터 재시작 여부를 확인해요. MCP 창의 의존성 표시와 서버 로그를 함께 남겨요. 주소가 이미 사용 중이라는 메시지가 있다면 임의로 다른 프로세스를 종료하지 말고 다른 로컬 포트를 선택한 뒤 양쪽 설정을 맞춰요.
서버를 켠 다음에는 Unity의 MCP 창에서 세션 연결을 확인해요. 클라이언트 주소에는 /mcp가 필요한데 서버의 기본 주소만 넣지는 않았는지 봐요. 이 가이드는 같은 컴퓨터의 HTTP Local 연결이에요. Windows 에디터와 WSL 클라이언트, 원격 서버는 네트워크 경계가 달라 별도 진단이 필요하므로 이 기본 설정과 섞지 않아요.
4. 도구가 안 보일 때는 새 요청 전에 목록을 확인해요
클라이언트에서 unityMCP가 활성화됐는지, 현재 대화가 새 설정을 읽었는지 확인해요. 서버 설정을 바꾼 뒤 새 대화를 시작하면 이전 세션과 구분해볼 수 있어요. 연결은 있는데 특정 기능이 없다면 manage_tools의 그룹 목록을 살펴봐요. 테스트 같은 기능은 도구 그룹 설정에 영향을 받을 수 있어요.
여러 Unity 프로젝트가 열려 있으면 현재 대상이 어느 것인지 먼저 선택해야 해요. set_active_instance에는 실제 목록에서 확인한 식별자를 써요. 예시의 임의 이름을 실제 프로젝트 ID처럼 사용하지 않아요. 대상 선택 후 get_active를 다시 요청해 기대한 장면 경로가 돌아오는지 확인해요. 공식 다중 인스턴스 안내
5. Console은 지우기 전에 읽어요
연결이 정상인데 스크립트나 프로젝트 오류가 있다면 read_console의 get을 사용해 최근 오류를 읽어요. 아래 인수는 오류 다섯 개와 스택 정보를 요청하는 예시예요. 에러를 읽는다고 수정까지 완료된 것은 아니에요.
오류 조회 인수와 진단 요청 예시
{"action":"get","types":["error"],"count":"5","include_stacktrace":true}
Console을 지우지 말고 최근 오류 5개를 읽어줘.
첫 오류의 파일과 줄, 관련된 변경을 설명하고 수정 전 계획부터 보여줘.
수정했다면 같은 작업을 다시 확인하고 남은 오류와 저장 여부를 구분해서 알려줘.
오류가 생긴 직전의 파일과 대상, 에디터 버전을 함께 봐요. 첫 오류를 고치면 뒤에 따라온 오류가 줄 수도 있지만 언제나 그런 것은 아니에요. 한 번에 관계없는 여러 파일을 고치게 하기보다 원인 하나와 변경 하나를 기록하고 재확인하는 편이 비교하기 좋아요.
6. 다시 실행해도 되는 지점을 정해요
Console에서 볼 곳: Unity Console에서 첫 빨간 오류를 선택하면 상세 메시지와 관련 파일·줄 정보를 확인할 수 있어요. 모두 지우기 전에 내용을 보관하고, 수정 후 같은 오류가 다시 나오는지 확인해요. 이 설명은 공식 문서 기반이며 여기서 해당 오류를 재현했다는 뜻은 아니에요.
상자 생성 호출의 결과가 불명확하다면 같은 요청부터 반복하지 말고 Hierarchy에서 이름을 찾아요. 이미 있는 대상이면 생성 재시도는 중복이 될 수 있어요. 저장 응답이 불명확하다면 장면 경로와 현재 파일을 확인한 뒤 저장을 판단해요. 삭제·파일 교체처럼 되돌리기 어려운 변경은 계획과 백업을 확인하고 별도로 결정해요.
진단 메모는 “패키지 10.3.0 / HTTP Local / 도구 목록 있음 / 장면 조회 실패 / 에디터 연결 재확인 필요”처럼 마지막 성공과 첫 실패를 나누면 돼요. 이번 시험에서도 서버가 응답했다고 Unity 작업 완료로 보고하지 않았어요. 원인이 해결되면 첫 장면 가이드의 조회 단계부터 돌아가 같은 목표를 확인해요.
참고 자료
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/MCPForUnity/package.json
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/getting-started/install.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/getting-started/clients.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/getting-started/first-prompt.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/reference/tools/core/manage_scene.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/reference/tools/core/manage_gameobject.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/reference/tools/core/read_console.md
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/website/docs/guides/troubleshooting.md
- https://github.com/CoplayDev/unity-mcp/releases/tag/v10.3.0
- https://cursor.com/docs/mcp
- https://github.com/CoplayDev/unity-mcp/blob/aa5fc638d623f56178d50329d9ad8c541a57fe66/LICENSE