서론

Unreal Engine 5.8에는 Unreal Editor의 기능을 MCP (Model Context Protocol)를 통해 AI 에이전트에게 공개하는 Unreal MCP 플러그인이 추가되었습니다. Codex를 연결하면 Actor 조사·편집, 라이팅, Material Instance 생성, Automation Test 등을 자연어로 요청할 수 있습니다.

하지만, 이것은 "Codex에 UE 프로젝트를 통째로 맡기면 알아서 멋지게 완성되는" 기능이 아닙니다.

UE5.8 시점의 Unreal MCP는 Experimental (실험적) 단계입니다. Epic Games의 Unreal MCP 공식 문서에도 미완성 또는 미구현된 기능이 있으며, API나 데이터 형식이 변경될 수 있다고 명시되어 있습니다. 또한, Unreal MCP의 HTTP 서버는 인증을 갖추지 않으며, Tool 호출은 Unreal Engine의 게임 스레드(Game Thread) 상에서 직렬로 실행됩니다. 편리함만 보고 기존 프로젝트에 연결하면 의도치 않은 Asset 편집, 저장 위치 착오, 여러 클라이언트에 의한 상태 경합을 일으킬 수 있습니다.

본고에서는 Server, Toolset Registry, AllToolsets의 역할부터 Codex 설정, Tool Search, 제한적 쓰기, 복구, Custom Tool화까지 순차적으로 다룹니다.

UE5.8의 Unreal MCP는 무엇을 하는 플러그인인가

구성을 먼저 파악하면 연결 트러블의 원인을 분류하기 쉬워집니다.

Codex CLI / Codex IDE 확장
│
│ MCP Streamable HTTP
...

플러그인 식별자와 Console Command 상의 명칭은 ModelContextProtocol이며, Plugin Browser 상의 표시 이름은 Unreal MCP입니다.

Unreal MCP 자체는 주로 Server와 접속구를 담당하며, 실제 조작은 Toolset Registry에 등록된 Toolset으로부터 가져옵니다. 동봉된 Tool을 한꺼번에 활성화하는 입구가 AllToolsets입니다.

따라서 다음 상태는 서로 다릅니다.

통신 확인 시에는 AllToolsets를 사용하고, 운용 시에는 불필요한 Toolset을 제거할 수 있는지 확인하여 Codex 측의 승인 설정과 함께 입구를 좁힙니다.

Unreal MCP로 할 수 있는 것과, 너무 기대하지 않는 것이 좋은 것

Epic Games의 공식 문서에서는 Unreal MCP에서 이용할 수 있는 예시로 다음과 같은 것들을 들고 있습니다.

• Actor의 생성과 편집
• 라이팅 설정
• Material Instance 생성
• Slate Widget 조사
• Automation Test 실행
• Toolset Registry를 사용한 독자 Tool 추가

이것만 보면 무엇이든 조작할 수 있을 것 같지만, MCP는 "Editor UI를 인간처럼 조작하는 매크로"가 아닙니다. Codex는 Unreal MCP가 공개한 Tool 이름, 인자 Schema (Argument Schema), 설명을 읽고 해당 Tool을 호출합니다. 공개되지 않은 처리는 호출할 수 없으며, 모호한 지시로부터 항상 올바른 Asset, Level, 좌표계, 저장 위치를 추측할 수 있는 것도 아닙니다.

또한, UE5.8의 Unreal MCP는 MCP의 Tools를 중심으로 구현되어 있어, 동봉된 Toolset으로부터 Resources나 Prompts는 공개되지 않습니다. Codex 측에서 "MCP 연결은 보이는데 Resource가 없다"라고 표시되더라도, 그것만으로 연결 실패라고 판단할 수는 없습니다.

또 하나 중요한 것은 실행 순서입니다. 외부에서 전달된 Tool 호출은 게임 스레드로 동기화되어 직렬로 실행됩니다. 하나의 Editor에 여러 Codex 세션이나 다른 MCP 클라이언트를 동시에 접속하여 중첩된 쓰기를 던지는 설계는 피해야 합니다. 병렬화하여 속도를 높이는 대상이 아니라, 한 번에 한 조작씩 상태를 확인하며 진행하는 Editor 확장 입구로 취급하는 것이 안전합니다.

도입 전에 만드는 검증 환경

기존 제작 중인 Level에 바로 연결하기보다, 전용 Sandbox를 준비합니다.

최소한 다음을 준비합니다.

• UE5.8에서 열 수 있는 검증용 프로젝트, 또는 본 프로젝트의 복사본
• Source Control 상의 작업 Branch
• MCP_Sandbox

와 같은 전용 Level -
/Game/MCPTest

와 같은 전용 Content 폴더 - Codex CLI 또는 Codex IDE 확장

• 작업 시작 전의 Commit 또는 Checkpoint

검증용 Level은 바닥(Floor), 조명(Light), 확인용 Static Mesh 정도로 제한하며, World Partition이나 제작 중인 Sequencer는 제외합니다. 가장 먼저 확인해야 할 기본 동작은 다음과 같습니다.

• Codex가 대상 Editor에 연결할 수 있는가
• 현재 선택된 Actor를 읽어올 수 있는가
• Toolset을 열거하고, 필요한 Tool의 Schema를 설명할 수 있는가
• 지정된 Level과 폴더만 변경할 수 있는가
• 저장 후 상태를 다시 가져와서, 자기 보고(Self-reporting)가 아닌 실제 결과를 확인할 수 있는가
• 예상치 못한 상태에서 중단될 수 있는가

다른 Level에 Actor가 잔류하는지, 동일한 이름의 Asset, 불필요한 Component, 저장 누락 등도 확인하며, 복구 가능한 지점에서 차이점(diff)의 특성을 파악한 뒤 범위를 넓혀갑니다.

Codex 준비하기

이미 Codex CLI를 사용 중이라면 이 절을 건너뛸 수 있습니다. 도입되지 않았다면, OpenAI 공식 Installer 또는 npm을 통해 도입합니다.

Windows PowerShell에서는 다음과 같습니다.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

macOS/Linux에서는 다음과 같습니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Node.js 환경에 npm으로 설치하는 경우는 다음과 같습니다.

npm install -g @openai/codex

위의 두 가지 방식은 OpenAI 공식 절차이지만, Remote Script를 그대로 실행하는 pipe-to-shell 방식입니다.

스크립트 실행이 금지된 기업용 단말기에서는 스크립트를 저장하여 내용을 확인하거나, npm/Homebrew, 공식 Release, 사내 배포 Package를 사용하는 등 조직의 기준을 우선하십시오.

도입 후, Project Directory에서 codex를 실행하고, 처음에는 ChatGPT 계정 등 사용 가능한 방법으로 Sign in 합니다. 본문에서는 Codex 자체의 filesystem 편집 기능이 아니라, Codex가 MCP Client로서 Unreal Editor에 연결되는 부분을 다룹니다.

Unreal Editor 측 설정

1. Unreal MCP 활성화하기

Unreal Editor에서 Edit > Plugins를 열고, Unreal MCP를 검색하여 활성화합니다. 의존 관계에 있는 Toolset Registry는 자동으로 활성화됩니다. Editor 재시작을 요청받으면 재시작합니다.

2. AllToolsets 활성화하기

동일한 Plugin Browser에서 AllToolsets를 검색하여 활성화합니다. 이것이 UE5.8에 포함된 각종 Toolset을 한꺼번에 활성화하는 입구입니다. 재시작을 요청받으면 여기서도 Editor를 재시작합니다.

Unreal MCP만 활성화한 상태에서 "연결은 되는데 Actor 조작을 찾을 수 없다"고 고민하는 경우, 먼저 이곳을 확인하십시오. Experimental 플러그인 경고가 표시되는 경우, 대상 프로젝트가 검증용임을 확인한 후 진행합니다.

3. 서버 수동 실행하기

Edit > Editor Preferences > General > Model Context Protocol을 열면 다음 항목을 확인할 수 있습니다. 아래는 UE5.8 공식 문서의 기본값입니다. 업데이트 이후에는 실제 화면과 Output Log를 우선하십시오.

처음에는 Auto Start Server를 비활성화 상태로 두고, 필요한 시간 동안만 서버를 실행하는 운영 방식을 권장합니다. Editor Console에 다음과 같이 입력합니다.

ModelContextProtocol.StartServer

포트를 명시하는 경우는 다음과 같습니다.

ModelContextProtocol.StartServer 8000

기본 연결 대상은 다음과 같습니다.

Output Log에서 LogModelContextProtocol

를 검색하여 bind 대상, port, URL path를 확인합니다. 8000번 포트가 다른 로컬 서비스와 충돌하는 경우, Editor Preferences에서 port를 변경하거나 실행 Command에 다른 port를 전달합니다.

작업 종료 시에는 다음 명령으로 정지할 수 있습니다.

ModelContextProtocol.StopServer

인증이 없는 로컬 HTTP 서버이므로, "사용하지 않을 때도 그냥 켜두는" 방식보다는 필요할 때만 사용하는 것이 다루기 쉽습니다. 접속 절차가 안정화된 후에 필요에 따라 Auto Start Server로 전환합니다.

Codex용 설정 생성하기

Unreal Editor의 Console에서 다음을 실행합니다.

ModelContextProtocol.GenerateClientConfig Codex

지원되는 Client에는 ClaudeCode, Cursor, VSCode, Gemini, Codex, All이 있습니다. 본고에서는 설정 차이를 최소화하기 위해 Codex만 생성합니다.

Codex는 사용자 공통 설정으로 ~/.codex/config.toml을 사용하며, 신뢰할 수 있는 Project에서는 Project 직하의 .codex/config.toml도 읽어들입니다. Unreal MCP 생성 Command를 실행한 후, Output Log에 표시된 생성 위치를 확인하십시오.

Epic의 GenerateClientConfig를 통한 Codex용 TOML 생성 프로세스는 write-once입니다. config.toml 자체는 편집할 수 있지만, 생성 위치에 기존 TOML이 있으면 덮어쓰지 않습니다. 다른 MCP 설정을 지우지 않도록 필요한 Entry를 수동으로 merge하십시오.

UE5.8의 Unreal MCP는 stdio나 WebSocket이 아닌 HTTP/Server-Sent Events를 사용하므로, Codex에는 command가 아닌 Streamable HTTP의 url을 등록합니다. 최소 구성은 다음과 같습니다.

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8000/mcp"

실무에서는 처음부터 무조건 실행되도록 설정하기보다, 승인(approval)과 timeout을 추가합니다.

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8000/mcp"
required = false
...

required = false로 설정하면, Editor를 실행하지 않은 일반적인 Codex 작업이 MCP 초기화 실패로 인해 중단되지 않습니다. Unreal 전용 Session에서 연결을 필수적으로 만들어야 한다면 true를 검토하십시오.

Tool timeout의 기본값은 60초입니다. 지속적으로 이 시간을 초과하는 처리의 경우 120을 초기 조정값으로 설정할 수 있지만, 길게 설정한다고 해서 성공이 보장되지는 않습니다. timeout 발생 후에는 재전송하지 말고, Editor 상태와 Output Log를 확인하십시오.

default_tools_approval_mode = "prompt"로 설정하면 Tool 호출 전에 확인할 수 있습니다. Toolset과 인자(argument)를 파악하는 초기 단계에서는 prompt를 사용합니다.

writes는 read-only로 지정된 Tool을 통과시키고 그 외의 것들을 확인합니다. 다만 Tool Search에서는 외부의 call_tool에 읽기/쓰기가 집중되어, 내부를 개별적으로 판정할 수 있다고 단정할 수는 없습니다. 초기에는 prompt를 사용하고, 개별 공개나 annotation 확인 후에 writes를 검토하십시오.

Codex를 Project Root에서 실행하기

UE5.8의 공식 절차에서는 생성된 설정 파일이 있는 Project 또는 Workspace Root에서 AI Agent를 실행합니다. Installed Build와 Source Build는 기점이 다를 수 있으므로, Output Log에서 생성 위치를 확인한 후 해당 Directory로 이동합니다.

cd C:\Work\Unreal\MCPExample
codex

Codex TUI에서는 다음 명령으로 Current Session의 Active MCP Server를 확인합니다.

/mcp

Terminal에서 설정된 Server를 확인하는 Command는 다음과 같습니다.

codex mcp list

codex mcp list

는 설정 등록 확인이며, unreal-mcp가 표시되더라도 HTTP 통신(Connectivity)까지 증명하는 것은 아닙니다. /mcp에서 Active 상태를 확인하고, End-to-End 통신은 다음 절의 list_toolsets / describe_toolset 응답 또는 MCP Inspector를 통해 확인합니다. Entry 자체가 나타나지 않는 경우의 확인 순서는, 후술할 「unreal-mcp 자체가 Codex에 나타나지 않는 경우」로 단일화합니다.

Project 로컬의 .codex/config.toml은 Codex가 해당 Project를 신뢰(Trust)하고 있는 경우에만 읽어옵니다. User 공통의 ~/.codex/config.toml에 작성했을 때는 보이지만 Project 설정에서는 보이지 않는다면, 신뢰 상태와 실행 디렉토리(Directory)를 확인하십시오.

처음에 보이는 3개의 Tool은 정상

UE5.8에서는 Enable Tool Search가 기본적으로 활성화되어 있습니다. 이 모드에서는 Codex에 처음부터 수백 개의 Tool Schema를 보내는 대신, MCP의 tools/list에는 다음 3가지만 공개됩니다. 아래는 UE5.8 공식 명칭입니다. 업데이트 이후에는 /mcp와 MCP Inspector의 실제 Schema를 기준으로 삼으십시오.

즉, /mcp에서 Actor 조작이나 Material 조작 Tool 이름이 대량으로 나열되지 않고 3개만 보이더라도 이상한 것이 아닙니다. Codex는 필요할 때 Toolset을 검색하고, Schema를 가져온 뒤, call_tool을 통해 실제 처리를 호출합니다.

여기에는 Codex 측의 허용 목록(Allowlist)을 설계할 때의 주의사항이 있습니다.

Codex의 enabled_tools는 MCP 서버가 공개한 Tool 이름을 제한합니다. 기본 Tool Search 모드에서는 공개된 이름이 3개로 집약되기 때문에, call_tool을 허용하면 그 내부에서 호출되는 개별 Tool을 enabled_tools만으로는 세밀하게 구분할 수 없습니다. 이는 Epic Games의 Tool Search 사양과 Codex의 MCP Allowlist 사양을 조합했을 때 발생하는 입도(Granularity)의 차이입니다.

따라서 첫 번째 읽기 확인 시에는 call_tool을 허용하지 않고, 다음과 같이 탐색용 Tool만 공개할 수 있습니다.

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8000/mcp"
enabled_tools = ["list_toolsets", "describe_toolset"]
...

실제 조작으로 넘어갈 때 call_tool을 추가합니다.

enabled_tools = ["list_toolsets", "describe_toolset", "call_tool"]

단, 이것으로 내부 Tool이 세밀하게 제한되는 것은 아닙니다. call_tool은 매번 prompt로 처리하며, Unreal 측에서는 필요한 Toolset만 활성화하고, 지시문과 AGENTS.md를 통해 대상을 한정합니다.

세밀한 Allowlist가 필요하다면 Enable Tool Search를 비활성화하여 모든 Tool을 개별 공개할 수 있습니다. 다만, 초기 Schema가 커지고, UE 업데이트 시의 Tool 이름·Schema 차이, enabled_tools의 업데이트 누락, 과도한 권한 부여 등을 지속적으로 검토해야 합니다. 우선 기본 모드에서 Toolset 구성을 파악하고, 운영 비용에 부합하는 경우에만 전환하십시오.

읽기만으로 연결을 확인하기

1. Toolset과 Schema만 탐색하기

첫 번째 프롬프트(Prompt)에서는 변경을 요청하지 않습니다.

Unreal MCP로의 연결 상태를 확인해 주세요.
이번 턴에서는 Unreal Editor의 상태를 일절 변경하지 마십시오.
1. list_toolsets로 이용 가능한 Toolset을 열거한다
...

2. 선택 중인 Actor의 실제 값을 읽기

탐색만으로 확인이 끝났다면, .codex/config.toml의 enabled_tools

call_tool

을 추가하고 Codex를 재시작합니다. 다음으로 Epic Games가 Quick Start에서 예시로 든 "선택 중인 Actor"를 사용합니다. Sandbox Level에서 Cube를 하나 선택하고 다음과 같이 요청합니다.

현재 Unreal Editor에서 선택 중인 Actor를 읽어 들여 다음을 보고해 주세요.
- Actor Label
- Class
...

여기서 확인하고자 하는 것은 답변문의 유창함이 아니라, Editor 상의 실제 값과 일치하는지 여부입니다. Cube의 Location을 사람이 약간 변경한 뒤 다시 가져오게 하여, 이전 값이 반환되지 않는지도 확인합니다.

성공 조건은 다음과 같습니다.

• 의도한 Editor의 선택 상태를 읽을 수 있었다
• Actor Label과 Object Path를 혼동하지 않는다
• World Transform을 명시할 수 있었다
• 읽기 도중에 선택이나 Asset을 변경하지 않았다
• 실제로 사용한 Toolset과 Tool 이름을 보고했다

읽기에 실패한 상태에서 쓰기(Write)로 진행해서는 안 됩니다. 연결 대상, Schema, Level 인식 중 어디에 문제가 있는지 모르는 상태에서 차분(diff)만 늘어나기 때문입니다.

첫 번째 쓰기는 Sandbox Level로 한정한다

첫 번째 쓰기 과제는 복잡한 Blueprint 생성 대신, 결과를 육안으로 확인하기 쉬운 Actor 배치로 설정합니다.

사전에 MCP_Sandbox Level을 열고 저장합니다. Codex에 다음과 같이 요청합니다.

Unreal MCP를 사용하여 현재 열려 있는 MCP_Sandbox Level만 편집해 주세요.
목적:
- Point Light를 하나 추가한다
...

Codex의 "완료했습니다"를 완료 조건으로 삼지 말고, 계획 및 승인 → 한 번에 한 작업씩 실행 → 저장 전후의 재취득 → Editor와 Source Control에서 확인까지를 하나의 세트로 구성합니다.

Unreal MCP의 Tool 호출은 게임 스레드(Game Thread)에서 직렬 실행되므로, 여러 Codex subagent에게 Actor 배치를 분담시키는 방식의 사용은 하지 않습니다. 다른 Agent가 중간에 동일한 Level의 상태를 변경하면, 먼저 세운 계획의 전제가 무너지기 때문입니다.

Material Instance 생성은 입력과 출력을 고정한다

다음 과제로 Material Instance 생성은 결과를 검증하기 쉬운 소재입니다. 다만 "그럴듯한 빨간색 Material을 만들어줘"라고 하면, 부모 Material(Parent Material), 저장 위치, Parameter 이름이 모호해집니다.

부모 Material, 출력 위치, Asset 이름, 변경 가능한 Parameter와 값, 덮어쓰기 가능 여부, 생성 후 확인 방법을 고정합니다. 프롬프트(Prompt) 예시입니다.

Unreal MCP를 사용하여 Material Instance를 하나 생성해 주세요.
입력:
- Parent: /Game/MCPTest/Materials/M_Master
...

실무에서는 Asset 생성보다 "기존 Asset을 멋대로 수정하지 않는 것"이 더 중요합니다. 동일한 이름의 Asset이 있을 경우의 처리를 반드시 결정합니다. overwrite를 자연어의 분위기에 따라 판단하게 하지 말고, 중지, 다른 이름 지정, 명시적 허가 중 하나로 고정합니다.

Automation Test는 읽기 중심의 진입점에 적합하다

Unreal MCP는 Automation Test 실행도 상정하고 있습니다. Editor 상태를 변경하는 Tool보다 리스크를 낮게 시작할 수 있지만, Test가 Asset 생성이나 Map 전환을 포함하는 경우에는 부작용이 있습니다.

다음과 같이 Test 이름과 기대 결과를 한정합니다.

Unreal MCP로 Automation Test를 실행해 주세요.
대상:
Project.MCP.Smoke
...

"Test가 실패하면 수정해줘"까지 한꺼번에 요청하면 관측과 변경이 뒤섞입니다. 첫 번째 턴(Turn)은 실행과 기록만 수행하고, 수정은 차분안을 확인한 뒤 별도의 턴으로 분리합니다.

AGENTS.md에 Unreal MCP 운영 규칙을 작성하기

매번 긴 제약 사항을 프롬프트에 붙여넣는 대신, Project Root의 AGENTS.md에 반복해서 지켜야 할 규칙을 작성합니다. Codex는 작업 시작 전에 AGENTS.md를 읽고, Project Root에서 Current Directory까지의 지시를 중첩하여 적용합니다. 탐색 순서와 덮어쓰기 규칙은 OpenAI의 AGENTS.md 공식 문서에서 확인할 수 있습니다.

예시입니다.

Unreal MCP 작업 협약 (Working Agreement)

범위 (Scope)

• Unreal MCP의 쓰기 대상은 /Game/MCPTest와 MCP_Sandbox Level뿐입니다.
  ...

AGENTS.md는 권한 메커니즘이 아니므로, MCP 승인 (approval), 플러그인 (Plugin) 범위, 소스 컨트롤 (Source Control), 샌드박스 (Sandbox)를 병용합니다. 변경 후에도 이전 규칙으로 동작하는 경우, 프로젝트 루트 (Project Root)에서 새로운 세션 (Session)을 시작하여 다시 읽어들입니다.

Tool이 보이지 않을 때의 문제 해결 (Troubleshooting)

unreal-mcp 자체가 Codex에 나타나지 않음

확인 순서는 다음과 같습니다.

• StartServer 실행 후, 출력 로그 (Output Log)에서 실제 엔드포인트 (Endpoint) URL 확인
• .codex/config.toml 파일과 대조
• 프로젝트 (Project) / 워크스페이스 (Workspace) 루트, 프로젝트의 신뢰 상태 확인
• Codex를 재시작하고, codex mcp list로 설정 등록 확인
• /mcp를 통해 현재 세션 (Current Session)의 활성 (Active) 상태 확인
• list_toolsets 또는 MCP Inspector를 통해 실제 통신 여부 확인

codex mcp list에는 표시되지만 list_toolsets가 반환되지 않는 경우에는 설정 등록 문제가 아니라 서버 (Server) 실행, 엔드포인트 (Endpoint), 포트 (Port) 충돌, 또는 세션 (Session) 재연결 문제를 조사해야 합니다.

3개의 메타 Tool (Meta Tool)만 보임

Enable Tool Search = true 상태라면 정상입니다. list_toolsets, describe_toolset, call_tool을 통해 필요한 툴셋 (Toolset)을 찾으십시오.

list_toolsets가 비어 있거나 Actor 계열 Toolset이 없음

Unreal MCP, Toolset Registry, AllToolsets의 활성화 상태를 확인하고 에디터 (Editor)를 재시작하십시오. 플러그인 (Plugin)을 활성화한 직후에는 Codex 측만 재연결할 경우 에디터의 레지스트리 (Registry)가 업데이트되지 않았을 가능성이 있습니다.

Toolset을 추가했는데 스키마 (Schema)가 오래됨

에디터 콘솔 (Editor Console)에서 다음을 실행합니다.

ModelContextProtocol.RefreshTools

그 후 Codex를 재연결합니다. Python Toolset이나 기존 C++ 함수 본체의 변경 사항은 업데이트할 수 있지만, 새로운 UFUNCTION 선언은 라이브 코딩 (Live Coding)만으로는 반영되지 않으며 에디터 재시작이 필요합니다.

포트 (Port) 충돌로 인해 실행되지 않음

출력 로그 (Output Log)에는 바인드 (bind) 실패 메시지도 나타납니다. 포트를 변경한 경우, 에디터 측뿐만 아니라 .codex/config.toml의 URL도 일치시켜야 합니다.

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8123/mcp"

설정 생성 후에 포트를 변경하면 Codex용 TOML은 자동으로 따라가지 않습니다.

Tool 호출이 타임아웃 (timeout)됨

타임아웃이 반드시 "실패하여 아무 일도 일어나지 않음"을 의미하지는 않습니다. 에디터 측에서는 처리가 완료되었거나, 중간까지 변경되었거나, 게임 스레드 (Game Thread)가 장시간 처리 중일 가능성이 있습니다.

다음 순서로 복구합니다.

• 동일한 call_tool을 재전송하지 말 것 - 에디터가 조작 가능한지 확인
• 출력 로그 (Output Log)를 확인
• 대상 Actor / 에셋 (Asset)을 다시 읽기
• 소스 컨트롤 (Source Control) 차이(diff) 확인
• 완료되지 않은 부분만 새로운 계획으로 수립

동일한 생성 작업을 재전송하면 중복된 Actor나 접미사 번호가 붙은 에셋 (Asset)을 만드는 원인이 됩니다.

MCP Inspector로 Codex와 Server 구분하기

Codex의 해석에 문제가 있는 것인지, Unreal MCP의 스키마 (Schema)나 응답에 문제가 있는 것인지 알 수 없을 때는 MCP Inspector를 사용합니다.

Node.js와 npm을 사용할 수 있는 환경에서 다음을 실행합니다.

npx @modelcontextprotocol/inspector

npx는 최초 실행 시 패키지 (Package)를 가져올 수 있으므로, Node.js/npm 외에도 네트워크 액세스 (Network Access) 및 실행 확인이 필요합니다. 여기서 멈춘다고 해서 반드시 Unreal MCP의 장애인 것은 아닙니다. 관리용 단말기에서는 승인된 버전 (Version)이나 사내 레지스트리 (Registry)를 사용합니다.

Inspector를 실행하고, Transport에 Streamable HTTP, URL에 다음을 지정합니다.

Inspector에서는 공개된 Tool, Schema, 인자 Form (Argument Form), Protocol Error를 직접 확인할 수 있습니다. Inspector에서도 Tool을 실행할 수 있으므로, 문제 분리 (Troubleshooting) 중에는 탐색 및 읽기를 우선하며, 쓰기 작업은 Sandbox와 Source Control이 있는 상태로 제한합니다. Inspector에서도 Tool이 보이지 않는다면 Unreal 측의 문제이고, Inspector에서는 작동하는데 Codex에서 실패한다면 Codex 설정, 승인 (Approval), Prompt 해석을 중심으로 조사합니다.

더 상세한 Unreal MCP Log가 필요하다면, Editor Console에서 Log verbosity를 높입니다.

Log LogModelContextProtocol Verbose

조사 후에는 Log 양이 계속 늘어나지 않도록 설정을 되돌리고, 기밀 정보를 포함할 수 있는 Project Log의 공유 범위에도 주의합니다.

로컬 연결이라도 "무조건 안전"하지는 않음

Unreal MCP는 기본적으로 loopback에 bind하며, 비(non) loopback Origin을 거부합니다. 반면 인증 계층 (Authentication Layer)은 없습니다. 공식 문서에서도 로컬 머신 외부로 공개하는 용도로는 안전하지 않다고 명시하고 있습니다.

따라서, 다음은 수행하지 않습니다.

0.0.0.0