MCP-Integration

Die Locus-MCP-Integration ermöglicht einem kompatiblen MCP-Client, während der Unreal Editor läuft, mit unterstützten Locus-Notizen, Dokumenten, Pins und dem Locus-Status zu arbeiten. Sie ist optional und standardmäßig deaktiviert.

Locus enthält keinen autonomen KI-Assistenten. Ihr verbundener MCP-Client führt den KI-Workflow aus und entscheidet, wann er die unterstützten Locus-Tools verwendet.

Vor der Verbindung

Sie benötigen:

einen geöffneten Unreal Editor mit für das Projekt aktiviertem Locus
aktivierte MCP-Integration in den Locus-Einstellungen
einen kompatiblen MCP-Client auf derselben Maschine

Der Locus-Endpunkt ist lokal auf Ihrem Computer. Locus behauptet keine Kompatibilität mit jedem MCP-Client oder jeder zukünftigen Client-Version. Locus bietet Onboarding-Voreinstellungen für OpenAI Codex, Claude Code und Gemini CLI sowie eine allgemeine Option für andere kompatible Streamable-HTTP-MCP-Clients. Diese Voreinstellungen konfigurieren denselben Locus-MCP-Server und dieselben 18 Tools; sie sind keine getrennten KI-Integrationen.

Die Release-Validierung mit echten Clients verwendete Codex CLI 0.147.0, Claude Code 2.1.228 und Gemini CLI 0.55.1. Betrachten Sie dies als getestete Versionen und nicht als dauerhafte Kompatibilitätsgarantie.

Einen Client verbinden

Öffnen Sie im Unreal Editor Editor Preferences > Plugins > Locus und anschließend MCP Integration.
Aktivieren Sie MCP aktivieren und warten Sie, bis der Status Running - waiting for client anzeigt.
Wählen Sie unter Connection das passende Client-Format: OpenAI Codex, Claude Code, Gemini CLI oder Generic Streamable HTTP MCP.
Wählen Sie Konfiguration kopieren.
Fügen Sie die kopierte Konfiguration in den normalen Konfigurationsort oder Einrichtungsablauf Ihres MCP-Clients ein und verbinden Sie ihn.
Kehren Sie zu Locus zurück und prüfen Sie, ob der Status Client connected anzeigt.

Die kopierte Konfiguration ist die Quelle der Wahrheit für den aktuellen Endpunkt und die Zugangsdaten. Schreiben Sie eine Verbindungskonfiguration nicht von Hand, außer Ihr Client benötigt ein Format, das Locus nicht anbietet.

OpenAI Codex

Wählen Sie für Codex OpenAI Codex und verwenden Sie Konfiguration kopieren. Fügen Sie das kopierte TOML über den normalen MCP-Einrichtungsablauf in Codex ein und laden Sie Codex neu oder starten Sie es neu, falls dies vor der Verbindung erforderlich ist. Prüfen Sie den Locus-Server in der MCP-Serverliste von Codex. Weitere Hinweise für Unreal Engine 5.8 finden Sie im Abschnitt Locus mit Unreal MCP in Unreal Engine 5.8 verwenden.

Claude Code

Für Claude Code kopiert Locus den offiziellen HTTP-MCP-Registrierungsbefehl mit projektspezifischem, benutzerprivatem Bereich. Führen Sie den kopierten Befehl in einem normalen Terminal aus. Er erstellt keine gemeinsame, zugangsdatenhaltige Projektdatei .mcp.json.

Gemini CLI

Für Gemini CLI kopiert Locus den offiziellen HTTP-MCP-Registrierungsbefehl mit --scope user. Dadurch werden Servereintrag und lokale Zugangsdaten in der privaten Gemini-Konfiguration des Benutzers gespeichert, statt eine Projektdatei .gemini/settings.json zu erzeugen, die in die Quellcodeverwaltung gelangen könnte. Der Nachteil ist, dass der Locus-Eintrag diesem Benutzer projektübergreifend zur Verfügung steht; kopieren Sie beim Wechsel zu einem Projekt mit anderem aktivem Endpunkt oder anderen Zugangsdaten eine frische Konfiguration.

Locus fügt Geminis Option --trust nicht hinzu. Geminis normale Bestätigungspolitik für Tools bleibt aktiv.

Generisches Streamable HTTP MCP

Wählen Sie Generic Streamable HTTP MCP, wenn ein kompatibler Client den Endpunkt und den Authorization-Header statt eines client-spezifischen Formats benötigt. Folgen Sie den privaten Konfigurationshinweisen dieses Clients und verwenden Sie in Notizen oder Beispielen Platzhalter wie Bearer <LOCAL_LOCUS_CREDENTIAL>.

Locus mit Unreal MCP in Unreal Engine 5.8 verwenden

Der integrierte Unreal MCP von Unreal Engine 5.8 und Locus MCP können nebeneinander als unabhängige MCP-Server laufen. Locus hängt nicht von Unreal MCP ab.

Das unten verifizierte Setup verwendet Codex. Es ist ein clientspezifisches Beispiel und keine Aussage, dass diese Fähigkeit unabhängiger Server nur für Codex gilt.

Codex-Beispiel

Beide Server konfigurieren

Aktivieren Sie in Unreal Engine 5.8 Unreal MCP, All Toolsets, Terminal und Locus. Stellen Sie sicher, dass der Unreal-MCP-Server aktiviert ist und automatisch startet.
Führen Sie in der Unreal-Konsole Folgendes aus:
```
ModelContextProtocol.GenerateClientConfig Codex
```
Unreal erzeugt die Codex-Konfiguration unter:
```
<Project>/.codex/config.toml
```
Öffnen Sie in Unreal Editor Preferences > Plugins > Locus > MCP Integration. Aktivieren Sie den Locus-MCP-Server und wählen Sie anschließend Copy Connection Configuration > OpenAI Codex (config.toml).
Fügen Sie den erzeugten Locus-MCP-Block unter der von Unreal erzeugten MCP-Konfiguration in <Project>/.codex/config.toml ein. Erstellen Sie Locus-URLs, Header oder Zugangsdaten nicht von Hand; der kopierte Block ist die aktuelle Verbindungskonfiguration.

Die Datei muss beide MCP-Servereinträge enthalten:

unreal-mcp
locus

Codex starten und die Verbindung prüfen

Öffnen Sie das Unreal-Engine-Terminal im Projektstamm und führen Sie Folgendes aus:

codex

Bitten Sie Codex, die verfügbaren MCP-Server zu prüfen:

Check which MCP servers are available to you.

Es sollte unreal-mcp und locus auflisten. Testen Sie anschließend jede Integration getrennt:

Use Unreal MCP to inspect my currently selected actor.

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

Verbindung lokal und privat halten

Locus lauscht nur auf der lokalen Loopback-Schnittstelle; der MCP-Endpunkt ist daher nur auf derselben Maschine verfügbar. Ein erzeugtes benutzerlokales Bearer-Token authentifiziert den Client.

Konfiguration kopieren ist die ausdrückliche Aktion, die Text mit Zugangsdaten erzeugt. Behandeln Sie die kopierte Konfiguration als vertraulich und fügen Sie sie nur in einen vertrauenswürdigen Client ein. Legen Sie sie nicht in Dokumentation, Fehlerberichten, Screenshots, Chatnachrichten oder von der Quellcodeverwaltung erfassten Konfigurationen ab. Locus zeigt die Zugangsdaten nicht absichtlich in den Einstellungen an und schreibt sie nicht in Logs. Wenn Sie glauben, dass sie offengelegt wurden, verwenden Sie Advanced > Regenerate Credential… und kopieren Sie eine frische Konfiguration in den Client.

Das Deaktivieren von MCP aktivieren beendet den Locus-MCP-Zugriff. Das Schließen des Unreal Editors beendet ebenfalls den aktiven Locus-MCP-Endpunkt. Zur umfassenderen Datenschutzgrenze für lokale Inhalte und externe Clients siehe Datenschutz und Feedback.

Berechtigungen bewusst wählen

Einstellung	Erlaubnis
Nur Lesen	Der Standard. Clients können unterstützte Leseoperationen verwenden; unterstützte Änderungsoperationen werden verweigert. Die Statuszusammenfassung zeigt `ReadOnly`, wenn Änderungen zulassen deaktiviert ist.
Änderungen zulassen	Aktiviert unterstützte Operationen zum Erstellen, Aktualisieren, Archivieren und Kommentieren. Aktivieren Sie dies nur, wenn der verbundene Client Locus-Inhalte ändern soll. Eine beliebige Änderung am Unreal-Projekt wird dadurch nicht erlaubt.

Private Inhalte sind separat geschützt. Private Notizen und Pins zulassen ist standardmäßig deaktiviert; weder die Aktivierung von MCP noch Änderungen zulassen gewährt die Berechtigung automatisch. Aktivieren Sie es nur, wenn der verbundene Client auf lokale private Notizen und Pins zugreifen soll. Dokumente sind immer projekt-eigen und haben keinen privaten Bereich.

Was Clients tun können

Locus stellt 18 MCP-Tools bereit. Sie sind nach der Art der unterstützten Arbeit und nicht nach Protokolldetails gruppiert.

Gruppe	Tools	Unterstützte Arbeit
Infrastruktur (2)	`locus.get_status`, `locus.get_capabilities`	Locus-Status, Berechtigungen und verfügbare Fähigkeiten prüfen.
Notizen (6)	`locus.list_notes`, `locus.get_note`, `locus.search_notes`, `locus.create_note`, `locus.update_note`, `locus.archive_note`	Notizen finden, lesen, erstellen, aktualisieren und archivieren.
Dokumente (5)	`locus.list_documents`, `locus.get_document`, `locus.search_documents`, `locus.create_document`, `locus.update_document`	Projekt-eigene Markdown-Dokumente finden, lesen, erstellen und aktualisieren. Umbenennen, Verschieben und Löschen sind über MCP nicht verfügbar.
Pins (5)	`locus.list_pins`, `locus.get_pin`, `locus.create_pin`, `locus.update_pin`, `locus.add_pin_comment`	Pins finden, lesen, erstellen, aktualisieren und kommentieren. Löschen und Archivieren von Pins ist über MCP nicht verfügbar.

Lesewerkzeuge bleiben im Modus Nur Lesen verfügbar. Die unterstützten Werkzeuge zum Erstellen, Aktualisieren, Archivieren und Kommentieren benötigen Änderungen zulassen. Die bestehenden Locus-Schutzmaßnahmen, einschließlich Regeln der Quellcodeverwaltung und der Inhaltsvalidierung, gelten weiterhin.

Über MCP erstellte Dokumente folgen demselben verzögerten Hinzufügen wie im Editor erstellte Dokumente: Sie beginnen lokal und Nicht verfolgt. Organisieren, benennen Sie sie um, verschieben oder bearbeiten Sie sie in Locus und wählen Sie anschließend ausdrücklich Zum Hinzufügen markieren, wenn der endgültige Pfad feststeht. MCP bietet keine Werkzeuge zum Umbenennen, Verschieben, Löschen oder Zum-Hinzufügen-Markieren von Dokumenten.

Präsentationswurzeln der Dokumente

MCP versteht dieselben zwei Präsentationswurzeln wie der Dokumente-Arbeitsbereich. Beide sind Ansichten desselben Repositorys <Project>/ProjectDocuments/:

Locus-Dokumente enthält normale Dokumente außerhalb der reservierten Zuordnung Content/.... Ein Präsentationspfad wie Design/Combat.md hat denselben maßgeblichen Pfad: Design/Combat.md.
Content Browser enthält Markdown-Dokumente, die in den Unreal-Content-Browser-Kontext projiziert werden. Ein Präsentationspfad wie Characters/Hero.md hat den maßgeblichen Dokumentpfad Content/Characters/Hero.md und wird in den passenden /Game/Characters-Kontext abgebildet.

Content-Browser-Dokumente bleiben externe Markdown-Dateien. Sie sind keine UAssets und /Game/... ist Präsentationskontext statt Dokumentidentität. Der normalisierte, zu ProjectDocuments relative Markdown-Pfad bleibt maßgeblich.

locus.list_documents und locus.search_documents akzeptieren optional presentationRoot mit dem Wert all, locusDocuments oder contentBrowser; ohne Angabe ist der Standard all. Die Filterung bleibt Teil der indexierten Listen-/Suchoperation und behält die bestehende Reihenfolge und Seitennavigation.

locus.create_document akzeptiert locusDocuments oder contentBrowser, wenn der Aufrufer eine sichtbare Wurzel ausdrücklich wählen möchte. In diesem Modus ist relativePath relativ zur ausgewählten Präsentationswurzel:

`presentationRoot`	Angegebener `relativePath`	Erstellter maßgeblicher Pfad
`locusDocuments`	`Design/Combat.md`	`Design/Combat.md`
`contentBrowser`	`Characters/Hero.md`	`Content/Characters/Hero.md`

Fügen Sie bei einer expliziten Erstellung unter contentBrowser nicht Content/ voran; Locus wendet die reservierte Zuordnung einmal an. Bestehende Aufrufer ohne presentationRoot behalten den bisherigen Vertrag des maßgeblichen Pfads, sodass eine Eingabe Content/Characters/Hero.md ihre bisherige Bedeutung behält.

Dokumentergebnisse unterscheiden:

relativePath: die maßgebliche normalisierte Identität unter ProjectDocuments
presentationRoot: locusDocuments oder contentBrowser
presentationPath: der unter dieser Präsentationswurzel sichtbare Pfad

Die Wurzelfelder liefern Kontext; sie führen kein weiteres Repository und keine weitere Dokumentkennung ein.

locus.archive_note ändert den Lebenszyklusstatus einer Notiz in „Archiviert“; es verschiebt die Notiz nicht in ein separates Archiv-Panel. Locus 1.0 zeigt archivierte Notizen weiterhin im normalen Notizen-Arbeitsbereich an und besitzt keinen Editor-Workflow zum Archivieren/Wiederherstellen und kein Werkzeug locus.restore_note. Um eine Notiz über MCP in den Status „Open“ zurückzuführen, verwenden Sie locus.update_note mit der aktuellen Revision und status: "open".

Unterstützung von Pin-Welten

Die unterstützte Pin-Basis ist eine gespeicherte, projekt-eigene /Game/...-Welt mit ausdrücklicher Weltidentität und Unreal-Position im Weltraum. Grundlegende gespeicherte projekt-eigene World-Partition-Pin-Arbeit wird unterstützt.

Verlassen Sie sich bei MCP-Pins nicht auf pluginmontierte Maps, nicht gespeicherte, transiente, Vorschau- oder PIE-/Laufzeitwelten, spezialisierte nicht geladene World-Partition-Regionen, Actor-folgende oder External-Actor-Anker, Data-Layer-spezifisches Verhalten, Level Instances, traditionelle Streaming-Sublevels oder die Wiederherstellung nach Weltumbenennung und Redirects. Diese Kontexte liegen außerhalb der derzeit unterstützten Basis.

Immer nur ein Client

Locus erlaubt eine aktive autorisierte Clientsitzung und verarbeitet Toolaufrufe nacheinander. Wenn ein anderer Client die Sitzung besitzt, kann ein zweiter Client abgewiesen oder als beschäftigt angezeigt werden, bis die aktive Sitzung endet oder abläuft.

Schließen oder trennen Sie zuerst den früheren Client, warten Sie kurz, falls er unterbrochen wurde, und versuchen Sie es erneut. Wenn die Sitzung nicht freigegeben wird, verwenden Sie Troubleshooting > Reset Active Client in der MCP-Integration. Deaktivieren und aktivieren Sie MCP nur, wenn dies zur Wiederherstellung des lokalen Servers nötig ist.

MCP trennen oder deaktivieren

Trennen Sie den Client, wenn Sie ihn nicht mehr verwenden. Um den Locus-MCP-Zugriff vollständig zu stoppen, deaktivieren Sie MCP aktivieren. Das Deaktivieren von MCP löscht weder Locus-Inhalte noch die lokale Zugangsdaten; es stoppt nur den lokalen Endpunkt, bis Sie ihn wieder aktivieren.

Verbindungsfehler beheben

Symptom	Maßnahme
MCP ist deaktiviert oder kein Endpunkt verfügbar	Lassen Sie den Unreal Editor geöffnet, öffnen Sie MCP Integration, aktivieren Sie MCP aktivieren und warten Sie auf einen laufenden Status.
Der Client lehnt Verbindung oder Zugangsdaten ab	Kopieren Sie eine frische Konfiguration. Tun Sie dies nach einer Änderung des lokalen Ports oder einer Regenerierung der Zugangsdaten; ältere kopierte Konfigurationen funktionieren dann nicht mehr.
Ein anderer Client ist aktiv oder Locus ist beschäftigt	Schließen Sie den anderen Client, warten Sie kurz und versuchen Sie es erneut. Verwenden Sie Reset Active Client nur, wenn dieser Client nicht mehr verwendet wird. Warten Sie, bis eine laufende Locus-Operation beendet ist, bevor Sie einen Toolaufruf wiederholen.
Ein Client kann Inhalte nicht ändern	Änderungen zulassen ist deaktiviert. Aktivieren Sie es nur für die unterstützten Locus-Änderungen, die Sie zulassen möchten.
Private Notizen oder Pins werden abgewiesen	Aktivieren Sie Private Notizen und Pins zulassen separat. Änderungen zulassen allein gewährt keinen privaten Zugriff.
Eine Pin-Anfrage meldet einen nicht unterstützten Weltkontext	Verwenden Sie eine gespeicherte, projekt-eigene `/Game/...`-Welt oder wechseln Sie zurück zum Locus-Editor-Workflow. Siehe Pins zu normalen Viewport-Anforderungen.
Der Unreal Editor wurde neu gestartet	Öffnen Sie das Projekt erneut und verbinden Sie den Client. Kopieren Sie eine frische Konfiguration, wenn der Status einen anderen Endpunkt oder andere Zugangsdaten anzeigt.

Bei allgemeinen Locus-Problemen siehe Fehlerbehebung. Informationen zur übrigen Oberfläche der Locus-Einstellungen finden Sie unter Einstellungen.