Integrazione MCP

L’Integrazione MCP di Locus consente a un client MCP compatibile di lavorare con Note, Documenti, Pin e stato Locus supportati mentre Unreal Editor è in esecuzione. È facoltativa e disabilitata per impostazione predefinita.

Locus non include un assistente AI autonomo. Il client MCP connesso esegue il flusso AI e decide quando usare gli strumenti Locus supportati.

Prima di collegarti

Servono:

Unreal Editor aperto con Locus abilitato per il progetto;
MCP Integration abilitata nelle impostazioni Locus;
un client MCP compatibile in esecuzione sulla stessa macchina.

L’endpoint Locus è locale al computer. Locus non dichiara compatibilità con ogni client MCP o con ogni versione futura del client. Offre preset di onboarding per OpenAI Codex, Claude Code e Gemini CLI, oltre a un’opzione generica per altri client MCP Streamable HTTP compatibili. I preset configurano lo stesso server MCP Locus e gli stessi 18 strumenti; non sono integrazioni AI separate.

La validazione di rilascio con client reali ha usato Codex CLI 0.147.0, Claude Code 2.1.228 e Gemini CLI 0.55.1. Considerali versioni testate, non garanzie di compatibilità permanenti.

Collega un client

In Unreal Editor apri Editor Preferences > Plugins > Locus, quindi MCP Integration.
Attiva Enable MCP e attendi che lo stato mostri Running - waiting for client.
In Connection, scegli il Formato client appropriato: OpenAI Codex, Claude Code, Gemini CLI o Generic Streamable HTTP MCP.
Seleziona Copia configurazione.
Incolla la configurazione copiata nella posizione di configurazione o nella procedura normale del client MCP, quindi connettilo.
Torna a Locus e verifica che lo stato mostri Client connected.

La configurazione copiata è il riferimento per endpoint e credenziale correnti. Non scrivere a mano una configurazione di connessione, a meno che il client richieda un formato che Locus non offre.

OpenAI Codex

Per Codex scegli OpenAI Codex e usa Copia configurazione. Aggiungi il TOML copiato a Codex tramite il normale flusso MCP, quindi ricarica o riavvia Codex se necessario prima della connessione. Conferma il server Locus nell’elenco dei server MCP di Codex. Per Unreal Engine 5.8, consulta la sezione Usare Locus con Unreal MCP in Unreal Engine 5.8.

Claude Code

Per Claude Code, Locus copia il comando ufficiale di registrazione HTTP MCP con ambito locale al progetto e privato dell’utente. Esegui il comando copiato in un normale terminale. Non crea un .mcp.json condiviso nel progetto contenente credenziali.

Gemini CLI

Per Gemini CLI, Locus copia il comando ufficiale di registrazione HTTP MCP con --scope user. Questo memorizza la voce server e la credenziale locale nella configurazione privata Gemini dell’utente invece di generare un .gemini/settings.json di progetto che potrebbe entrare nel controllo del codice sorgente. Il compromesso è che la voce Locus è disponibile per quell’utente in tutti i progetti; copia una configurazione nuova quando passi a un progetto con endpoint o credenziale attivi diversi.

Locus non aggiunge l’opzione --trust di Gemini. La normale policy di conferma degli strumenti di Gemini resta attiva.

Generic Streamable HTTP MCP

Scegli Generic Streamable HTTP MCP quando un client compatibile ha bisogno di endpoint e header Authorization invece di uno dei formati specifici supportati. Segui le indicazioni di configurazione privata del client e usa segnaposto come Bearer <LOCAL_LOCUS_CREDENTIAL> in eventuali note o esempi conservati.

Usare Locus con Unreal MCP in Unreal Engine 5.8

Unreal MCP integrato in Unreal Engine 5.8 e Locus MCP possono essere eseguiti fianco a fianco come server MCP indipendenti. Locus non dipende da Unreal MCP.

La configurazione verificata riportata sotto usa Codex. È un esempio specifico del client, non un’affermazione che questa capacità di server indipendenti sia esclusiva di Codex.

Esempio Codex

Configurare entrambi i server

In Unreal Engine 5.8, abilita Unreal MCP, All Toolsets, Terminal e Locus. Verifica che il server Unreal MCP sia abilitato e impostato per l’avvio automatico.

Nella console di Unreal, esegui:

ModelContextProtocol.GenerateClientConfig Codex

Unreal genera la configurazione Codex in:

<Project>/.codex/config.toml

In Unreal, apri Editor Preferences > Plugins > Locus > MCP Integration. Abilita il server MCP di Locus, quindi seleziona Copy Connection Configuration > OpenAI Codex (config.toml).
Incolla il blocco MCP Locus generato sotto la configurazione MCP generata da Unreal in <Project>/.codex/config.toml. Non ricreare manualmente URL, intestazioni o credenziali Locus; il blocco copiato è la configurazione di connessione corrente.

Il file deve contenere entrambe le voci del server MCP:

unreal-mcp
locus

Avviare Codex e verificare la connessione

Apri il Terminale di Unreal Engine nella radice del progetto ed esegui:

codex

Chiedi a Codex di controllare i server MCP disponibili:

Check which MCP servers are available to you.

Dovrebbe elencare unreal-mcp e locus. Quindi prova ogni integrazione separatamente:

Use Unreal MCP to inspect my currently selected actor.

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

Mantieni la connessione locale e privata

Locus ascolta solo sull’interfaccia loopback locale, quindi l’endpoint MCP è disponibile solo sulla stessa macchina. Una credenziale bearer locale generata per l’utente autentica il client.

Copia configurazione è l’azione esplicita che produce testo contenente la credenziale. Tratta la configurazione copiata come sensibile e incollala solo in un client affidabile. Non includerla in documentazione, report di problemi, screenshot, messaggi chat o configurazioni sotto controllo del codice sorgente. Locus non mostra intenzionalmente la credenziale nelle Impostazioni e non la emette nei log. Se ritieni che sia stata esposta, usa Advanced > Regenerate Credential…, quindi copia una configurazione nuova nel client.

Disattivare Enable MCP interrompe l’accesso Locus MCP. Anche la chiusura di Unreal Editor termina l’endpoint MCP Locus attivo. Per il confine privacy più ampio dei contenuti locali e dei client esterni, vedi Privacy e feedback.

Scegli le autorizzazioni deliberatamente

Impostazione	Cosa consente
Sola lettura	Predefinita. I client possono usare operazioni di lettura supportate, ma le operazioni di modifica supportate vengono negate. Il riepilogo mostra `ReadOnly` quando Consenti modifiche è disattivato.
Consenti modifiche	Abilita le operazioni supportate di creazione, aggiornamento, archiviazione e commento. Attivalo solo quando vuoi che il client connesso modifichi contenuti Locus. Non concede modifiche arbitrarie al progetto Unreal.

Il contenuto Privato è protetto separatamente. Consenti note e Pin Privati è disattivato per impostazione predefinita e né l’attivazione di MCP né Consenti modifiche lo concede automaticamente. Attivalo solo quando il client deve accedere a Note e Pin privati locali. I Documenti sono sempre di proprietà del progetto e non hanno ambito Privato.

Cosa possono fare i client

Locus espone 18 strumenti MCP. Sono raggruppati per tipo di lavoro supportato, non per dettagli del protocollo MCP.

Gruppo	Strumenti	Lavoro supportato
Infrastruttura (2)	`locus.get_status`, `locus.get_capabilities`	Controllare stato, autorizzazioni e capacità disponibili di Locus.
Note (6)	`locus.list_notes`, `locus.get_note`, `locus.search_notes`, `locus.create_note`, `locus.update_note`, `locus.archive_note`	Trovare, leggere, creare, aggiornare e archiviare Note.
Documenti (5)	`locus.list_documents`, `locus.get_document`, `locus.search_documents`, `locus.create_document`, `locus.update_document`	Trovare, leggere, creare e aggiornare Documenti Markdown di proprietà del progetto. Rinomina, spostamento ed eliminazione non sono disponibili via MCP.
Pin (5)	`locus.list_pins`, `locus.get_pin`, `locus.create_pin`, `locus.update_pin`, `locus.add_pin_comment`	Trovare, leggere, creare, aggiornare e commentare Pin. Eliminazione e archiviazione dei Pin non sono disponibili via MCP.

Gli strumenti di lettura restano disponibili in Sola lettura. Gli strumenti supportati di creazione, aggiornamento, archiviazione e commento richiedono Consenti modifiche. Le protezioni Locus esistenti, incluse le regole di controllo del codice sorgente e validazione contenuti, continuano ad applicarsi.

I Documenti creati tramite MCP seguono lo stesso flusso di aggiunta differita dei Documenti creati nell’Editor: iniziano locali e Non tracciati. Organizzali, rinominali, spostali o modificali in Locus, poi usa esplicitamente Contrassegna per l’aggiunta quando il percorso finale è pronto. MCP non offre strumenti per rinominare, spostare, eliminare o contrassegnare per l’aggiunta i Documenti.

Radici di presentazione dei Documenti

MCP comprende le stesse due radici di presentazione mostrate nel area di lavoro Documenti. Entrambe sono viste dello stesso repository <Project>/ProjectDocuments/:

Documenti Locus contiene Documenti normali fuori dalla mappatura riservata Content/.... Un percorso di presentazione come Design/Combat.md ha lo stesso percorso canonico: Design/Combat.md.
Content Browser contiene Documenti Markdown proiettati nel contesto Unreal Content Browser. Un percorso come Characters/Hero.md ha il percorso canonico Content/Characters/Hero.md e si mappa sul contesto /Game/Characters corrispondente.

I Documenti Content Browser restano file Markdown esterni. Non sono UAsset e /Game/... è contesto di presentazione, non identità del Documento. Il percorso Markdown normalizzato relativo a ProjectDocuments resta l’identità canonica.

locus.list_documents e locus.search_documents accettano un valore opzionale presentationRoot pari a all, locusDocuments o contentBrowser; se omesso, il default è all. Il filtraggio resta parte dell’operazione indicizzata di lista/ricerca e mantiene ordinamento e paginazione esistenti.

locus.create_document accetta locusDocuments o contentBrowser quando il chiamante vuole scegliere esplicitamente una radice visibile. In quel caso relativePath è relativo alla radice selezionata:

`presentationRoot`	`relativePath` fornito	Percorso canonico creato
`locusDocuments`	`Design/Combat.md`	`Design/Combat.md`
`contentBrowser`	`Characters/Hero.md`	`Content/Characters/Hero.md`

Non anteporre Content/ durante la creazione esplicita sotto contentBrowser; Locus applica una volta la mappatura riservata. I chiamanti esistenti che omettono presentationRoot mantengono il precedente contratto del percorso canonico, quindi un input legacy Content/Characters/Hero.md conserva il significato esistente.

I risultati Documento distinguono:

relativePath: identità canonica normalizzata sotto ProjectDocuments;
presentationRoot: locusDocuments o contentBrowser;
presentationPath: percorso visibile sotto quella radice di presentazione.

I campi root forniscono contesto; non introducono un altro repository o identificatore Documento.

locus.archive_note porta lo stato di ciclo di vita di una Nota ad Archived; non sposta la Nota in un pannello Archived separato. Locus 1.0 mantiene le Note archiviate visibili nel area di lavoro Note normale e non ha un flusso Editor Archive/Restore dedicato né uno strumento locus.restore_note. Per riportare una Nota allo stato Open tramite MCP, usa locus.update_note con la revisione corrente e status: "open".

Supporto dei mondi per i Pin

La baseline Pin supportata è un mondo /Game/... salvato e di proprietà del progetto con identità esplicita del mondo e posizione nello spazio del mondo Unreal. È supportato il lavoro di base su Pin World Partition salvati e di proprietà del progetto.

Non affidarti ai Pin MCP per mappe montate da plugin; mondi non salvati, transitori, di anteprima o PIE/runtime; regioni World Partition specializzate non caricate; ancore che seguono Actor o attori esterni; comportamento specifico dei Data Layer; Level Instance; sottolivelli di streaming tradizionali; o recupero dopo rinomina/redirect del mondo. Questi contesti sono fuori dalla baseline supportata corrente.

Un client alla volta

Locus consente una sessione client autorizzata attiva e completa le chiamate agli strumenti una alla volta. Se un altro client possiede la sessione, un secondo client può essere rifiutato o mostrato occupato finché la sessione attiva non termina o scade.

Chiudi o disconnetti prima il client precedente, attendi brevemente se è stato interrotto, quindi riprova. Se non libera la sessione, usa Troubleshooting > Reset Active Client in Integrazione MCP. Disabilita e riabilita MCP solo quando è necessario recuperare il server locale.

Disconnettere o disabilitare MCP

Disconnetti il client quando hai terminato. Per fermare completamente l’accesso Locus MCP, disabilita Enable MCP. Disabilitare MCP non elimina contenuti Locus o la credenziale locale; arresta solo l’endpoint locale finché non lo riabiliti.

Risolvere un problema di connessione

Sintomo	Cosa fare
MCP è disabilitato o non esiste un endpoint	Tieni aperto Unreal Editor, apri MCP Integration, attiva Enable MCP e attendi lo stato in esecuzione.
Il client rifiuta connessione o credenziale	Copia una configurazione nuova. Fallo dopo aver cambiato la porta locale o rigenerato la credenziale; le configurazioni copiate precedenti non funzioneranno.
Un altro client è attivo o Locus è occupato	Chiudi l’altro client, attendi brevemente e riprova. Usa Reset Active Client solo quando quel client non è più in uso. Attendi il completamento di un’operazione Locus in corso prima di ritentare una chiamata.
Un client non può modificare il contenuto	Consenti modifiche è disattivato. Abilitalo solo per le modifiche Locus supportate che vuoi consentire.
Note o Pin Privati sono negati	Abilita separatamente Consenti note e Pin Privati. Consenti modifiche da solo non concede accesso Privato.
Una richiesta Pin segnala un contesto mondo non supportato	Usa un mondo `/Game/...` salvato e di proprietà del progetto oppure torna al flusso dell’Editor Locus. Vedi Pin per i requisiti normali del viewport.
Unreal Editor è stato riavviato	Riapri il progetto e riconnetti il client. Copia una configurazione nuova se lo stato mostra endpoint o credenziale diversi.

Per problemi Locus generali, vedi Risoluzione dei problemi. Per il resto della superficie Impostazioni Locus, vedi Impostazioni.