Integração MCP

A Integração MCP do Locus permite que um cliente MCP compatível trabalhe com Notas, Documentos, Pins, contexto atual do Editor e status do Locus compatíveis enquanto o Unreal Editor estiver em execução. Ela é opcional e desabilitada por padrão.

O Locus não inclui um assistente de IA autônomo. Seu cliente MCP conectado executa o fluxo de IA e decide quando usar as ferramentas compatíveis do Locus.

Antes de conectar

Você precisa de:

• Unreal Editor aberto com o Locus habilitado para o projeto;
• MCP Integration habilitada nas configurações do Locus;
• um cliente MCP compatível em execução na mesma máquina.

O endpoint do Locus é local ao seu computador. O Locus não declara compatibilidade com todos os clientes MCP nem com todas as versões futuras de clientes. Ele oferece predefinições de integração para OpenAI Codex, Claude Code e Gemini CLI, além de uma opção genérica para outros clientes MCP Streamable HTTP compatíveis. Essas predefinições configuram o mesmo servidor MCP do Locus e as mesmas 20 ferramentas; não são integrações de IA separadas.

A validação final do Locus 1.3 usou o Codex CLI 0.160.0. Validações anteriores de lançamento do Locus também cobriram Claude Code 2.1.228 e Gemini CLI 0.55.1. Trate-as como versões testadas, não como garantias permanentes de compatibilidade.

Conectar um cliente

1. No Unreal Editor, abra Editor Preferences > Plugins > Locus e depois MCP Integration.
2. Ative Enable MCP e aguarde o status mostrar Running - waiting for client.
3. Em Connection, escolha o Formato do Cliente adequado: OpenAI Codex, Claude Code, Gemini CLI ou Generic Streamable HTTP MCP.
4. Selecione Copiar Configuração.
5. Cole a configuração copiada no local ou fluxo normal de configuração do cliente MCP e conecte-o.
6. Retorne ao Locus e confirme que o status mostra Client connected.

A configuração copiada é a fonte de verdade do endpoint e da credencial atuais. Não escreva uma configuração de conexão manualmente, a menos que o cliente exija um formato que o Locus não ofereça.

OpenAI Codex

Para o Codex, escolha OpenAI Codex e use Copiar Configuração. Adicione o TOML copiado ao Codex pelo fluxo normal de configuração MCP e recarregue ou reinicie o Codex se isso for necessário antes da conexão. Confirme o servidor Locus na lista de servidores MCP do Codex. Para Unreal Engine 5.8, consulte a seção Usar o Locus com Unreal MCP no Unreal Engine 5.8.

Claude Code

Para o Claude Code, o Locus copia o comando oficial de registro HTTP MCP com escopo local do projeto e privado do usuário. Execute o comando copiado em um terminal normal. Ele não cria um .mcp.json compartilhado do projeto contendo credenciais.

Gemini CLI

Para o Gemini CLI, o Locus copia o comando oficial de registro HTTP MCP com --scope user. Isso armazena a entrada do servidor e a credencial local na configuração privada do Gemini do usuário, em vez de gerar um .gemini/settings.json do projeto que poderia entrar no controle de código-fonte. A contrapartida é que a entrada do Locus fica disponível para esse usuário em todos os projetos; copie uma configuração nova ao trocar para um projeto com endpoint ou credencial ativa diferente.

O Locus não adiciona a opção --trust do Gemini. A política normal de confirmação de ferramentas do Gemini continua em vigor.

Generic Streamable HTTP MCP

Escolha Generic Streamable HTTP MCP quando um cliente compatível precisar do endpoint e do cabeçalho Authorization, em vez de um formato específico de cliente. Siga as orientações de configuração privada desse cliente e use marcadores como Bearer <LOCAL_LOCUS_CREDENTIAL> em notas ou exemplos que você guardar.

Usar o Locus com Unreal MCP no Unreal Engine 5.8

O Unreal MCP integrado do Unreal Engine 5.8 e o Locus MCP podem ser executados lado a lado como servidores MCP independentes. O Locus não depende do Unreal MCP.

A configuração verificada abaixo usa o Codex. É um exemplo específico do cliente, não uma afirmação de que esse recurso de servidores independentes seja exclusivo do Codex.

Exemplo do Codex

Configurar os dois servidores

1. No Unreal Engine 5.8, habilite Unreal MCP, All Toolsets, Terminal e Locus. Verifique se o servidor Unreal MCP está habilitado e configurado para iniciar automaticamente.

2. No console do Unreal, execute:

   ModelContextProtocol.GenerateClientConfig Codex

   O Unreal gera a configuração do Codex em:

   <Project>/.codex/config.toml

3. No Unreal, abra Editor Preferences > Plugins > Locus > MCP Integration. Habilite o servidor MCP do Locus e selecione Copy Connection Configuration > OpenAI Codex (config.toml).

4. Cole o bloco MCP do Locus gerado abaixo da configuração MCP gerada pelo Unreal em <Project>/.codex/config.toml. Não recrie manualmente URLs, cabeçalhos ou credenciais do Locus; o bloco copiado é a configuração de conexão atual.

O arquivo deve conter as duas entradas de servidor MCP:

unreal-mcp
locus

Mantenha a configuração do Codex privada

O bloco Locus gerado pode conter uma credencial Bearer local. Não faça commit de <Project>/.codex/config.toml no controle de código-fonte quando ele contiver credenciais.

Iniciar o Codex e verificar a conexão

Abra o Terminal do Unreal Engine na raiz do projeto e execute:

codex

Peça ao Codex para verificar os servidores MCP disponíveis:

Check which MCP servers are available to you.

Ele deve listar unreal-mcp e locus. Em seguida, teste cada integração separadamente:

Use Unreal MCP to inspect my currently selected actor.

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

Manter a conexão local e privada

O Locus escuta apenas na interface de loopback local, portanto o endpoint MCP fica disponível somente na mesma máquina. Uma credencial bearer local gerada para o usuário autentica o cliente.

Copiar Configuração é a ação explícita que produz texto contendo a credencial. Trate a configuração copiada como sensível e cole-a somente em um cliente confiável. Não a inclua em documentação, relatórios de problemas, capturas de tela, mensagens de chat ou configurações sob controle de código-fonte. O Locus não exibe intencionalmente a credencial nas Configurações nem a grava nos logs. Se acreditar que ela foi exposta, use Advanced > Regenerate Credential… e copie uma configuração nova para o cliente.

Desativar Enable MCP interrompe o acesso MCP do Locus. Fechar o Unreal Editor também encerra o endpoint MCP ativo do Locus. Para o limite de privacidade mais amplo do conteúdo local e de clientes externos, consulte Privacidade e feedback.

Escolher permissões deliberadamente

Configuração	O que permite
Somente Leitura	O padrão. Clientes podem usar operações de leitura compatíveis, mas operações de alteração compatíveis são negadas. O resumo de status mostra ReadOnly quando Permitir Alterações está desativado.
Permitir Alterações	Habilita operações compatíveis de criação, atualização, arquivamento e comentário. Ative somente quando quiser que o cliente conectado altere conteúdo do Locus. Isso não concede alteração arbitrária do projeto Unreal.

Conteúdo Privado é protegido separadamente. Permitir Conteúdo Privado fica desativado por padrão, e nem habilitar MCP nem Permitir Alterações concede acesso automaticamente. Ative-o somente quando o cliente conectado precisar acessar Notas e Pins Privados locais. Documentos são sempre de propriedade do projeto e não têm escopo Privado.

Ao desativar Permitir Alterações ou Permitir Conteúdo Privado, as solicitações que ainda aguardavam sob a permissão mais ampla são canceladas. Alterações já concluídas não são desfeitas, e o cliente não precisa se reconectar.

O que os clientes podem fazer

O Locus expõe 20 ferramentas MCP. Elas são agrupadas pelo tipo de trabalho que apoiam, não pelos detalhes do protocolo MCP.

Grupo	Ferramentas	Trabalho compatível
Infraestrutura (2)	locus.get_status, locus.get_capabilities	Verificar status, permissões e recursos disponíveis do Locus.
Notas (6)	locus.list_notes, locus.get_note, locus.search_notes, locus.create_note, locus.update_note, locus.archive_note	Localizar, ler, criar, atualizar e arquivar Notas.
Documentos (5)	locus.list_documents, locus.get_document, locus.search_documents, locus.create_document, locus.update_document	Localizar, ler, criar e atualizar Documentos Markdown de propriedade do projeto. Renomear, mover e excluir não estão disponíveis pelo MCP.
Pins (5)	locus.list_pins, locus.get_pin, locus.create_pin, locus.update_pin, locus.add_pin_comment	Localizar, ler, criar, atualizar e comentar Pins. Excluir e arquivar Pins não estão disponíveis pelo MCP.
Contexto (2)	locus.search_context, locus.get_active_context	Pesquisar Notas, Pins e Documentos em conjunto e ler o contexto atual do Editor relevante para o Locus. Ambas são somente leitura.

Ferramentas de leitura continuam disponíveis em Somente Leitura. Ferramentas compatíveis de criar, atualizar, arquivar e comentar exigem Permitir Alterações. As proteções existentes do Locus, incluindo regras de controle de código-fonte e validação de conteúdo, continuam valendo.

Documentos criados pelo MCP seguem o mesmo fluxo de adição adiada dos Documentos criados no Editor: começam locais e Não rastreados. Organize, renomeie, mova ou edite-os no Locus e use explicitamente Marcar para Adição quando o caminho final estiver pronto. O MCP não oferece ferramentas para renomear, mover, excluir ou marcar Documentos para adição.

Ferramentas de contexto

Pesquisar em Notas, Pins e Documentos

locus.search_context é uma pesquisa somente leitura em Notas, Pins e Documentos em uma única chamada. É uma pesquisa direta no conteúdo existente do Locus, não uma IA nem um índice vetorial.

• Os resultados usam uma única ordem determinística para todos os tipos, sem pontuações de relevância.
• Filtros opcionais restringem o resultado por tipo (note, pin, document), escopo, tags (Notas e Pins) e mundo do Pin.
• Documentos correspondem por título e caminho, não pelo corpo do Documento.
• Cada resultado retorna metadados de resumo, como tipo, identidade, título, campos correspondentes e revisão. Os resultados nunca incluem corpos de Notas, descrições ou comentários de Pins nem o Markdown de Documentos; use a ferramenta get correspondente para ler um item.
• Notas e Pins Privados aparecem somente quando Permitir Conteúdo Privado está ativado.

Ler o contexto ativo do Editor

locus.get_active_context retorna um snapshot somente leitura do contexto atual do Editor relevante para o Locus. Dependendo do que estiver aberto e selecionado, ele pode incluir:

• o mundo salvo e, quando compatível, o nível atual;
• a Nota ativa, o Pin selecionado e o Documento ativo;
• os Actors selecionados e os assets selecionados.

Para a Nota, o Pin e o Documento ativos, o snapshot informa o título e a revisão persistidos e se há alterações não salvas. Ele nunca expõe o corpo ou o conteúdo de Documento não salvos. Quando Permitir Conteúdo Privado está desativado, uma Nota ou um Pin Privado ativo é indistinguível da ausência de um item ativo.

Raízes de apresentação dos Documentos

O MCP entende as mesmas duas raízes de apresentação mostradas no espaço de trabalho Documentos. Ambas são visões do único repositório <Project>/ProjectDocuments/:

• Documentos do Locus contém Documentos normais fora do mapeamento reservado Content/.... Um caminho de apresentação como Design/Combat.md tem o mesmo caminho autoritativo: Design/Combat.md.
• Content Browser contém Documentos Markdown projetados no contexto do Unreal Content Browser. Um caminho como Characters/Hero.md tem o caminho autoritativo Content/Characters/Hero.md e mapeia para o contexto /Game/Characters correspondente.

Documentos do Content Browser continuam sendo arquivos Markdown externos. Eles não são UAssets e /Game/... é contexto de apresentação, não identidade do Documento. O caminho Markdown normalizado relativo a ProjectDocuments continua autoritativo.

locus.list_documents e locus.search_documents aceitam um valor opcional presentationRoot de all, locusDocuments ou contentBrowser; quando omitido, o padrão é all. A filtragem continua fazendo parte da operação indexada de lista/pesquisa e mantém a ordenação e paginação existentes.

locus.create_document aceita locusDocuments ou contentBrowser quando o chamador quer escolher explicitamente uma raiz visível. Nesse modo, relativePath é relativo à raiz selecionada:

presentationRoot	relativePath fornecido	Caminho autoritativo criado
locusDocuments	Design/Combat.md	Design/Combat.md
contentBrowser	Characters/Hero.md	Content/Characters/Hero.md

Não adicione Content/ ao criar explicitamente em contentBrowser; o Locus aplica o mapeamento reservado uma vez. Chamadores existentes que omitem presentationRoot mantêm o contrato anterior de caminho autoritativo; portanto, uma entrada legada Content/Characters/Hero.md conserva seu significado.

Os resultados do Documento distinguem:

• relativePath: identidade autoritativa normalizada sob ProjectDocuments;
• presentationRoot: locusDocuments ou contentBrowser;
• presentationPath: caminho visível sob essa raiz de apresentação.

Os campos de raiz fornecem contexto; não introduzem outro repositório ou identificador de Documento.

locus.archive_note altera o estado de ciclo de vida de uma Nota para Archived; não move a Nota para um painel Archived separado. O Locus mantém Notas arquivadas visíveis no espaço de trabalho normal de Notas e não tem um fluxo dedicado de Archive/Restore no Editor nem uma ferramenta locus.restore_note. Para retornar uma Nota ao estado Open pelo MCP, use locus.update_note com a revisão atual e status: "open".

Suporte a mundos para Pins

A base compatível de Pins é um mundo /Game/... salvo e de propriedade do projeto, com identidade explícita do mundo e posição no espaço do mundo Unreal. O trabalho básico com Pins de World Partition salvo e de propriedade do projeto é compatível.

locus.create_pin sempre cria Pins do nível persistente. A propriedade por subníveis de streaming clássicos é atribuída somente pela colocação do Locus no Editor; consulte Pins.

Não dependa de Pins do MCP para mapas montados por plugins; mundos não salvos, transitórios, de visualização ou PIE/runtime; regiões especializadas descarregadas de World Partition; âncoras que acompanham Actors ou atores externos; comportamento específico de Data Layers; Level Instances; ou recuperação após renomear/redirecionar o mundo. Esses contextos estão fora da base compatível atual.

Um cliente por vez

O Locus permite uma sessão de cliente autorizado ativo e conclui chamadas de ferramentas uma por vez. Se outro cliente possuir a sessão, um segundo cliente poderá ser rejeitado ou aparecer como ocupado até a sessão ativa terminar ou expirar.

Feche ou desconecte o cliente anterior primeiro, aguarde brevemente se ele foi interrompido e tente novamente. Se isso não liberar a sessão, use Troubleshooting > Reset Active Client em Integração MCP. Desabilite e habilite novamente o MCP somente quando for necessário recuperar o servidor local.

Desconectar ou desabilitar MCP

Desconecte o cliente quando terminar. Para interromper totalmente o acesso MCP do Locus, desative Enable MCP. Desabilitar o MCP não exclui o conteúdo do Locus nem a credencial local; apenas interrompe o endpoint local até que você o habilite novamente.

Solucionar problemas de conexão

Sintoma	O que fazer
MCP está desabilitado ou não há endpoint	Mantenha o Unreal Editor aberto, abra MCP Integration, ative Enable MCP e aguarde um status em execução.
O cliente rejeita a conexão ou a credencial	Copie uma configuração nova. Faça isso depois de alterar a porta local ou regenerar a credencial; configurações copiadas antigas não funcionarão.
Outro cliente está ativo ou o Locus está ocupado	Feche o outro cliente, aguarde brevemente e tente novamente. Use Reset Active Client somente quando esse cliente não estiver mais em uso. Aguarde uma operação do Locus terminar antes de repetir a chamada.
Um cliente não consegue alterar conteúdo	Permitir Alterações está desativado. Habilite-o somente para as alterações compatíveis do Locus que você pretende permitir.
Notas ou Pins Privados são negados	Habilite Permitir Conteúdo Privado separadamente. Permitir Alterações sozinho não concede acesso Privado.
Uma solicitação de Pin informa um contexto de mundo não compatível	Use um mundo /Game/... salvo e de propriedade do projeto ou retorne ao fluxo do Editor Locus. Consulte Pins para requisitos normais do viewport.
O Unreal Editor foi reiniciado	Reabra o projeto e reconecte o cliente. Copie uma configuração nova se o status mostrar endpoint ou credencial diferente.

Para problemas gerais do Locus, consulte Solução de problemas. Para o restante das configurações do Locus, consulte Configurações.