UEFN MCP

UEFN MCP는 포트나이트 언리얼 에디터 프로세스 내에 MCP 서버를 임베드하여 Claude Code, Cursor 또는 MCP Inspector와 같은 MCP 호환 AI 에이전트가 로컬 HTTP 연결을 통해 에디터를 제어할 수 있게 해줍니다.

UEFN MCP는 UEFN에 특화된 다음과 같은 기능을 제공합니다. 

• Verse 씬 그래프 엔티티 생성 및 수정

• Verse 파일 읽기 및 쓰기

• 포크리 장치 배치 및 장치 프로퍼티 편집

• 플레이 세션 시작, 중지 및 검사

MCP란 무엇인가요?

UEFN MCP는 UEFN 에디터 프로세스 내에 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 서버를 임베드합니다. 모든 MCP 호환 AI 에이전트는 로컬 HTTP를 통해 MCP에 연결되고, 툴세트로 그룹화된 타입 지정된 툴을 통해 에디터를 제어합니다. MCP는 에이전트가 Verse 읽기, 씬 그래프 편집, 포크리 장치 배치 및 환경설정, 플레이 세션 실행을 검사 및 작업할 수 있도록 에디터를 변경합니다. 

개발자가 실행 중인 에디터에 에이전트(예: Claude Code)를 연결하도록 설정하면 자연어로 질문하거나 지시할 수 있습니다. 몇 가지 예를 들면 다음과 같습니다.

• 어떤 장치를 배치할 수 있어?

• 라운드가 시작되면 로그를 추가하고 컴파일해 줘.

• 테스트할 수 있게 세션을 시작해 줘.

이러한 유형의 질문과 지시를 통해 에이전트는 사용 가능한 툴세트를 찾고, 툴을 호출하고, 이를 보고합니다. 

UEFN MCP 전제 조건

UEFN MCP를 사용하려면 진행하기 전에 프로젝트에서 다음을 설정해야 합니다.

1. 프로젝트에서 파이썬 에디터 스크립팅(Python Editor Scripting)을 활성화합니다.

2. MCP가 자동 시작되도록 환경설정합니다.

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

4. 포트나이트 UEFN 설치 디렉터리에서 AI 에이전트를 시작합니다.

파이썬 및 UEFN MCP 활성화

프로젝트 세팅(Project Settings)에서 파이썬 에디터 스크립팅 및 UEFN MCP 툴세트(UEFN MCP Toolsets) 박스를 체크합니다.

MCP 자동 시작 환경설정

MCP 자동 시작 환경설정 방법은 다음과 같습니다.

• 편집(Edit) > 에디터 개인설정(Editor Preferences)을 엽니다.

• 일반(General) 그룹에서 모델 컨텍스트 프로토콜을 선택합니다.

이렇게 하면 서버 자동 시작(Auto Start Server) 설정이 나타나며, 이 설정을 활성화하면 에디터가 실행될 때마다 MCP 서버를 자동으로 시작하고, MCP 서버를 http://127.0.0.1:8000/mcp에 바인딩합니다. 

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

대신 필요에 따라 서버를 시작하길 원한다면 서버 자동 시작을 끄고 에디터 콘솔에 ModelContextProtocol.StartServer를 입력합니다.

이 명령은 ModelContextProtocol.StartServer:8000과 같은 선택적 포트도 허용합니다.

클라이언트 구성 생성

각 AI 에이전트는 서버 리스트가 특정 파일 포맷으로 프로젝트 트리 내 특정 위치에 있다고 예상합니다. AI 에이전트는 UEFN이 설치된 위치를 알아야 합니다. 

빠르게 액세스하려면 런처 설치 파일 위치를 확인하여 해당 폴더 위치를 직접 열 수 있습니다.

UEFN 설치 파일(프로젝트 파일 아님)이 저장된 위치를 확인한 다음 .mcp.json 파일을 생성합니다.

mcp.json 파일 생성 방법은 다음과 같습니다. 

1. UEFN 프로젝트 루트 폴더에서 우클릭해 새로운 텍스트 문서를 만듭니다. 이름을 .mcp.txt로 지정합니다.  

   

2. 텍스트 문서를 엽니다.

3. 다음 텍스트를 파일에 복사하여 붙여넣습니다. 이는 특정 모델의 JSON이며, 사용하는 특정 AI 에이전트에 맞게 포맷을 지정해야 합니다. 아래 예시는 Claude의 JSON입니다.

   Config

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

   Copy full snippet(9 lines long)

4. 모든 파일로 설정하고 끝부분의 .txt 확장자를 .json으로 바꿔 저장합니다.

   

AI 에이전트 구성을 생성했다면, Codex CLI를 사용할 때 기억해야 할 관리 사항이 하나 있습니다. Codex CLI가 사용하는 TOML 구성은 한 번만 기록되므로, 이 명령은 기존 파일을 덮어쓰지 않습니다. 그러므로 기존 구성은 직접 삭제해야 합니다. Claude Code, Cursor, VS Code, Gemini에서 사용하는 JSON 포맷 환경설정의 경우 기존 항목과 병합되므로 명령을 반복 실행해도 안전합니다. 

AI 에이전트 연결

AI 에이전트를 UEFN에 연결하려면 .mcp.json 환경설정 파일이 생성된 프로젝트 또는 워크스페이스 루트에서 선호하는 AI 에이전트 CLI 또는 애플리케이션을 실행합니다. 해당 파일 위치에 환경설정 파일을 생성할 경우 출력 로그를 참조할 수 있습니다. 

아래는 .mcp.json 파일이 생성된 폴더에서 Claude를 실행하는 방법의 예시입니다. 

연결 문제가 있는 경우에는 다음 단계를 시도해 보세요.

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

• 디폴트 포트(8000)가 다른 서비스에서 사용 중인 경우 다른 포트를 시도합니다. 이는 에디터 개인설정에서 서버 포트 번호로 설정할 수 있습니다.

• 프로젝트 세팅에서 파이썬 에디터 스크립팅 및 UEFN MCP 툴세트가 모두 활성화되었는지 확인합니다.

• 서버를 시작하고 중지하려면 에디터를 닫았다가 다시 열어야 합니다. 확실하지 않은 경우 에디터를 다시 시작하세요.

언리얼 MCP는 다른 어떤 기능과 상호작용하나요?

툴세트 프롬프트 제안

아래 표에는 각 기능의 활용법을 단계별로 살펴볼 수 있는 몇 가지 프롬프트가 나열되어 있습니다. 이는 모든 툴세트가 의도대로 작동하는지 다시 한번 확인하는 데에도 활용할 수 있습니다. 

최상의 결과를 위한 팁

• 구체적인 이름으로 요청하세요.

  • 프롬프트 입력 시, 에이전트에게 오브젝트 관련 작업을 요청할 때는 최대한 구체적으로 요청하는 것이 좋습니다. 예를 들어, 에이전트에게 '타이머 장치'를 변경해달라고 요청하면 '아까 추가한 장치'를 변경해달라고 요청하는 것보다 더 나은 결과를 얻을 수 있습니다.

• 에이전트에게 사용 가능한 툴을 나열해 달라고 요청하세요.

  • 이를 위해 탐색 툴이 존재하며, 잘못된 추측을 줄이는 데 도움이 됩니다.

• 다단계 요청은 계획을 요구하세요.

  • 에이전트에게 작업 실행을 지시하기 전에 제공된 계획을 검토하세요. 이렇게 하면 에이전트가 의도를 잘못 추측하는 것을 방지할 수 있습니다.

• 변경 사항을 검토할 수 있게 유지하세요.

  • 다수의 소규모 편집이 한 번의 대규모 변경보다 더 검증하기 간편합니다. 이러한 변경 사항의 검증은 점점 더 까다로워질 수 있고 검증 과정에서 무언가를 놓칠 수 있습니다.

알려진 문제

다음은 현재 조사 중인 알려진 문제 목록이며, 추후 출시 버전에서 해결될 수 있습니다.

• LUF에서 XYZ 형식으로 좌표계 및 트랜스폼 변환.

  • 현재 파이썬 툴세트는 왼쪽-위쪽-앞쪽(LUF) 좌표계 대신 XYZ 포맷을 사용합니다. XYZ 좌표계를 UEFN에서 사용하는 LUF 좌표계로 변환하는 경우, AI 에이전트에 변환을 요청하면 제대로 작동할 때도 있지만 두 시스템의 공간 수학 처리 방식이 달라 오류 발생 가능성이 높아집니다.

• 에디터 끊김 현상

  • MCP 툴 호출 시 에디터가 끊기거나 멈출 수 있습니다. 현재 문제를 조사 중이며, 에디터에서의 툴 호출 효율성을 높일 방법을 검토하고 있습니다.