MCP 통합

Locus MCP 통합을 사용하면 Unreal Editor가 실행되는 동안 호환되는 MCP 클라이언트가 지원되는 Locus 노트, 문서, 핀 및 Locus 상태를 사용할 수 있습니다. 선택 사항이며 기본적으로 비활성화되어 있습니다.

Locus에는 자율 AI 어시스턴트가 포함되지 않습니다. 연결한 MCP 클라이언트가 AI 워크플로를 수행하고 지원되는 Locus 도구를 사용할 시점을 결정합니다.

연결 전 준비 사항

다음이 필요합니다.

프로젝트에서 Locus가 활성화된 상태로 Unreal Editor가 열려 있어야 함
Locus 설정에서 MCP 통합이 활성화되어 있어야 함
같은 컴퓨터에서 실행 중인 호환 MCP 클라이언트

Locus 엔드포인트는 컴퓨터의 로컬 엔드포인트입니다. Locus는 모든 MCP 클라이언트 또는 미래의 모든 클라이언트 버전과 호환된다고 주장하지 않습니다. Locus는 OpenAI Codex, Claude Code, Gemini CLI를 위한 온보딩 프리셋과 호환되는 다른 Streamable HTTP MCP 클라이언트를 위한 일반 옵션을 제공합니다. 이 프리셋들은 같은 Locus MCP 서버와 같은 18개 도구를 구성하며 별도의 AI 통합이 아닙니다.

실제 클라이언트 릴리스 검증에는 Codex CLI 0.147.0, Claude Code 2.1.228, Gemini CLI 0.55.1을 사용했습니다. 이는 테스트한 버전이며 영구적인 호환성을 보장하는 버전은 아닙니다.

클라이언트 연결

Unreal Editor에서 Editor Preferences > Plugins > Locus를 열고 MCP 통합을 엽니다.
MCP 활성화를 켜고 상태가 실행 중 - 클라이언트 대기 중으로 표시될 때까지 기다립니다.
연결에서 적절한 클라이언트 형식을 선택합니다. OpenAI Codex, Claude Code, Gemini CLI 또는 일반 Streamable HTTP MCP입니다.
구성 복사를 선택합니다.
복사한 구성을 MCP 클라이언트의 일반 구성 위치 또는 설정 흐름에 붙여 넣고 연결합니다.
Locus로 돌아와 상태가 클라이언트 연결됨인지 확인합니다.

복사한 구성이 현재 엔드포인트와 자격 증명의 기준입니다. Locus가 제공하지 않는 형식을 클라이언트가 요구하는 경우가 아니면 연결 구성을 직접 작성하지 마세요.

OpenAI Codex

Codex에서는 OpenAI Codex를 선택하고 구성 복사를 사용합니다. 일반 MCP 설정 흐름을 통해 복사한 TOML을 Codex에 추가한 다음 연결 전에 Codex를 다시 로드하거나 다시 시작해야 하는지 확인하세요. Codex의 MCP 서버 목록에서 Locus 서버를 확인합니다. Unreal Engine 5.8의 경우 Unreal Engine 5.8에서 Unreal MCP와 함께 Locus 사용 섹션을 참조하세요.

Claude Code

Claude Code의 경우 Locus는 프로젝트 로컬 및 사용자 개인 범위를 사용하는 공식 HTTP MCP 등록 명령을 복사합니다. 복사한 명령은 일반 터미널에서 실행하세요. 공유 자격 증명이 들어 있는 프로젝트 .mcp.json을 만들지 않습니다.

Gemini CLI

Gemini CLI의 경우 Locus는 --scope user가 포함된 공식 HTTP MCP 등록 명령을 복사합니다. 이렇게 하면 소스 컨트롤에 들어갈 수 있는 프로젝트 .gemini/settings.json을 생성하지 않고 사용자의 개인 Gemini 구성에 서버 항목과 로컬 자격 증명을 저장합니다. 대신 Locus 항목을 여러 프로젝트에서 해당 사용자가 사용할 수 있으므로 활성 엔드포인트나 자격 증명이 다른 프로젝트로 전환할 때는 새 구성을 복사하세요.

Locus는 Gemini의 --trust 옵션을 추가하지 않습니다. Gemini의 일반적인 도구 확인 정책이 계속 적용됩니다.

일반 Streamable HTTP MCP

호환 클라이언트에 지원되는 클라이언트별 형식 대신 엔드포인트와 Authorization 헤더가 필요한 경우 일반 Streamable HTTP MCP를 선택합니다. 해당 클라이언트의 개인 구성 지침을 따르고 보관할 메모나 예제에는 Bearer <LOCAL_LOCUS_CREDENTIAL> 같은 자리표시자를 사용하세요.

Unreal Engine 5.8에서 Unreal MCP와 함께 Locus 사용

Unreal Engine 5.8에 기본 제공되는 Unreal MCP와 Locus MCP는 독립적인 MCP 서버로 나란히 실행할 수 있습니다. Locus는 Unreal MCP에 종속되지 않습니다.

아래의 검증된 설정은 Codex를 사용합니다. 이는 클라이언트별 예시이며, 이 독립 서버 기능이 Codex 전용이라는 의미는 아닙니다.

Codex 예

두 서버 구성

Unreal Engine 5.8에서 Unreal MCP, All Toolsets, Terminal, Locus를 활성화합니다. Unreal MCP 서버가 활성화되어 있고 자동 시작하도록 설정되어 있는지 확인합니다.
Unreal 콘솔에서 다음을 실행합니다.
```
ModelContextProtocol.GenerateClientConfig Codex
```
Unreal은 다음 위치에 Codex 구성을 생성합니다.
```
<Project>/.codex/config.toml
```
Unreal에서 Editor Preferences > Plugins > Locus > MCP Integration을 엽니다. Locus MCP 서버를 활성화한 다음 **Copy Connection Configuration > OpenAI Codex (config.toml)**을 선택합니다.
생성된 Locus MCP 블록을 <Project>/.codex/config.toml의 Unreal이 생성한 MCP 구성 아래에 붙여넣습니다. Locus URL, 헤더 또는 자격 증명을 직접 다시 만들지 마세요. 복사한 블록이 현재 연결 구성입니다.

파일에는 두 MCP 서버 항목이 모두 있어야 합니다.

unreal-mcp
locus

Codex 시작 및 연결 확인

프로젝트 루트에서 Unreal Engine Terminal을 열고 다음을 실행합니다.

codex

Codex에 사용 가능한 MCP 서버를 확인하도록 요청합니다.

Check which MCP servers are available to you.

unreal-mcp 및 locus가 나열되어야 합니다. 그런 다음 각 통합을 별도로 테스트합니다.

Use Unreal MCP to inspect my currently selected actor.

Use Locus to get its current status and list my Notes. Do not modify anything.

연결을 로컬 및 비공개로 유지

Locus는 로컬 루프백 인터페이스에서만 수신하므로 MCP 엔드포인트는 같은 컴퓨터에서만 사용할 수 있습니다. 생성된 사용자 로컬 bearer 자격 증명이 클라이언트를 인증합니다.

구성 복사는 자격 증명이 포함된 텍스트를 생성하는 명시적인 작업입니다. 복사한 구성은 민감한 정보로 취급하고 신뢰할 수 있는 클라이언트에만 붙여 넣으세요. 문서, 이슈 보고서, 스크린샷, 채팅 메시지 또는 소스 컨트롤 구성에 포함하지 마세요. Locus는 설정에서 자격 증명을 의도적으로 표시하거나 로그에 기록하지 않습니다. 노출되었다고 생각되면 **Advanced > Regenerate Credential…**을 사용한 다음 클라이언트에 새 구성을 복사하세요.

MCP 활성화를 끄면 Locus MCP 액세스가 중지됩니다. Unreal Editor를 닫아도 활성 Locus MCP 엔드포인트가 종료됩니다. 더 넓은 로컬 콘텐츠 및 외부 클라이언트 개인 정보 보호 경계는 개인 정보 보호 및 의견을 참조하세요.

권한을 신중하게 선택

설정	허용하는 작업
읽기 전용	기본값입니다. 클라이언트는 지원되는 읽기 작업을 사용할 수 있지만 지원되는 변경 작업은 거부됩니다. 변경 허용이 꺼져 있으면 상태 요약에 `ReadOnly`로 표시됩니다.
변경 허용	지원되는 생성, 업데이트, 보관 및 댓글 작업을 활성화합니다. 연결한 클라이언트가 Locus 콘텐츠를 변경하도록 하려는 경우에만 켜세요. 임의의 Unreal 프로젝트 변경 권한을 부여하지는 않습니다.

개인 콘텐츠는 별도로 보호됩니다. 개인 노트 및 핀 허용은 기본적으로 꺼져 있으며 MCP를 활성화하거나 변경 허용을 켜도 자동으로 허용되지 않습니다. 연결한 클라이언트가 사용자 로컬 개인 노트 및 핀에 액세스해야 할 때만 켜세요. 문서는 항상 프로젝트 소유이며 개인 범위가 없습니다.

클라이언트가 할 수 있는 작업

Locus는 18개의 MCP 도구를 노출합니다. MCP 프로토콜 세부 정보가 아니라 지원하는 작업 유형으로 그룹화되어 있습니다.

그룹	도구	지원되는 작업
인프라 (2)	`locus.get_status`, `locus.get_capabilities`	Locus 상태, 권한 및 사용 가능한 기능을 확인합니다.
노트 (6)	`locus.list_notes`, `locus.get_note`, `locus.search_notes`, `locus.create_note`, `locus.update_note`, `locus.archive_note`	노트를 찾고, 읽고, 만들고, 업데이트하고, 보관합니다.
문서 (5)	`locus.list_documents`, `locus.get_document`, `locus.search_documents`, `locus.create_document`, `locus.update_document`	프로젝트 소유 Markdown 문서를 찾고, 읽고, 만들고, 업데이트합니다. MCP에서는 이름 변경, 이동 및 삭제를 사용할 수 없습니다.
핀 (5)	`locus.list_pins`, `locus.get_pin`, `locus.create_pin`, `locus.update_pin`, `locus.add_pin_comment`	핀을 찾고, 읽고, 만들고, 업데이트하고, 댓글을 추가합니다. 핀 삭제 및 보관은 MCP에서 사용할 수 없습니다.

읽기 도구는 읽기 전용에서도 사용할 수 있습니다. 지원되는 생성, 업데이트, 보관 및 댓글 도구에는 변경 허용이 필요합니다. 소스 컨트롤 및 콘텐츠 검증 규칙을 포함한 기존 Locus 보호 장치도 계속 적용됩니다.

MCP로 만든 문서는 Editor에서 만든 문서와 같은 지연 추가 워크플로를 따릅니다. 로컬 추적되지 않음으로 시작하므로 Locus에서 정리하고 이름을 바꾸고 이동하고 편집한 뒤 최종 경로가 준비되면 명시적으로 추가 대상으로 표시를 사용하세요. MCP에는 문서 이름 변경, 이동, 삭제 또는 추가 대상으로 표시 도구가 없습니다.

문서 표시 루트

MCP는 문서 작업 공간에 표시되는 동일한 두 표시 루트를 이해합니다. 둘 다 하나의 <Project>/ProjectDocuments/ 리포지토리를 보여 주는 방식입니다.

Locus 문서에는 예약된 Content/... 매핑 외부의 일반 문서가 들어 있습니다. Design/Combat.md 같은 표시 경로의 권위 있는 경로는 Design/Combat.md입니다.
콘텐츠 브라우저에는 Unreal 콘텐츠 브라우저 컨텍스트로 프로젝션된 Markdown 문서가 들어 있습니다. Characters/Hero.md 같은 표시 경로의 권위 있는 문서 경로는 Content/Characters/Hero.md이며 대응하는 /Game/Characters 컨텍스트에 매핑됩니다.

콘텐츠 브라우저 문서는 외부 Markdown 파일로 유지됩니다. UAsset이 아니며 /Game/...은 표시 컨텍스트이지 문서 ID가 아닙니다. 정규화된 ProjectDocuments 상대 Markdown 경로가 권위 있는 ID입니다.

locus.list_documents 및 locus.search_documents는 선택적인 presentationRoot 값 all, locusDocuments 또는 contentBrowser를 허용하며 생략하면 all이 기본값입니다. 필터링은 인덱싱된 목록/검색 작업의 일부이며 기존 정렬 및 페이지 매김 동작을 유지합니다.

locus.create_document는 호출자가 표시 루트를 명시적으로 선택하려는 경우 locusDocuments 또는 contentBrowser를 허용합니다. 이 모드에서 relativePath는 선택한 표시 루트에 상대적입니다.

`presentationRoot`	제공된 `relativePath`	생성되는 권위 경로
`locusDocuments`	`Design/Combat.md`	`Design/Combat.md`
`contentBrowser`	`Characters/Hero.md`	`Content/Characters/Hero.md`

contentBrowser 아래에서 명시적으로 만들 때 Content/를 앞에 붙이지 마세요. Locus가 예약 매핑을 한 번 적용합니다. presentationRoot를 생략하는 기존 호출자는 이전 권위 경로 계약을 유지하므로 기존 Content/Characters/Hero.md 입력은 이전 의미를 그대로 유지합니다.

문서 결과는 다음을 구분합니다.

relativePath: ProjectDocuments 아래의 권위 있는 정규화 ID
presentationRoot: locusDocuments 또는 contentBrowser
presentationPath: 표시 루트 아래에 보이는 경로

루트 필드는 컨텍스트를 제공할 뿐 다른 리포지토리나 문서 ID를 만들지 않습니다.

locus.archive_note는 노트의 수명 주기 상태를 Archived로 바꾸며 노트를 별도의 Archived Notes 패널로 이동하지 않습니다. Locus 1.0에서는 보관된 노트가 일반 노트 작업 공간에 계속 표시되며 전용 Editor Archive/Restore 워크플로 또는 locus.restore_note 도구가 없습니다. MCP에서 노트를 Open 상태로 되돌리려면 현재 리비전과 status: "open"을 사용해 locus.update_note를 호출하세요.

핀 월드 지원

지원되는 핀 기준은 명시적인 월드 ID와 Unreal 월드 공간 위치를 가진 저장된 프로젝트 소유 /Game/... 월드입니다. 저장된 프로젝트 소유 World Partition 핀의 기본 작업은 지원됩니다.

플러그인 마운트 맵, 저장되지 않은/임시/미리 보기/PIE 런타임 월드, 특수한 언로드 World Partition 영역, 액터 추적 또는 외부 액터 앵커, Data Layer별 동작, Level Instances, 기존 스트리밍 서브레벨 또는 월드 이름 변경/리디렉션 복구에는 MCP 핀을 의존하지 마세요. 이러한 컨텍스트는 현재 지원 기준 밖입니다.

한 번에 한 클라이언트

Locus는 승인된 활성 클라이언트 세션 하나만 허용하며 도구 호출을 한 번에 하나씩 완료합니다. 다른 클라이언트가 세션을 소유하면 두 번째 클라이언트가 거부되거나 활성 세션이 종료 또는 만료될 때까지 사용 중으로 표시될 수 있습니다.

먼저 연결된 클라이언트를 닫거나 연결 해제하고 중단된 경우 잠시 기다린 뒤 다시 시도하세요. 그래도 세션이 해제되지 않으면 MCP 통합의 문제 해결 > 활성 클라이언트 초기화를 사용합니다. 로컬 서버를 복구해야 할 때만 MCP를 비활성화했다가 다시 활성화하세요.

MCP 연결 해제 또는 비활성화

사용을 마치면 클라이언트 연결을 해제합니다. Locus MCP 액세스를 완전히 중지하려면 MCP 활성화를 끕니다. MCP를 비활성화해도 Locus 콘텐츠나 로컬 자격 증명은 삭제되지 않고 다시 활성화할 때까지 로컬 엔드포인트만 중지합니다.

연결 문제 해결

증상	조치
MCP가 비활성화되었거나 엔드포인트가 없음	Unreal Editor를 열어 두고 MCP 통합을 열어 MCP 활성화를 켠 뒤 실행 상태를 기다립니다.
클라이언트가 연결 또는 자격 증명을 거부함	새 구성을 복사합니다. 로컬 포트를 변경하거나 자격 증명을 재생성한 뒤 수행하세요. 이전에 복사한 구성은 더 이상 작동하지 않습니다.
다른 클라이언트가 활성 상태이거나 Locus가 사용 중	다른 클라이언트를 닫고 잠시 기다린 뒤 다시 시도합니다. 활성 클라이언트 초기화는 해당 클라이언트를 더 이상 사용하지 않을 때만 사용합니다. 도구 호출을 다시 시도하기 전에 진행 중인 Locus 작업이 끝날 때까지 기다립니다.
클라이언트가 콘텐츠를 변경할 수 없음	변경 허용이 꺼져 있습니다. 허용하려는 지원 Locus 변경에 대해서만 활성화합니다.
개인 노트 또는 핀이 거부됨	개인 노트 및 핀 허용을 별도로 활성화합니다. 변경 허용만으로는 개인 액세스가 허용되지 않습니다.
핀 요청이 지원되지 않는 월드 컨텍스트를 보고함	저장된 프로젝트 소유 `/Game/...` 월드를 사용하거나 작업을 Locus Editor 워크플로로 되돌립니다. 일반 뷰포트 요구 사항은 핀을 참조하세요.
Unreal Editor가 다시 시작됨	프로젝트를 다시 열고 클라이언트를 연결합니다. 상태에 다른 엔드포인트 또는 자격 증명이 표시되면 새 구성을 복사하세요.

일반적인 Locus 문제는 문제 해결을 참조하세요. 나머지 Locus 설정 화면은 설정을 참조하세요.