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 の MCP サーバー一覧で Locus サーバーを確認してください。 Unreal Engine 5.8 の場合は、Unreal Engine 5.8 で Locus を Unreal MCP と併用するを参照してください。

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 で Locus を Unreal MCP と併用する

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

利用可能な MCP サーバーを確認するよう Codex に指示します。

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 はドキュメントワークスペースと同じ 2 つの表示ルートを理解します。どちらも単一の <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 ピンを使用しないでください。これらは現在のサポート基準外です。

一度に 1 クライアント

Locus は承認済みのアクティブクライアントセッションを 1 つだけ許可し、ツール呼び出しを一度に 1 つずつ完了します。別のクライアントがセッションを所有している場合、2 番目のクライアントは拒否されるか、アクティブなセッションが終了または期限切れになるまでビジー状態になることがあります。

先に接続したクライアントを閉じるか切断し、割り込まれた場合は少し待ってから再試行します。それでもセッションが解放されない場合は、MCP 統合の トラブルシューティング > アクティブクライアントをリセットを使います。ローカルサーバーの復旧に必要な場合だけ MCP を無効化して再有効化してください。

MCP を切断または無効化する

使用が終わったらクライアントを切断します。Locus MCP アクセスを完全に停止するには MCP を有効化をオフにします。MCP を無効にしても Locus コンテンツやローカル資格情報は削除されず、有効に戻すまでローカルエンドポイントを停止するだけです。

接続のトラブルシューティング

症状	対処
MCP が無効、またはエンドポイントがない	Unreal Editor を開いたまま MCP 統合を開き、MCP を有効化をオンにして実行中のステータスを待ちます。
クライアントが接続または資格情報を拒否する	新しい設定をコピーします。ローカルポートを変更した後や資格情報を再生成した後は必ず行ってください。古いコピーは使えません。
別のクライアントがアクティブ、または Locus がビジー	他のクライアントを閉じて少し待ち、再試行します。アクティブクライアントをリセットは、そのクライアントを使用していない場合だけ使います。ツール呼び出しを再試行する前に、進行中の Locus 操作が終わるまで待ちます。
クライアントがコンテンツを変更できない	変更を許可がオフです。許可したい対応する Locus 変更に対してだけ有効にします。
プライベートなノートやピンが拒否される	プライベートノートとピンを許可を別途有効にします。変更を許可だけではプライベートアクセスは許可されません。
ピンリクエストが未サポートのワールドコンテキストを報告する	保存済みでプロジェクト所有の `/Game/...` ワールドを使うか、タスクを Locus Editor のワークフローに戻します。通常のビューポート要件はピンを参照してください。
Unreal Editor が再起動した	プロジェクトを再度開いてクライアントを接続します。ステータスに別のエンドポイントまたは資格情報が表示される場合は新しい設定をコピーします。

一般的な Locus の問題については、トラブルシューティングを参照してください。Locus 設定の残りの項目については、設定を参照してください。