언리얼 MCP

언리얼 MCP는 언리얼 에디터 프로세스 내에 MCP 서버를 임베드하여 Claude Code, Cursor 또는 MCP Inspector와 같은 MCP 호환 AI 에이전트가 로컬 HTTP 연결을 통해 에디터를 제어할 수 있게 해줍니다. 이 플러그인은 액터 스폰, 라이팅 환경설정, 머티리얼 인스턴스 생성, 슬레이트 위젯 검사, 자동화 테스트 실행 등 엔진의 기능을 AI 에이전트가 사용자를 대신하여 호출할 수 있는 툴로 노출하며, 사용자의 커스텀 툴로도 손쉽게 확장할 수 있습니다.

모델 컨텍스트 프로토콜이란 무엇인가요?

모델 컨텍스트 프로토콜(Model Context Protocol, MCP)은 modelcontextprotocol.io에서 퍼블리싱한 오픈 사양입니다. 이는 AI 클라이언트가 initialize, tools/list, tools/call 등 소규모 JSON-RPC 메시지 타입 세트를 사용하여 MCP 서버와 커뮤니케이션하는 방법을 정의합니다. 서버는 다음과 같은 세 가지 종류의 프리미티브를 애드버타이징합니다. 

• 툴(Tool)은 클라이언트가 호출할 수 있는 이름이 지정된 기능으로, 타입이 지정된 파라미터와 반환 값을 포함합니다.

• 리소스(Resource)는 클라이언트가 통합 자원 식별자(Uniform Resource Identifier, URI)를 통해 가져올 수 있는 읽기 전용 데이터입니다.

• 프롬프트(Prompt)는 재사용 가능한 프롬프트 템플릿입니다.

언리얼 MCP는 MCP 서버입니다. 언리얼 엔진 기능을 기반으로 하는 툴을 애드버타이징하고 프로토콜을 사용하는 모든 클라이언트의 연결을 수락합니다.

플러그인은 에디터 프로세스 내에서 실행됩니다. 기본적으로 서버는 동일한 머신에서만 연결을 허용하며, 인증 레이어가 없고 원격 사용을 위해 디자인되지 않았습니다. 정확한 바인딩 비헤이비어는 제한 사항 및 알려진 문제에 문서화되어 있습니다.

MCP 서버의 핵심 기능은 게임 스레드에서 툴 호출을 순차적으로 실행하여 외부 요청을 언리얼 엔진 게임 스레드와 동기화하는 것입니다. 즉, 클라이언트는 오버랩되는 툴 호출을 실행해서는 안 됩니다.

구성

구성은 다음의 기본 단계를 따릅니다.

• 언리얼 MCP 및 모든 툴세트 플러그인을 활성화합니다.

• 자동 시작을 환경설정합니다.

• 클라이언트 환경설정 파일을 생성합니다.

• 프로젝트 루트에서 AI 에이전트를 시작합니다.

• [선택 사항] 통합 터미널 플러그인을 사용하여 AI 에이전트를 실행하고 전체 워크플로를 에디터 내에 유지합니다.

플러그인 활성화

편집(Edit) > 플러그인(Plugins)을 열고 Unreal MCP를 검색한 다음 활성화됨(Enabled) 체크박스를 확인합니다. 'All Toolsets' 플러그인을 검색하고 활성화됨 박스를 체크합니다. 이러한 플러그인은 자동으로 활성화되는 툴 레지스트리(Toolset Registry) 플러그인에 종속됩니다. 메시지가 표시되면 에디터를 다시 시작합니다.

자동 시작 환경설정

편집 > 에디터 개인설정(Editor Preferences)을 열고 일반(General) 그룹으로 스크롤하여 모델 컨텍스트 프로토콜(Model Context Protocol)을 선택합니다. 패널에 서버 자동 시작(Auto Start Server) 세팅이 표시됩니다. 활성화하면 에디터가 실행될 때마다 MCP 서버가 자동으로 시작되고 http://127.0.0.1:8000/mcp에 바인딩됩니다.

디폴트가 다른 로컬 서비스와 충돌하는 환경에서는 같은 패널에 수신 포트(디폴트 8000) 및 URL 경로(디폴트 /mcp)도 표시됩니다. serverInfo.name에 애드버타이징된 서버 이름은 항상 unreal-mcp입니다.

대신 필요에 따라 서버를 시작하려면 '자동 서버 시작'을 끄고 에디터 콘솔에 ModelContextProtocol.StartServer를 입력합니다. 이 명령은 ModelContextProtocol.StartServer 8000 같은 선택적 포트도 허용합니다.

클라이언트 환경설정 생성

각 AI 에이전트는 서버 리스트가 특정 파일 포맷으로 프로젝트 트리 내 특정 위치에 있다고 예상합니다. 플러그인이 해당 파일을 직접 씁니다. 에디터 콘솔(기본적으로 ` 키로 열 수 있음)에서 다음을 입력합니다.

ModelContextProtocol.GenerateClientConfig ClaudeCode

이 명령은 실행 중인 서버를 가리키는 올바른 엔트리와 함께 .mcp.json을 프로젝트 루트에 습니다. 지원되는 클라이언트 이름은 ClaudeCode, Cursor, VSCode, Gemini, Codex 및 All입니다. 여러 에이전트를 한 번에 환경설정하는 경우에는 'All'을 사용합니다.

ModelContextProtocol.GenerateClientConfig All

Claude Code용으로 생성된 .mcp.json은 다음과 같습니다.

{
  "mcpServers": {
    "unreal-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

JSON 포맷 환경설정(Claude Code, Cursor, VS Code, Gemini)은 기존 엔트리와 병합되므로 명령을 반복 실행해도 안전합니다. Codex CLI에서 사용하는 TOML 환경설정은 한 번만 쓸 수 있습니다. 해당 명령은 기존 파일의 덮어쓰기를 거부하며, 오래된 환경설정은 수동으로 제거해야 합니다.

선호하는 AI 에이전트에서 연결

연결하려면 환경설정 파일이 생성된 프로젝트 또는 워크스페이스 루트에서 선호하는 AI 에이전트 CLI 또는 애플리케이션을 실행합니다. 구체적인 연결 단계 및 고급 세팅에 대한 자세한 내용은 선택한 AI 클라이언트의 문서를 참고하세요.

연결에 문제가 있는 경우에는 다음 조치를 시도해 볼 수 있습니다. 

AI 에이전트 CLI 또는 애플리케이션이 언리얼 MCP를 찾지 못하는 경우, 환경설정 파일이 생성된 프로젝트 또는 워크스페이스 루트에서 실행되었는지 검증합니다. 

에디터가 실행된 후 원하는 AI 에이전트를 실행합니다. 그렇지 않으면 MCP를 다시 연결해야 할 수도 있습니다. 이렇게 하려면 다음 단계를 따릅니다. 

1. 언리얼 에디터를 실행하고 MCP가 시작되었는지 확인합니다.

2. 워크스페이스 루트에서 AI 에이전트(에디터에서 MCP를 수신하는 에이전트)를 실행합니다.

선택 사항: 터미널 플러그인을 사용한 일회성 실행

터미널(Terminal) 플러그인은 완전히 작동하는 터미널 패널을 에디터 내에 임베드하고, 패널이 열릴 때 셸 명령이 자동으로 실행되도록 지원합니다. 언리얼 MCP와 함께 사용하면 전체 워크플로를 단일 에디터 창 내에 유지할 수 있습니다.

터미널 플러그인을 구성하려면 다음 단계를 따릅니다. 

1. 편집 > 플러그인을 열고 Terminal을 검색합니다. 에디터를 재시작하여 변경사항을 적용합니다.

2. 에디터 개인설정 > 일반 > 터미널을 엽니다.

터미널 에디터 개인설정에서 다음 순서대로 '스타트업 명령(Startup Commands)' 목록에 엔트리를 추가합니다.

1. AI 에이전트 CLI가 적합한 터미널을 탐지하도록 터미널 타입을 설정합니다. 

   경고: 이 설정이 없으면 claude 및 이와 유사한 CLI는 제한된 모드로 예비 전환되며, 포맷이 적용된 출력 대신 원시 이스케이프 시퀀스를 출력할 수 있습니다.

   1. Windows(cmd.exe): set TERM=xterm-256color.

   2. Unix 셸(bash, zsh): export TERM=xterm-256color.

2. GenerateClientConfig가 .mcp.json을 쓴 디렉터리(설치된 빌드의 프로젝트 루트, 소스 빌드의 워크스페이스 루트)로 변경합니다.

   1. Windows: cd /d "<path>".

   2. Unix: cd "<path>".

3. 사용할 AI 에이전트 CLI를 설정합니다. 이 예시에서는 claude로 설정합니다.

명시적인 cd는 레시피를 이식 가능하게 만듭니다. '터미널' 패널은 FPaths::RootDir()에서 새 세션을 시작하며, 이는 소스 빌드의 워크스페이스 루트이자 설치된 빌드의 엔진 설치 디렉터리이므로 작업 디렉터리가 .mcp.json이 있는 위치와 항상 일치하지는 않습니다.

퀵스타트

서버가 실행 중이고 AI 에이전트가 연결되면 언리얼 엔진과 인터랙션을 시작할 수 있습니다.

시작하려면 다음과 같은 간단한 질문을 통해 AI 에이전트가 에디터에 연결되어 컨텍스트를 수신하고 있는지 확인해 보세요.

• "내가 어떤 액터를 선택했지?"

• "네가 언리얼에서 할 수 있는 작업이 뭐야?"

나머지 질문은 원하는 대로 작성하면 됩니다! 사용하는 AI 에이전트에 따라 결과가 달라질 수 있습니다.

툴세트 및 툴세트 레지스트리

플러그인은 동일한 이름의 형제 플러그인이 제공하는 언리얼 엔진 서브시스템인 툴세트 레지스트리를 쿼리하여 툴을 탐색합니다.

툴세트(Toolset)는 UToolsetDefinition(또는 Python의 unreal.ToolsetDefinition)에서 파생되는 클래스로, 툴 호출로 표시된 함수를 하나 이상 노출합니다.

툴세트 레지스트리는 스타트업 시 이러한 클래스를 모두 수집하고, 언리얼 MCP는 각 툴 호출을 MCP 툴로 래핑하며, 래핑된 툴은 연결된 모든 MCP 클라이언트에서 사용할 수 있게 됩니다. 레지스트리는 엔진의 다른 AI 인터페이스에서 사용되므로 MCP용으로 작성된 툴세트는 해당 인터페이스에서 수정 없이 작동합니다.

MCP 툴 작성하기

실행 중인 서버에 툴을 추가하는 방법은 두 가지입니다. 첫 번째는 권장 경로이며 거의 모든 경우에 적합합니다. 두 번째는 리플렉션 기반 탐색이 적합하지 않은 고급 사례를 위한 것입니다.

툴세트 레지스트리 사용 권장 경로

툴세트는 Python의 unreal.ToolsetDefinition 또는 C++의 UToolsetDefinition에서 파생되며, 관련 툴을 그룹화하는 클래스입니다. 두 언어 모두 뛰어나므로 작업에 적합한 언어를 선택하면 됩니다. 툴세트 레지스트리 플러그인과 함께 배포되는 대부분의 툴세트(SceneTools, ActorTools, MaterialInstanceTools, ObjectTools 등)는 Python으로 작성됩니다.

Claude Code에서 작업하는 사용자는 create-toolset 스킬을 unreal-mcp Claude Code 플러그인에서 사용하여 두 언어 중 하나로 새 툴세트를 스캐폴딩할 수 있습니다. 아래에 설명된 규칙은 스캐폴드가 적용된 후에도 여전히 적용되며, 스킬은 단순히 상용구를 제거합니다.

Python으로 작성하기

Python 툴세트는 모든 플러그인의 Content/Python/ 디렉터리 아래에 .py 모듈로 존재합니다. 레지스트리는 스타트업 시 이를 탐색합니다. 배포된 ActorTools(현재 위치: Engine/Plugins/Experimental/ToolsetRegistry/Content/Python/toolset_registry/toolsets/core/actor.py)는 짧아서 쉽게 살펴볼 수 있습니다.

import unreal
import toolset_registry
from toolset_registry.toolsets.core.utils import require_editable


@unreal.uclass()
class ActorTools(unreal.ToolsetDefinition):
    """Provides tools for inspecting and modifying actors, including
    their transforms, labels, parent-child relationships, and components."""

다음 규칙이 적용됩니다.

• @unreal.uclass() 데코레이터는 클래스를 언리얼 엔진 리플렉션에 노출합니다. 클래스는 unreal.ToolsetDefinition을 상속합니다.

• 클래스 독스트링은 툴세트 자체를 설명하고 툴세트의 그룹화 설명으로 표시됩니다.

• 각 툴 기능은 @toolset_registry.tool_call 데코레이터를 포함하며, @staticmethod로 선언됩니다. @toolset_registry.tool_call이 없는 함수는 애드버타이징되지 않습니다.

• 파라미터 및 반환 타입 힌트(unreal.Actor, str, bool, list[str], 데이터 클래스 등)는 툴이 애드버타이징하는 JSON 스키마를 제어합니다.

• 함수 독스트링은 Args: 및 Returns: 블록을 포함하는 Google 스타일을 사용합니다. 설명 텍스트와 실행인자별 설명은 툴 스키마에 반영되며, 다른 API의 공개 인터페이스와 동일한 주의를 기울여 작성해야 합니다.

C++로 작성하기

C++ 툴세트는 다른 구문을 사용하지만 동일한 패턴을 따릅니다. UToolsetDefinition에서 파생하고, 클래스를 UCLASS(BlueprintType, Hidden)으로 마킹하고, 스태틱 UFUNCTION(meta = (AICallable)) 메서드를 노출합니다. 기능 및 각 파라미터에 대한 독 코멘트는 Python 독스트링과 동일한 방식으로 스키마에 반영됩니다.

전체 배포 예시는 GASToolsets 플러그인(Engine/Plugins/Experimental/Toolsets/GASToolsets/Source/GASToolsets/Private/AttributeSetToolset.h)의 UAttributeSetToolset에서 살펴볼 수 있습니다. 이는 비동기 비헤이비어가 없는 일반 USTRUCT 반환 타입의 두 AICallable 함수를 노출합니다. 참고로, GASToolsets는 기본적으로 비활성화된 상태로 제공되는 실험 단계 엔진 플러그인입니다. 활성화하면 처음에 실험 단계 기능 경고 프롬프트가 표시됩니다.

다음과 같은 경우 C++를 사용합니다.

• 툴에서 Python에 노출되지 않은 엔진 기능이 필요한 경우

• 툴의 시그니처가 USTRUCT 또는 Python 타입 힌트를 통해 명확하게 표현할 수 없는 기타 리플렉션 타입을 사용하는 경우

• 툴 사용 빈도가 높아 Python과 엔진의 바운더리 비용이 중요한 경우

작성 후

에디터 콘솔에서 ModelContextProtocol.RefreshTools를 실행하여 플러그인이 레지스트리를 다시 폴링하도록 강제합니다. C++ 툴에서 라이브 코딩은 기존 기능 바디에 대한 변경사항을 반영하지만, 새로운 UFUNCTION을 추가하려면 에디터를 완전히 재시작해야 합니다.

다음 가이드라인을 따르면 AI 클라이언트가 언어에 관계없이 안정적으로 사용할 수 있는 툴을 생성할 수 있습니다.

• 함수는 그 크기를 작게 유지하고 명확한 용도로 제한합니다. 하나의 툴은 하나의 역할만 담당해야 합니다.

• 자유 형식 스트링보다 의미를 손쉽게 파악할 수 있는 함수 이름과 구조화된 반환 타입을 사용합니다. 구조화된 타입은 필드 레벨 타입 및 설명과 함께 JSON 스키마로 시리얼라이즈됩니다. 자유 형식 스트링은 스키마를 포함하지 않으며, 클라이언트가 직접 파싱하도록 강제합니다.

• 툴세트 내에 있는 함수가 애드버타이징되지 않도록 제외하려면 @toolset_registry.tool_call을 생략(Python)하거나 meta = (AIIgnore)를 추가(C++)합니다.  

직접 등록

리플렉션 기반 탐색이 충분하지 않은 경우(런타임에서 스키마가 결정되는 툴, 동적으로 생성되고 제거되는 툴 또는 타입 시스템 외부의 데이터에 의해 백업되는 툴)에는 IModelContextProtocolTool을 직접 구현하고 구현을 등록합니다.

TSharedRef<IModelContextProtocolTool> Tool = MakeShared<FMyDynamicTool>();
IModelContextProtocolModule::GetChecked().AddTool(Tool);

툴의 수명이 끝나면 호출자가 등록을 취소해야 합니다. 인터페이스 메서드는 게임 스레드에서 호출되며(HTTP 서버는 코어 티커에서 틱됨), 툴세트 레지스트리에서 탐색된 툴도 마찬가지입니다.

환경설정 레퍼런스

에디터 개인설정: 모델 컨텍스트 프로토콜

콘솔 명령

명령줄 플래그

콘솔 변수

디버깅

스타트업 시 출력 로그. 자동 시작을 활성화하면 서버는 에디터를 초기화하는 동안 바인드 주소, 포트 및 URL 경로를 출력 로그에 로깅합니다. 바인딩 실패(포트가 이미 사용 중인 경우, 종속 플러그인이 누락된 경우 등)가 여기에 표시됩니다. 서버가 실행 중인 것처럼 보이지 않는 경우에는 가장 먼저 이 출력 로그를 살펴봐야 합니다.

LogModelContextProtocol 로그 카테고리. 모든 플러그인 출력은 LogModelContextProtocol을 통해 흐릅니다. 에디터 콘솔에서 로그 LogModelContextProtocol Verbose를 사용하여 상세도를 높일 수 있습니다.

MCP 인스펙터. MCP 인스펙터는 npx 명령으로 퍼블리싱되는 모든 MCP 서버의 공식 디버깅 클라이언트입니다. 툴이 나타나지 않거나, 잘못된 셰이프를 반환하거나, 프로토콜 레벨의 오류를 보고하는 경우에는 인스펙터를 실행 중인 서버를 가리키도록 설정합니다. 인스펙터는 선언된 스키마와 함께 애드버타이징된 모든 툴을 나열하고 AI 에이전트의 요청 해석을 우회하는 폼 스타일 호출 인터페이스를 제공합니다.

npx @modelcontextprotocol/inspector를 사용하여 인스펙터를 실행할 수 있습니다.

인스펙터 창이 열리면 Streamable HTTP 전송을 통해 http://127.0.0.1:8000/mcp를 가리키도록 설정합니다.

ModelContextProtocol.RefreshTools. 플러그인은 스타트업 시 툴세트 목록을 캐시합니다. 새 툴세트를 제작하거나, 변경된 함수 바디를 핫 리로드하거나, 툴세트를 제공하는 게임 피처 플러그인을 활성화한 후 이 명령을 실행하여 다시 폴링하도록 강제합니다. 툴세트 메서드를 라이브 코딩한 다음, 연결된 클라이언트가 여전히 이전 툴 스키마를 유지할 수도 있습니다. 이 경우에는 RefreshTools를 실행하고 클라이언트를 재연결하세요.

에디터 및 런타임 가용성

플러그인은 세 개의 모듈로 나뉩니다. ModelContextProtocol 및 ModelContextProtocolEngine은 런타임 모듈입니다. 이 두 개의 모듈은 서버, 프로토콜 구현, 세팅 및 StartServer, StopServer, RefreshTools, GenerateClientConfig 콘솔 명령을 소유합니다. ModelContextProtocolEditor는 에디터 전용이며, 자동 시작 후크와 툴세트 레지스트리에서 검색된 툴세트를 MCP 툴로 변환하는 작업만 담당합니다.

따라서 서버가 에디터에 엄격하게 종속되지 않습니다. 쿠킹되어 배포되는 게임 빌드는 스타트업 시 IModelContextProtocolModule::StartServer()를 호출하여 MCP 서버를 호스팅할 수 있습니다.

툴 검색

기본적으로 플러그인은 툴 검색 모드(bEnableToolSearch = true)로 실행됩니다. 이 모드에서 tools/list는 애드버타이징된 모든 툴 대신 다음의 세 가지 탐색 메타 툴을 반환합니다.

에이전트는 요청 시 이 탐색 경로를 따라가며, 이를 통해 레지스트리가 수백 개의 툴을 노출하는 경우에도 tools/list 응답을 작게 유지합니다. 이 값을 false로 설정하면 다시 모든 툴을 적극적으로 애드버타이징하지만, 초기 스키마 페이로드가 훨씬 커집니다. 툴 제작자는 툴이 적극적으로 애드버타이징된다는 점에 의존해서는 안 되며, 이는 연결하는 에이전트가 기본적으로 보게 되는 것은 툴 검색 경로이기 때문입니다.

툴 검색 메타 툴 자체는 에디터 전용 어댑터의 일부입니다. IModelContextProtocolModule::AddTool()을 통해 툴을 등록하는 쿠킹된 빌드 호스트는 bEnableToolSearch 세팅과 관계없이 이를 직접 적극적으로 애드버타이징합니다.

제한 사항 및 알려진 문제

• HTTP 및 서버 전송 이벤트만 지원합니다. stdio 및 WebSocket 전송은 지원되지 않습니다.

• 기본적으로 루프백만 사용합니다. HTTP 리스너는 [HTTPServer.Listeners] DefaultBindAddress(디폴트 localhost)에 따라 바인딩되며, 서버는 비루프백 Origin 헤더를 거부합니다. 인증 레이어가 없으므로 플러그인을 로컬 머신 외부로 노출하는 것은 안전하지 않습니다.

• MCP 리소스 및 프롬프트는 어떤 출시 툴세트에서도 애드버타이징되지 않습니다.

• 툴세트 레지스트리 어댑터는 에디터 전용입니다. 쿠킹 및 배포 빌드는 MCP 서버를 호스팅할 수 있지만(에디터 및 런타임 가용성 참고), 레지스트리를 통해 배포된 툴은 여기에서 자동으로 탐색되지 않으므로, IModelContextProtocolModule::AddTool()을 통해 명시적으로 등록해야 합니다.

• 라이브 코딩은 새 UFUNCTION 선언을 전파하지 않습니다. 툴을 추가하려면 에디터를 재시작해야 합니다.

관련 항목

• 모델 컨텍스트 프로토콜 사양

• MCP 인스펙터