Intégration MCP

L’intégration MCP de Locus permet à un client MCP compatible de travailler avec les Notes, Documents, Repères et informations d’état Locus pris en charge pendant l’exécution d’Unreal Editor. Elle est facultative et désactivée par défaut.

Locus n’inclut pas d’assistant IA autonome. Votre client MCP connecté exécute le workflow IA et décide quand utiliser les outils Locus pris en charge.

Avant la connexion

Vous avez besoin de :

Unreal Editor ouvert avec Locus activé pour le projet ;
MCP Integration activée dans les paramètres Locus ;
un client MCP compatible exécuté sur la même machine.

Le point de terminaison Locus est local à votre ordinateur. Locus ne revendique pas la compatibilité avec tous les clients MCP ni avec toutes leurs versions futures. Locus fournit des préréglages d’intégration pour OpenAI Codex, Claude Code et Gemini CLI, ainsi qu’une option générique pour les autres clients MCP Streamable HTTP compatibles. Ces préréglages configurent le même serveur MCP Locus et les mêmes 18 outils ; ce ne sont pas des intégrations IA distinctes.

La validation de publication avec de vrais clients a utilisé Codex CLI 0.147.0, Claude Code 2.1.228 et Gemini CLI 0.55.1. Considérez-les comme des versions testées et non comme des garanties permanentes de compatibilité.

Connecter un client

Dans Unreal Editor, ouvrez Editor Preferences > Plugins > Locus, puis MCP Integration.
Activez Enable MCP et attendez que le statut affiche Running - waiting for client.
Sous Connection, choisissez le Format client approprié : OpenAI Codex, Claude Code, Gemini CLI ou Generic Streamable HTTP MCP.
Sélectionnez Copier la configuration.
Collez la configuration copiée dans l’emplacement de configuration ou le parcours de configuration normal du client MCP, puis connectez-le.
Revenez dans Locus et vérifiez que le statut affiche Client connected.

La configuration copiée est la source de vérité du point de terminaison et de l’identifiant actuels. N’écrivez pas une configuration de connexion à la main, sauf si votre client exige un format que Locus ne propose pas.

OpenAI Codex

Pour Codex, choisissez OpenAI Codex et utilisez Copier la configuration. Ajoutez le TOML copié à Codex avec son parcours normal de configuration MCP, puis rechargez ou redémarrez Codex si nécessaire avant la connexion. Confirmez le serveur Locus dans la liste des serveurs MCP de Codex. Pour Unreal Engine 5.8, consultez la section Utiliser Locus avec Unreal MCP dans Unreal Engine 5.8.

Claude Code

Pour Claude Code, Locus copie la commande officielle d’enregistrement HTTP MCP avec un scope local au projet et privé à l’utilisateur. Exécutez la commande copiée dans un terminal normal. Elle ne crée pas de .mcp.json de projet partagé contenant un identifiant.

Gemini CLI

Pour Gemini CLI, Locus copie la commande officielle d’enregistrement HTTP MCP avec --scope user. Cela stocke l’entrée du serveur et l’identifiant local dans la configuration Gemini privée de l’utilisateur au lieu de générer un .gemini/settings.json de projet qui pourrait entrer dans le contrôle de source. En contrepartie, l’entrée Locus est disponible pour cet utilisateur dans tous les projets ; copiez une configuration récente lorsque vous passez à un projet avec un autre point de terminaison ou identifiant actif.

Locus n’ajoute pas l’option --trust de Gemini. La politique normale de confirmation des outils de Gemini reste en vigueur.

Generic Streamable HTTP MCP

Choisissez Generic Streamable HTTP MCP lorsqu’un client compatible a besoin du point de terminaison et de l’en-tête Authorization plutôt que d’un format propre à un client pris en charge. Suivez les conseils de configuration privée de ce client et utilisez des espaces réservés tels que Bearer <LOCAL_LOCUS_CREDENTIAL> dans vos notes ou exemples conservés.

Utiliser Locus avec Unreal MCP dans Unreal Engine 5.8

L’Unreal MCP intégré à Unreal Engine 5.8 et Locus MCP peuvent s’exécuter côte à côte comme serveurs MCP indépendants. Locus ne dépend pas d’Unreal MCP.

La configuration vérifiée ci-dessous utilise Codex. C’est un exemple propre à ce client, et non l’affirmation que cette capacité de serveurs indépendants est réservée à Codex.

Exemple Codex

Configurer les deux serveurs

Dans Unreal Engine 5.8, activez Unreal MCP, All Toolsets, Terminal et Locus. Vérifiez que le serveur Unreal MCP est activé et configuré pour démarrer automatiquement.
Dans la console Unreal, exécutez :
```
ModelContextProtocol.GenerateClientConfig Codex
```
Unreal génère la configuration Codex à l’emplacement suivant :
```
<Project>/.codex/config.toml
```
Dans Unreal, ouvrez Editor Preferences > Plugins > Locus > MCP Integration. Activez le serveur MCP de Locus, puis sélectionnez Copy Connection Configuration > OpenAI Codex (config.toml).
Collez le bloc MCP Locus généré sous la configuration MCP générée par Unreal dans <Project>/.codex/config.toml. Ne recréez pas manuellement les URL, en-têtes ou identifiants Locus ; le bloc copié est la configuration de connexion actuelle.

Le fichier doit contenir les deux entrées de serveur MCP :

unreal-mcp
locus

Démarrer Codex et vérifier la connexion

Ouvrez le Terminal Unreal Engine à la racine du projet et exécutez :

codex

Demandez à Codex de vérifier les serveurs MCP disponibles :

Check which MCP servers are available to you.

Il doit répertorier unreal-mcp et locus. Testez ensuite chaque intégration séparément :

Use Unreal MCP to inspect my currently selected actor.

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

Garder la connexion locale et privée

Locus écoute uniquement sur l’interface loopback locale ; le point de terminaison MCP n’est donc disponible que sur la même machine. Un identifiant bearer local généré pour l’utilisateur authentifie le client.

Copier la configuration est l’action explicite qui produit le texte contenant l’identifiant. Traitez la configuration copiée comme sensible et collez-la uniquement dans un client de confiance. Ne l’incluez pas dans la documentation, des rapports de problème, des captures d’écran, des messages de chat ou une configuration sous contrôle de source. Locus n’affiche pas intentionnellement l’identifiant dans les paramètres et ne l’écrit pas dans les journaux. Si vous pensez qu’il a été exposé, utilisez Advanced > Regenerate Credential…, puis copiez une configuration récente dans le client.

Désactiver Enable MCP arrête l’accès MCP Locus. Fermer Unreal Editor met également fin au point de terminaison MCP Locus actif. Pour la limite plus large de confidentialité des contenus locaux et des clients externes, voir Confidentialité et retours.

Choisir les autorisations délibérément

Paramètre	Autorisation
Lecture seule	Le comportement par défaut. Les clients peuvent utiliser les opérations de lecture prises en charge, mais les opérations de modification sont refusées. Le résumé d’état affiche `ReadOnly` lorsque Autoriser les modifications est désactivé.
Autoriser les modifications	Active les opérations prises en charge de création, mise à jour, archivage et commentaire. Ne l’activez que si vous voulez que le client connecté modifie le contenu Locus. Cela n’accorde pas de modification arbitraire du projet Unreal.

Le contenu privé est protégé séparément. Autoriser les Notes et Repères Privés est désactivé par défaut ; ni l’activation de MCP ni Autoriser les modifications ne l’accorde automatiquement. Activez-le uniquement lorsque le client connecté doit accéder aux Notes et Repères privés locaux. Les Documents appartiennent toujours au projet et n’ont pas de scope Privé.

Ce que les clients peuvent faire

Locus expose 18 outils MCP, regroupés par type de travail pris en charge plutôt que par détails du protocole MCP.

Groupe	Outils	Travail pris en charge
Infrastructure (2)	`locus.get_status`, `locus.get_capabilities`	Vérifier l’état, les autorisations et les capacités disponibles de Locus.
Notes (6)	`locus.list_notes`, `locus.get_note`, `locus.search_notes`, `locus.create_note`, `locus.update_note`, `locus.archive_note`	Trouver, lire, créer, mettre à jour et archiver des Notes.
Documents (5)	`locus.list_documents`, `locus.get_document`, `locus.search_documents`, `locus.create_document`, `locus.update_document`	Trouver, lire, créer et mettre à jour des Documents Markdown appartenant au projet. Le renommage, le déplacement et la suppression ne sont pas disponibles via MCP.
Repères (5)	`locus.list_pins`, `locus.get_pin`, `locus.create_pin`, `locus.update_pin`, `locus.add_pin_comment`	Trouver, lire, créer, mettre à jour et commenter les Repères. La suppression et l’archivage des Repères ne sont pas disponibles via MCP.

Les outils de lecture restent disponibles en Lecture seule. Les outils pris en charge de création, mise à jour, archivage et commentaire nécessitent Autoriser les modifications. Les protections Locus existantes, notamment les règles de contrôle de source et de validation du contenu, s’appliquent toujours.

Les Documents créés via MCP suivent le même workflow d’ajout différé que ceux créés dans l’Editor : ils commencent en local et Non suivi. Organisez, renommez, déplacez ou modifiez-les dans Locus, puis utilisez explicitement Marquer pour ajout lorsque le chemin final est prêt. MCP ne fournit pas d’outils de renommage, déplacement, suppression ou marquage pour ajout des Documents.

Racines de présentation des Documents

MCP comprend les deux mêmes racines de présentation que l’espace de travail Documents. Toutes deux sont des vues du dépôt unique <Project>/ProjectDocuments/ :

Documents Locus contient les Documents normaux en dehors du mapping réservé Content/.... Un chemin de présentation comme Design/Combat.md a le même chemin faisant autorité : Design/Combat.md.
Content Browser contient les Documents Markdown projetés dans le contexte Unreal Content Browser. Un chemin comme Characters/Hero.md a le chemin faisant autorité Content/Characters/Hero.md et correspond au contexte /Game/Characters.

Les Documents Content Browser restent des fichiers Markdown externes. Ils ne sont pas des UAssets et /Game/... est un contexte de présentation plutôt qu’une identité de Document. Le chemin Markdown normalisé relatif à ProjectDocuments reste l’autorité.

locus.list_documents et locus.search_documents acceptent une valeur facultative presentationRoot parmi all, locusDocuments et contentBrowser; en l’absence de valeur, le défaut est all. Le filtrage fait partie de l’opération indexée de liste/recherche et conserve l’ordre et la pagination existants.

locus.create_document accepte locusDocuments ou contentBrowser lorsque l’appelant veut choisir explicitement une racine visible. Dans ce mode, relativePath est relatif à la racine sélectionnée :

`presentationRoot`	`relativePath` fourni	Chemin faisant autorité créé
`locusDocuments`	`Design/Combat.md`	`Design/Combat.md`
`contentBrowser`	`Characters/Hero.md`	`Content/Characters/Hero.md`

N’ajoutez pas Content/ lors d’une création explicite sous contentBrowser ; Locus applique une seule fois le mapping réservé. Les appelants qui omettent presentationRoot conservent le contrat précédent du chemin faisant autorité ; une entrée historique Content/Characters/Hero.md garde donc son sens existant.

Les résultats Document distinguent :

relativePath : l’identité normalisée faisant autorité sous ProjectDocuments ;
presentationRoot : locusDocuments ou contentBrowser ;
presentationPath : le chemin visible sous cette racine de présentation.

Les champs de racine fournissent un contexte ; ils n’introduisent ni dépôt ni identifiant de Document supplémentaire.

locus.archive_note fait passer l’état de cycle de vie d’une Note à Archived ; il ne déplace pas la Note vers un panneau Archived séparé. Locus 1.0 conserve les Notes archivées visibles dans l’espace de travail Notes normal et ne fournit ni workflow Editor Archive/Restore dédié ni outil locus.restore_note. Pour ramener une Note à l’état Open via MCP, utilisez locus.update_note avec la révision courante et status: "open".

Prise en charge des mondes pour les Repères

La base prise en charge est un monde /Game/... enregistré et appartenant au projet, avec une identité de monde explicite et une position Unreal dans l’espace. Les Repères de base dans un monde World Partition enregistré et appartenant au projet sont pris en charge.

Ne comptez pas sur les Repères MCP pour les cartes montées par un plugin, les mondes non enregistrés, transitoires, de prévisualisation ou PIE/runtime, les régions World Partition spécialisées non chargées, les ancres suivant un Actor ou externes, le comportement propre aux Data Layers, les Level Instances, les sous-niveaux de streaming traditionnels ou la récupération après renommage/redirection d’un monde. Ces contextes sont en dehors de la base actuellement prise en charge.

Un seul client à la fois

Locus autorise une session client autorisée active et exécute les appels d’outils un par un. Si un autre client possède la session, un second client peut être refusé ou affiché comme occupé jusqu’à la fin ou l’expiration de la session active.

Fermez ou déconnectez d’abord l’ancien client, attendez brièvement s’il a été interrompu, puis réessayez. Si cela ne libère pas la session, utilisez Troubleshooting > Reset Active Client dans MCP Integration. Désactivez et réactivez MCP uniquement si nécessaire pour récupérer le serveur local.

Déconnecter ou désactiver MCP

Déconnectez le client lorsque vous avez terminé. Pour arrêter complètement l’accès MCP Locus, désactivez Enable MCP. Désactiver MCP ne supprime ni votre contenu Locus ni l’identifiant local ; cela arrête seulement le point de terminaison local jusqu’à sa réactivation.

Résoudre un problème de connexion

Symptôme	Action
MCP est désactivé ou aucun point de terminaison n’est disponible	Gardez Unreal Editor ouvert, ouvrez MCP Integration, activez Enable MCP et attendez un statut en cours d’exécution.
Le client rejette la connexion ou l’identifiant	Copiez une configuration récente. Faites-le après avoir changé le port local ou régénéré l’identifiant ; les anciennes configurations copiées ne fonctionneront plus.
Un autre client est actif ou Locus est occupé	Fermez l’autre client, attendez brièvement et réessayez. Utilisez Reset Active Client uniquement lorsque ce client n’est plus utilisé. Attendez la fin d’une opération Locus en cours avant de retenter un appel d’outil.
Un client ne peut pas modifier le contenu	Autoriser les modifications est désactivé. Activez-le seulement pour les changements Locus pris en charge que vous voulez autoriser.
Les Notes ou Repères privés sont refusés	Activez séparément Autoriser les Notes et Repères Privés. Autoriser les modifications seul n’accorde pas l’accès Privé.
Une requête de Repère signale un contexte de monde non pris en charge	Utilisez un monde `/Game/...` enregistré et appartenant au projet, ou revenez au workflow de l’Editor Locus. Voir Repères pour les exigences normales du viewport.
Unreal Editor a redémarré	Rouvrez le projet et reconnectez le client. Copiez une configuration récente si le statut affiche un autre point de terminaison ou identifiant.

Pour les problèmes Locus généraux, voir Résolution des problèmes. Pour le reste de la surface des paramètres Locus, voir Paramètres.