핵심 표면

공식 Unity MCP 흐름
1. Unity Editor가 MCP Bridge를 자동 시작
2. ~/.unity/relay/ 의 relay binary를 MCP 클라이언트가 --mcp 로 실행
3. Edit > Project Settings > AI > Unity MCP 에서 브리지, 연결, 도구 상태 확인
4. 외부 MCP 클라이언트의 첫 연결은 Pending Connection 에서 승인
5. 필요하면 McpToolRegistry 기반 custom tool 추가

핵심 포인트
- Unity가 외부 AI 클라이언트에 노출하는 공식 MCP 서버다
- direct connection 은 승인 필요, Unity Assistant의 AI Gateway 연결은 자동 승인
- built-in tool 과 custom tool 이 같은 브리지에 함께 등록된다

연결 구조

공식 Unity MCP는 "Unity가 MCP 서버를 제공하는 쪽"이다

Unity 공식 문서 기준으로 Unity MCP는 Unity Editor 안에 브리지를 두고, 외부 AI 클라이언트가 그 브리지에 MCP로 연결하는 구조입니다. 즉 "Unity가 다른 MCP 서버에 접속하는 기능"이 아니라, 반대로 Unity가 자신을 MCP 도구 집합으로 노출하는 쪽입니다. 씬 관리, 에셋 작업, 스크립트 편집, 콘솔 접근 같은 built-in tool이 여기에 매달리고, 필요하면 custom tool도 같은 표면에 붙일 수 있습니다.

특히 이 문서를 코덱스 관점에서 볼 때 중요한 점은 Unity가 에디터 내부 상태를 구조화된 tool call로 노출한다는 점입니다. 단순 셸 명령 몇 개보다 "어떤 도구를 호출했는지"가 더 분명하게 남기 때문에, 긴 작업 흐름이나 단계적 자동화에 더 잘 맞습니다.

relay binary 와 승인 절차가 실제 연결의 핵심이다

Unity가 시작될 때 bridge를 자동으로 올리고, ~/.unity/relay/ 아래 relay binary를 설치합니다. MCP 클라이언트는 이 relay executable을 --mcp 플래그와 함께 실행해 Unity에 붙습니다. 문서 예시는 Claude Code와 Cursor 기준이지만, 구조 자체는 relay binary를 실행하는 MCP 호환 클라이언트 공통 개념으로 이해하면 됩니다.

{
  "mcpServers": {
    "unity-mcp": {
      "command": "~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": ["--mcp"]
    }
  }
}

첫 연결에서는 Unity 쪽 승인 절차도 필요합니다. 외부 클라이언트가 직접 연결하면 Pending Connections에 나타나고, 사용자가 Accept 해야 실제 도구 호출이 열립니다. 반대로 Unity Assistant의 AI Gateway 연결은 자동 승인됩니다. 그래서 "클라이언트 설정은 맞는데 도구가 안 보인다"면 relay 경로만 볼 것이 아니라 승인 대기 상태도 같이 확인해야 합니다.

Project Settings 에서 확인해야 할 화면이 명확하다

공식 overview 문서는 Edit > Project Settings > AI > Unity MCP 화면에서 bridge 상태, connected/pending client, tool list, integration 설정을 본다고 정리합니다. 여기서 도구 enable/disable 토글도 관리할 수 있으므로, 처음에는 읽기 위주 도구만 켜고 쓰기 도구는 점진적으로 여는 운영 방식도 가능합니다.

같은 AI 메뉴 안에 MCP Client 페이지도 있지만 역할이 다릅니다. Unity MCP 페이지는 Unity가 외부에 노출하는 공식 MCP 서버를 설정하는 곳이고, AI > MCP Client는 Unity Assistant가 다른 MCP 서버에 접속할 때 쓰는 화면입니다. 이 둘을 헷갈리면 "왜 Unity가 안 보이지?" 같은 설정 혼선이 바로 생깁니다.

custom tool 은 McpToolRegistry 가 에디터 시작 시 자동 등록한다

McpToolRegistry는 TypeCache로 어셈블리를 스캔해 도구를 자동 등록합니다. 단순 static method, JObject 기반 유연한 schema, class-based tool, runtime API까지 네 가지 등록 방식이 있어서, 프로젝트 성격에 맞춰 확장할 수 있습니다.

using Unity.AI.MCP.Editor.ToolRegistry;

[McpTool("my_tool", "Description of what this tool does")]
public static object MyTool(MyParameters parameters)
{
    return new { success = true, message = $"Processed {parameters.Action}" };
}

public class MyParameters
{
    [McpDescription("Action to perform", Required = true)]
    public string Action { get; set; }
}

이 방식의 장점은 Unity가 입력 schema 생성과 타입 변환을 같이 도와준다는 점입니다. 반대로 custom tool 스크립트에 컴파일 에러가 있으면 등록 자체가 빠질 수 있으므로, 도구가 일부만 보일 때는 연결 문제로만 보지 말고 Unity Console 오류도 함께 봐야 합니다.

언제 공식 MCP를 쓸까

주의할 점

실패 예시
- Unity 쪽 bridge 는 Running 이고 클라이언트 설정도 넣었는데 도구 목록이 비어 있음
- 결과: Pending Connection 미승인, custom tool 컴파일 오류, tool toggle 비활성 중 하나일 가능성이 큼
- 대응: Unity MCP 설정 화면에서 Connected/Pending 상태를 확인하고, Unity Console 오류와 tool list 를 함께 점검한다