Godot-MCP

Godot MCP é um assistente de desenvolvimento de jogos com IA para o Godot Editor. Conecte Claude, Cursor, Copilot ou qualquer agente compatível com MCP ao Godot e deixe-o inspecionar e controlar seu projeto — criar nós, editar cenas, gerenciar recursos e scripts, capturar screenshots e muito mais.

Godot-MCP é a contraparte Godot do Unity-MCP: um addon de editor em C# que expõe operações do Godot Editor como Ferramentas de IA e as conecta a um servidor MCP através do mesmo backend hospedado em nuvem (ai-game.dev) que alimenta o Unity-MCP — ou seu próprio servidor auto-hospedado. A pilha MCP/reflexão não é um fork: ela é compartilhada com o Unity-MCP e consumida do nuget.org como PackageReferences.

💬 Entre no nosso servidor Discord — Tire dúvidas, mostre seu trabalho e conecte-se com outros desenvolvedores!

• ✔️ Agentes de IA — Use os melhores agentes da Anthropic, OpenAI, Google ou qualquer outro provedor sem ficar preso a um fornecedor
• ✔️ 42 ferramentas integradas — Uma ampla gama de Ferramentas MCP em 12 famílias para operar o Godot Editor
• ✔️ C# e GDScript — Leia, crie e atualize scripts .cs e .gd, e anexe-os a nós
• ✔️ Controle de Cenas e Nós — Construa e edite a árvore de cena, abra/salve cenas .tscn, altere recursos .tres/.res
• ✔️ Feedback visual — Capture screenshots do viewport, câmera e nós isolados que o LLM pode inspecionar
• ✔️ Válvula de escape por reflexão — Encontre e chame qualquer método C# em assemblies carregados via ReflectorNet
• ✔️ Nuvem ou auto-hospedado — Conecte-se ao ai-game.dev imediatamente, ou aponte para seu próprio servidor
• ✔️ Conversa natural — Converse com a IA como faria com um humano

Início Rápido

Comece a usar a partir de um terminal com o godot-cli (o análogo Godot do unity-mcp-cli) — sem necessidade de copiar arquivos manualmente ou editar o csproj:

# 1. Install godot-cli
npm install -g godot-cli

# 2. (Optional) Scaffold a fresh Godot C# project — skip if you already have one
godot-cli create-project --dotnet ./MyGodotProject

# 3. Install the godot_mcp addon: downloads addons/godot_mcp/ from the matching
#    GitHub release, adds the required NuGet packages + the extension-catalog
#    EmbeddedResource to your .csproj, and enables the plugin in project.godot —
#    all idempotently
godot-cli install-plugin ./MyGodotProject

# 4. Sign in to the ai-game.dev cloud — OAuth 2.1 device login (opens a browser,
#    saves a machine-wide credential the editor plugin auto-adopts; no token to copy)
godot-cli login

# 5. Pick an AI agent (Claude Code, Cursor, Copilot, …) and write its MCP config —
#    pinned to THIS project's cloud route by default (pass --no-pin for the bare URL)
godot-cli setup-mcp claude-code ./MyGodotProject

# 6. Open the Godot editor — builds the C# assembly first (so the addon loads on
#    the very first open) then auto-connects with the right GODOT_MCP_* env vars
godot-cli open ./MyGodotProject

# 7. Wait until the plugin answers the readiness probe
godot-cli wait-for-ready ./MyGodotProject

É isso. Peça à sua IA "Crie 3 cubos em um círculo com raio 2" e veja acontecer. ✨

Instalação offline / dev: install-plugin --source <path-to>/addons/godot_mcp copia o addon de um diretório local em vez de baixá-lo. Prefira a versão de release correspondente com install-plugin --version <x.y.z> se precisar de um build específico do addon. O caminho manual (copiar o addon + adicionar os pacotes NuGet você mesmo) ainda está documentado em Instalação Passos 1–2 para os fluxos da Biblioteca de Assets / gerenciados manualmente.

Veja a documentação completa da CLI para todos os comandos, ordem de resolução do editor e variáveis de ambiente de conexão.

Conteúdo

• Início Rápido
• Referência de Ferramentas
• Requisitos
• Instalação
  • Passo 1: Adicione o addon
    • Opção A — Biblioteca de Assets do Godot (recomendada)
    • Opção B — zip do GitHub Release
    • Opção C — copiar do código-fonte
  • Passo 2: Adicione os pacotes NuGet
  • Passo 3: Instale um agente de IA
• Conectar
  • Modo nuvem (padrão) — ai-game.dev
  • Modo personalizado — seu próprio servidor
• Configuração do MCP Server do Godot
  • Servidor local — deixe o addon baixar e executá-lo para você
  • Compile e execute o servidor manualmente (avançado)
• Personalizar Ferramentas
• Uso em tempo de execução (no jogo)
  • Capturando erros de tempo de execução no jogo
  • Exemplo: uma ferramenta de estado de jogo ao vivo
  • De onde vêm a URL do servidor e o token
  • Segurança: somente opt-in, desligado por padrão
• Como Funciona a Arquitetura do Godot MCP
• Compilação e contribuição
• Licença

Referência de Ferramentas

Godot-MCP inclui 42 ferramentas integradas agrupadas em 12 famílias. Os nomes das ferramentas espelham o Unity-MCP quando faz sentido (scene-*, node-*, …). Cada ferramenta retorna um resultado estruturado, serializado via ReflectorNet (ou uma imagem PNG para screenshots). Todas as ferramentas do editor estão disponíveis imediatamente após o addon ser ativado — nenhuma configuração extra é necessária. A família runtime-errors é a exceção: ela expõe erros do jogo em execução e está DESLIGADA por padrão — ative com builder.WithRuntimeErrorCapture() (veja Capturando erros de tempo de execução no jogo).

Família	Ferramentas	O que faz
ping	ping	Sonda de prontidão leve — ecoa uma mensagem de volta, ou retorna pong. Verifica o caminho MCP de ponta a ponta (editor → SignalR → despacho de ferramentas). Ferramenta de sistema — acessível pela superfície HTTP /api/system-tools/ do servidor, não anunciada aos agentes de IA em tools/list.
node	node-find, node-create, node-modify, node-set-parent, node-reorder, node-duplicate, node-delete	Inspecione e edite a árvore de cena ativa (o análogo Godot dos GameObjects do Unity), acionando EditorInterface na thread principal. A ordem dos filhos — que é a ordem de layout em um VBoxContainer/HBoxContainer — é definível tanto na criação (node-create's index) quanto depois (node-reorder).
scene	scene-open, scene-save, scene-create, scene-list-opened, scene-get-data	Abra, salve, crie e inspecione cenas Godot (res://*.tscn PackedScenes) no editor.
resource	resource-find, resource-get-data, resource-modify, resource-create, resource-move, resource-delete	Encontre e altere recursos Godot (.tres/.res) através de ResourceLoader/ResourceSaver/EditorFileSystem, mantendo os sidecars .import consistentes.
filesystem	filesystem-list, filesystem-reimport	Navegue e reimporte a árvore res:// do projeto via índice EditorFileSystem do editor (tipos de arquivo + uids sem carregar recursos).
script	script-read, script-create, script-update, script-delete, script-attach-to-node, script-validate	CRUD em arquivos C# (.cs) e GDScript (.gd), além de anexar um script a um nó e validar GDScript.
screenshot	screenshot-viewport, screenshot-camera, screenshot-isolated	Capture o viewport do editor, uma câmera específica ou uma renderização de nó isolado, retornada como imagem PNG que o LLM pode inspecionar.
editor	editor-application-get-state, editor-application-set-state, editor-selection-get, editor-selection-set	Leia/controle o ciclo de execução e reprodução do editor (Godot inicia o jogo em um processo separado) e a seleção atual.
console	console-get-logs, console-clear-logs	Leia e limpe o coletor de logs do editor do plugin (GD.Print/GD.PushWarning/GD.PushError).
reflection	reflection-method-find, reflection-method-call	Encontre e chame métodos C# (estáticos/instância, públicos/privados) em todos os assemblies carregados via ReflectorNet — a válvula de escape independente de engine.
skills	godot-skill-create, godot-skill-generate	Crie uma nova ferramenta MCP como arquivo C# no projeto e regenere os arquivos SKILL.md a partir das ferramentas que o editor tem registradas atualmente. Ferramentas de sistema — acessíveis pela superfície HTTP /api/system-tools/ do servidor (como ping), não anunciadas aos agentes de IA em tools/list.
runtime-errors	runtime-errors-get, runtime-errors-clear	Consulte erros levantados dentro do jogo em execução (NÃO o editor) — erros de tempo de execução GDScript, push_error/push_warning, erros de shader e exceções C# não tratadas / Task não observadas, com backtraces GDScript de múltiplos frames no Godot 4.5+. DESLIGADO por padrão — ative com builder.WithRuntimeErrorCapture().

ping

• ping — Sonda de prontidão leve; ecoa uma mensagem de volta, ou retorna pong. Uma ferramenta de sistema: chame-a via /api/system-tools/ping (ou godot-cli run-system-tool ping); ela não é listada em tools/list.

node

• node-find — Encontre nós na árvore de cena ativa por caminho, tipo ou nome.
• node-create — Crie um novo nó sob um pai (opcionalmente instanciando uma sub-cena .tscn), opcionalmente em um index irmão específico (contagens negativas a partir do final).
• node-modify — Defina campos/propriedades em um ou mais nós.
• node-set-parent — Reparente nós dentro da árvore de cena.
• node-reorder — Mova um nó existente para uma posição diferente entre seus irmãos (Node.MoveChild) — a única maneira de reorganizar uma cena existente sem excluir e recriar.
• node-duplicate — Duplique nós juntamente com suas subárvores.
• node-delete — Exclua nós da cena ativa.

scene

• scene-open — Abra um res://*.tscn PackedScene no editor.
• scene-save — Salve uma cena aberta de volta em seu arquivo .tscn.
• scene-create — Crie um novo asset de cena no projeto.
• scene-list-opened — Liste as cenas atualmente abertas no editor.
• scene-get-data — Recupere os nós raiz / estrutura de uma cena.

resource

• resource-find — Pesquise no projeto por recursos (.tres/.res).
• resource-get-data — Leia os campos e propriedades serializados de um recurso.
• resource-modify — Modifique as propriedades de um recurso.
• resource-create — Crie um novo asset de recurso.
• resource-move — Mova / renomeie um recurso, mantendo os sidecars .import consistentes.
• resource-delete — Exclua um recurso do projeto.

filesystem

• filesystem-list — Navegue pela árvore res:// (tipos de arquivo + uids) via índice de arquivos do editor.
• filesystem-reimport — Reimporte arquivos no projeto.

script

• script-read — Leia um arquivo de script .cs / .gd.
• script-create — Crie um novo arquivo de script.
• script-update — Atualize o conteúdo de um arquivo de script existente.
• script-delete — Exclua um arquivo de script.
• script-attach-to-node — Anexe um script a um nó.
• script-validate — Valide arquivos GDScript (.gd) e retorne diagnósticos estruturados de parse/compilação.

screenshot

• screenshot-viewport — Capture o viewport do editor como PNG.
• screenshot-camera — Capture de uma câmera específica.
• screenshot-isolated — Renderize um nó isoladamente de um ângulo escolhido.

editor

• editor-application-get-state — Lê o estado de execução/aplicação do editor.
• editor-application-set-state — Inicia / interrompe o jogo em execução.
• editor-selection-get — Obtém a seleção atual do editor.
• editor-selection-set — Define a seleção atual do editor.

console

• console-get-logs — Lê os logs do editor coletados pelo plugin (com filtragem). Isso inclui os diagnósticos do ciclo de vida da conexão do plugin (conectar/desconectar, tempo limite de drenagem, salvar/carregar configuração, geração de habilidades, controle de desenvolvimento, dispatcher e avisos de captura em tempo de execução), que passam pelo mesmo destino de captura que seus logs de estrutura.
• console-clear-logs — Limpa o cache de logs coletados.

reflection

• reflection-method-find — Encontra métodos C# (incluindo privados) em todos os assemblies carregados.
• reflection-method-call — Chama qualquer método C# com parâmetros de entrada e obtém o resultado.

runtime-errors (no jogo; DESATIVADO por padrão — ative com builder.WithRuntimeErrorCapture())

• runtime-errors-get — Lê erros de tempo de execução capturados no jogo (mais antigos primeiro, página com os mais recentes mantidos); consulte apenas novos erros via sinceSequence. Retorna available:false quando a captura nunca foi ativada, para que uma lista vazia nunca seja confundida com saúde.
• runtime-errors-clear — Limpa o buffer de erros de tempo de execução capturados no jogo (uma operação sem efeito quando a captura não está ativada); o contador de sequência monotônico é preservado.

skills (ferramentas do sistema — servidas em /api/system-tools/, não anunciadas aos agentes de IA)

• godot-skill-create — Escreve um novo arquivo de ferramenta MCP C# (.cs) no projeto. A ferramenta se torna chamável após a reconstrução do projeto (Godot compila C# fora do processo).
• godot-skill-generate — Regenera cada SKILL.md a partir das ferramentas atualmente registradas no editor, na pasta de habilidades do agente de IA selecionado.

Requisitos

• Godot 4.3+ — a edição C# / .NET (mono). O csproj do addon fixa Godot.NET.Sdk/4.3.0 como seu piso mínimo; editores 4.x mais novos (4.4, 4.5) funcionam.
• .NET 8 SDK (net8.0).

[!IMPORTANT] Godot-MCP requer a compilação mono (C#/.NET) do Godot — a compilação padrão (somente GDScript) não pode compilar o addon.

Instalação

Há duas coisas para instalar: o addon (os arquivos do plugin) e os dois pacotes NuGet dos quais o C# do addon depende. O Godot compila cada .cs sob seu projeto em um único assembly, então o .csproj do seu projeto deve declarar as mesmas referências NuGet que o addon precisa — caso contrário, o C# do addon não compilará.

Etapa 1: Adicionar o addon

Escolha uma das seguintes maneiras para obter a pasta addons/godot_mcp/ em seu projeto C# do Godot.

Totalmente automatizado (recomendado para fluxos de trabalho de terminal): godot-cli install-plugin ./MyGodotProject faz tudo da Etapa 1 e Etapa 2 em um único comando — ele baixa addons/godot_mcp/ da versão GitHub correspondente, adiciona os dois pacotes NuGet e o <EmbeddedResource> do catálogo de extensões ao seu .csproj, e ativa o plugin em project.godot, de forma idempotente. Use --source <path>/addons/godot_mcp para instalar a partir de uma cópia local offline. As Opções manuais A–C abaixo permanecem para instalações no editor (Biblioteca de Assets) e gerenciadas manualmente.

Opção A — Biblioteca de Assets do Godot (recomendada)

O caminho mais fácil: instale diretamente de dentro do editor.

1. Abra a aba AssetLib no topo do editor Godot.
2. Pesquise por Godot-MCP e abra o asset.
3. Clique em Download e depois Install — o Godot descompacta o addon na pasta res://addons/godot_mcp/ do seu projeto.

A entrada da Biblioteca de Assets é publicada por versão e sempre aponta para uma versão marcada, então uma instalação no editor fornece um snapshot conhecido e bom do addon. (Veja a nota abaixo se a entrada ainda não estiver visível.)

Opção B — Zip da versão GitHub

Pegue o godot-mcp-addon-<version>.zip mais recente da página de Versões e extraia-o na raiz do seu projeto — o arquivo já contém addons/godot_mcp/..., então os arquivos caem em res://addons/godot_mcp/.

Opção C — Copiar do código-fonte

Copie a pasta addons/godot_mcp/ deste repositório (ou do seu clone) para o diretório addons/ do seu projeto manualmente.

---

Após os arquivos estarem no lugar (Opções A–C), ative o plugin: Projeto → Configurações do Projeto → Plugins → Godot-MCP → Ativar. (Se você usou o godot-cli install-plugin totalmente automatizado acima, o plugin já está ativado e os pacotes NuGet + o embed do catálogo de extensões já foram adicionados — pule direto para Etapa 3.) Em um carregamento bem-sucedido, o painel de Saída do editor imprime:

[Godot-MCP] plugin loaded

Disponibilidade da Biblioteca de Assets. A entrada AssetLib no editor (Opção A) aparece após a primeira submissão do mantenedor ser aprovada pelos moderadores da Biblioteca de Assets do Godot. Até lá, use a Opção B (zip da versão GitHub) ou a Opção C.

Etapa 2: Adicionar os pacotes NuGet + o embed do catálogo de extensões

Adicione ambos os PackageReferences e o <EmbeddedResource> do catálogo de extensões ao seu .csproj (use estas versões fixadas exatas — elas devem corresponder ao Godot-MCP.csproj do addon):

<ItemGroup>
  <PackageReference Include="com.IvanMurzak.ReflectorNet" Version="5.4.1" />
  <PackageReference Include="com.IvanMurzak.McpPlugin"   Version="8.6.0" />
</ItemGroup>

<!-- Embed the extension catalog so the Extensions panel populates (else it is EMPTY). -->
<ItemGroup>
  <EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
</ItemGroup>

Pacote	Versão	Função
com.IvanMurzak.ReflectorNet	5.4.1	Núcleo de reflexão / serialização
com.IvanMurzak.McpPlugin	8.6.0	Cliente do plugin MCP (puxa transitivamente McpPlugin.Common + ReflectorNet; carrega o módulo AgentConfig compartilhado)

O <EmbeddedResource> é tão necessário quanto as fixações NuGet: o registro de extensões puramente gerenciado do addon lê o catálogo em tempo de execução do editor via GetManifestResourceStream (sem res:// / fallback de sistema de arquivos), e como o addon é distribuído como código-fonte, seu próprio <EmbeddedResource> não é carregado para o seu projeto — então sem esta linha, seu painel de Extensões fica vazio. O LogicalName deve ser exatamente Godot-MCP.extensions.catalog.json para que o recurso seja resolvido de forma idêntica ao assembly do próprio addon.

Execute dotnet restore para que os pacotes caiam no seu cache NuGet e depois compile. Nenhuma cópia manual de DLL é necessária — em tempo de execução do editor, o resolvedor de assembly do addon localiza as DLLs na sua pasta global-packages do NuGet lendo o *.deps.json da compilação. (Se você preferir saída autocontida, defina <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies> para que as DLLs sejam copiadas ao lado do assembly do seu projeto.)

Etapa 3: Instalar um agente de IA

Escolha um único AI agent que você preferir — você não precisa instalar todos. Esta é sua principal janela de chat para se comunicar com o LLM.

• Claude Code (recomendado)
• Claude Desktop
• GitHub Copilot no VS Code
• Antigravity
• Cursor
• Qualquer outro agente compatível com MCP

Escreva a configuração do cliente MCP do agente com godot-cli setup-mcp <agent> ./MyGodotProject. Por padrão, ela aponta o cliente para a URL de nuvem fixada no projeto <host>/mcp/p/<pin>, então uma sessão de agente iniciada nesta pasta de projeto roteia para o editor deste projeto mesmo quando sua conta tem vários editores conectados; passe --no-pin para a URL <host>/mcp simples. No modo Nuvem, a configuração carrega a chave de projeto deste projeto (Authorization: Bearer agd_pk_…) — uma credencial sem expiração vinculada apenas a este projeto, criada com seu login de máquina; sem um login (ou com --oauth) a configuração é somente URL e o agente faz login com seu próprio OAuth. O botão Configurar do editor grava a mesma configuração. Veja a documentação da CLI para a lista completa de agentes suportados.

Conectar

O plugin se conecta a um servidor MCP em um de dois modos. O modo e sua URL / token podem ser definidos na configuração serializada ou substituídos na inicialização do processo com variáveis de ambiente (útil para CI, execuções headless e desenvolvimento local). Todos os nomes de variáveis são o análogo Godot do UNITY_MCP_* do Unity-MCP. O modo ativo sempre é recalculado a partir do ambiente, então uma substituição no nível do processo vence sobre a configuração serializada sem editar nenhum arquivo.

Modo Nuvem (padrão) — ai-game.dev

No modo Nuvem, o plugin se conecta ao backend hospedado em https://ai-game.dev (o caminho do hub /mcp é anexado automaticamente). Este é o connectionMode padrão.

Entre uma vez com godot-cli login. A autenticação em nuvem usa o fluxo de autorização de dispositivo OAuth 2.1 (RFC 8628): godot-cli login imprime um código de usuário curto, abre seu navegador e — após aprovação — salva uma credencial de nuvem no armazenamento compartilhado da máquina (~/.ai-game-dev/credentials.json) que o plugin do editor adota automaticamente, então godot-cli open conecta sem token para copiar ou colar. Nenhum token de acesso pessoal (PAT) é gerado. GODOT_MCP_TOKEN (abaixo) permanece disponível como uma substituição manual para CI / execuções headless.

Variável de ambiente	Finalidade	Padrão
GODOT_MCP_CONNECTION_MODE	Força o modo: Cloud ou Custom (sem diferenciar maiúsculas/minúsculas).	Cloud
GODOT_MCP_CLOUD_URL	Substitui a URL base da nuvem. Uma /mcp final é removida se presente; um valor não-http(s) volta ao padrão.	https://ai-game.dev
GODOT_MCP_TOKEN	Token Bearer, roteado para o token do modo ativo. Aspas ao redor são removidas.	(nenhum)

Modo Personalizado — seu próprio servidor

No modo Personalizado, o plugin se conecta a uma URL de servidor que você fornece (um servidor de desenvolvimento local, uma instância auto-hospedada, etc.).

Variável de ambiente	Finalidade	Padrão
GODOT_MCP_CONNECTION_MODE	Defina como Custom para selecionar este modo.	Cloud
GODOT_MCP_HOST	A URL do servidor personalizado. Deve ser uma URL http(s) absoluta ou volta ao padrão.	http://localhost:8080
GODOT_MCP_TOKEN	Token Bearer (necessário apenas se o servidor exigir autorização).	(nenhum)

Exemplo — inicie o editor apontando para um servidor local:

export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:5300
# export GODOT_MCP_TOKEN=...   # only if the server enforces auth

O comando godot-cli open encaminha essas variáveis de ambiente para você via flags --mode, --url, --cloud-url e --token.

Configuração do MCP Server Godot

No modo Nuvem, você não executa um servidor — o plugin fala com ai-game.dev. Se você quiser hospedar o servidor você mesmo (desenvolvimento local, CI ou sua própria nuvem), você tem duas opções: deixar o addon baixar e executar o binário do servidor correspondente para você (recomendado), ou executá-lo manualmente (avançado).

O servidor em si é o compartilhado, agnóstico de engine GameDev-MCP-Server — um binário de servidor (gamedev-mcp-server) servindo Unity-MCP, Godot-MCP e Unreal-MCP. Ele é lançado de seu próprio repositório em sua própria linha de versão; este addon fixa a versão do servidor que consome (a constante ServerVersion em addons/godot_mcp/Runtime/Connection/GodotMcpServerView.cs).

Servidor local — deixe o addon baixar & executá-lo para você

No modo Personalizado, o plugin pode hospedar seu próprio servidor MCP — você não precisa compilar ou iniciar nada manualmente. Abra o cartão Servidor do dock do addon enquanto o modo Personalizado está selecionado e use a linha Servidor local:

• Iniciar Servidor — baixa a compilação do servidor para a versão de servidor fixada (pinned), armazena em cache, inicia-o, e o plugin conecta-se a ele. Parar Servidor encerra-o (ele também é interrompido automaticamente quando você fecha o editor).
• O download é o asset de lançamento específico da plataforma gamedev-mcp-server-<rid>.zip — baixado somente via HTTPS de github.com, do lançamento do GameDev-MCP-Server marcado como v<ServerVersion>, portanto o URL do asset é: https://github.com/IvanMurzak/GameDev-MCP-Server/releases/download/v<ServerVersion>/gamedev-mcp-server-<rid>.zip. O <rid> (identificador de runtime da plataforma — ex.: win-x64, osx-arm64, linux-x64) é resolvido automaticamente para sua máquina; todos os sete RIDs publicados são suportados (win-x64/x86/arm64, linux-x64/arm64, osx-x64/arm64).
• O binário é armazenado em cache na pasta .godot/mcp-server/<rid>/ do seu projeto (ignorada pelo git) e reutilizado em execuções posteriores; ele só é baixado novamente quando a versão do servidor fixada muda (uma correspondência exata de versão, para que o plugin do editor e o servidor com o qual ele se comunica nunca fiquem dessincronizados). O servidor é iniciado na porta da sua URL do Servidor (padrão http://localhost:8080), pelo transporte streamableHttp.

Fixação de versão e segurança. O URL de download é derivado exclusivamente da constante ServerVersion fixada no addon e do RID da sua plataforma — não há execução de binário por URL arbitrário. A versão do addon e a versão do servidor são desacopladas: atualizar o servidor consumido é uma alteração explícita do addon (um novo ServerVersion), e o lançamento v<ServerVersion> fixado já deve existir no GameDev-MCP-Server antes de um lançamento do addon que o fixe. Se o asset do lançamento não puder ser obtido (você estiver offline), o addon registra um aviso e o servidor local simplesmente não inicia — recorra à execução manual abaixo ou use o modo Nuvem. O download é totalmente ignorado em CI (o ambiente CI / GITHUB_ACTIONS), onde nenhum servidor local é hospedado.

Isso espelha o fluxo de servidor auto-hospedado do Unity-MCP: o plugin do editor gerencia o binário do servidor fixado para você, em vez de exigir uma compilação manual.

Executar o servidor manualmente (avançado)

Para executar o servidor como um processo autônomo / em nuvem, baixe um binário do lançamento do GameDev-MCP-Server (ou use a imagem Docker aigamedeveloper/mcp-server). Ambos os transportes são suportados: streamableHttp (HTTP) e stdio.

# HTTP transport on port 8080
./gamedev-mcp-server --client-transport streamableHttp --port 8080

# stdio transport — for local MCP clients that launch the server directly
./gamedev-mcp-server --client-transport stdio

Em seguida, aponte o plugin para ele no modo Personalizado (GODOT_MCP_HOST=http://localhost:8080).

Escolhendo um transporte: use stdio quando o cliente MCP iniciar o binário do servidor diretamente (uso local — a configuração mais comum); use streamableHttp ao executar o servidor como um processo autônomo ou na nuvem e conectar-se via HTTP.

Consulte o README do GameDev-MCP-Server para a tabela completa de argumentos / variáveis de ambiente, a imagem Docker e a matriz de compilação multiplataforma.

Personalizar Ferramentas

O Godot-MCP suporta o desenvolvimento de MCP Tool personalizados diretamente no código do seu projeto. Uma família de ferramentas é um partial class decorado com [AiToolType]; cada método de ferramenta é decorado com [AiTool("tool-name", …)], com um [Description] no método e em cada parâmetro para ajudar o LLM a entendê-lo.

Qualquer chamada de API do Godot (Node, Resource, EditorInterface, …) deve ser executada na thread principal do editor — serialize-a por meio de MainThread.Instance.Run(...) (o MainThread do ReflectorNet é respaldado pelo despachante da thread principal do Godot na inicialização do plugin). Nunca toque em objetos do motor fora da thread.

[AiToolType]
public partial class Tool_MyFeature
{
    [AiTool("my-custom-task", Title = "Do a custom task")]
    [Description("Explain to the LLM what this does and when to call it.")]
    public string CustomTask
    (
        [Description("Explain to the LLM what this parameter is.")]
        string inputData
    )
    {
        // ... work that does not touch the Godot API can run on this background thread ...

        return MainThread.Instance.Run(() =>
        {
            // ... touch EditorInterface / Node / Resource here, on the main thread ...
            return "[Success] Operation completed.";
        });
    }
}

Retorne um modelo de dados estruturado (serializado pelo ReflectorNet) ou void para operações apenas com efeitos colaterais — nunca formate strings ad hoc para saída analisável. Use parâmetros string? optional = null (anuláveis + padrão) para marcá-los como opcionais para o LLM.

Uso em tempo de execução (no jogo)

Tudo acima executa a conexão MCP dentro do editor Godot (o [Tool] EditorPlugin o inicia para você). O Godot-MCP também pode ser executado dentro de uma compilação de jogo em execução / exportada (depuração ou lançamento) — o análogo no Godot do modo de tempo de execução do Unity-MCP. Isso permite que um LLM leia e conduza o estado do jogo ao vivo: imagine um jogo de Xadrez cuja lógica de bot você terceiriza para um LLM expondo algumas ferramentas.

Duas coisas tornam o modo de tempo de execução diferente do modo de editor, e ambas são deliberadas:

• Ele nunca se conecta automaticamente. O plugin do editor conecta-se na inicialização; uma compilação de jogo não. Você escreve o código de adesão e decide quando (se é que alguma vez) chamar Connect().
• Não há ferramentas, prompts ou recursos por padrão — estritamente manual. O tempo de execução inclui zero ferramentas MCP, prompts e recursos. Você registra cada ferramenta [AiToolType], prompt [AiPromptType], e recurso [AiResourceType] você mesmo, no seu próprio código — e cada tipo é independentemente opcional (registre prompts sem nenhuma ferramenta, ou vice-versa). (As famílias de ferramentas do editor do addon são limitadas por #if TOOLS e nem sequer compilam em uma compilação de jogo, portanto nunca podem vazar.)

O ponto de entrada é GodotMcpRuntime.Initialize(...) (namespace com.IvanMurzak.Godot.MCP.Runtime). Escreva-o uma vez — ex.: a partir do _Ready() de um autoload do Godot, para que um SceneTree exista:

using System.Reflection;
using com.IvanMurzak.Godot.MCP.Connection;   // GodotMcpConnectionMode
using com.IvanMurzak.Godot.MCP.Runtime;      // GodotMcpRuntime
using McpServerConsts = com.IvanMurzak.McpPlugin.Common.Consts.MCP.Server;   // AuthOption (none/oauth/token)
using Godot;

public partial class GameMcp : Node
{
    private GodotMcpRuntimeHandle? _mcp;

    public override async void _Ready()
    {
        // 1) Build the connection (default OFF — nothing connects yet).
        _mcp = GodotMcpRuntime.Initialize(builder =>
        {
            builder.WithConfig(config =>
            {
                config.ConnectionMode = GodotMcpConnectionMode.Custom;         // your own server
                config.Host           = "http://localhost:8080";               // prefer loopback
                config.AuthOption     = McpServerConsts.AuthOption.token;      // offline bearer-token auth
                config.Token          = "your-secret-token";
            });

            // 2) Opt YOUR tools / prompts / resources in. Zero of each by default — this is the only way
            //    they get registered, and each kind is independently optional.
            builder.WithToolsFromAssembly(Assembly.GetExecutingAssembly());     // [AiToolType] classes
            builder.WithPromptsFromAssembly(Assembly.GetExecutingAssembly());   // [AiPromptType] classes
            builder.WithResourcesFromAssembly(Assembly.GetExecutingAssembly()); // [AiResourceType] classes
            //   …or register specific families:
            //   builder.WithTools(typeof(GameMcpTools));
            //   builder.WithPrompts(typeof(GameMcpPrompts));
            //   builder.WithResources(typeof(GameMcpResources));
        }).Build();

        // 3) Connect — explicit, the security-required opt-in. Retries in the background while
        //    KeepConnected is true (the default).
        await _mcp.Connect();
    }

    public override async void _ExitTree()
    {
        // 4) Disconnect on shutdown (or whenever you want to stop exposing tools).
        if (_mcp is not null)
            await _mcp.Disconnect();
    }
}

Superfície do construtor (tudo fluente / encadeável):

Chamada	O que faz
GodotMcpRuntime.Initialize(configure)	Começa a configurar; retorna um GodotMcpRuntimeBuilder. configure pode ser null para o padrão de zero ferramentas, configurado por ambiente.
builder.WithConfig(Action<GodotMcpConfig>)	Define Host / Token / ConnectionMode / AuthOption no código. Várias chamadas compõem em ordem.
builder.WithToolsFromAssembly(Assembly)	Registra todas as classes [AiToolType] em um assembly (geralmente Assembly.GetExecutingAssembly()).
builder.WithTools(params Type[])	Registra classes [AiToolType] específicas quando uma varredura de assembly inteiro é ampla demais.
builder.WithPromptsFromAssembly(Assembly)	Registra todas as classes [AiPromptType] em um assembly. Independente de ferramentas/recursos.
builder.WithPrompts(params Type[])	Registra classes [AiPromptType] específicas.
builder.WithResourcesFromAssembly(Assembly)	Registra todas as classes [AiResourceType] em um assembly. Independente de ferramentas/prompts.
builder.WithResources(params Type[])	Registra classes [AiResourceType] específicas.
builder.WithoutMainThreadDispatcher()	Ignora a inicialização automática do despachante da thread principal (somente se você instalar seu próprio despachante autoload).
builder.WithRuntimeErrorCapture()	Captura erros levantados no jogo em execução (erros de tempo de execução do GDScript, push_error/push_warning, erros de shader via o hook do motor Godot 4.5+; exceções C# não tratadas / não observadas de Task com rastreamentos de pilha completos) e registra a ferramenta runtime-errors-* para que um agente possa consultá-los. Desligado por padrão. Consulte "Capturando erros de tempo de execução no jogo" abaixo.
builder.Build()	Finaliza; retorna um GodotMcpRuntimeHandle desligado por padrão.
handle.Connect() / handle.Disconnect()	Abre / fecha a conexão. handle.Dispose() o encerra no desligamento.

Initialize().Build() também garante um despachante da thread principal Node no SceneTree em execução (para que os manipuladores de ferramentas possam serializar chamadas de API do Godot na thread principal do motor), a menos que você opte por sair com WithoutMainThreadDispatcher(). Chame-o uma vez que um SceneTree esteja ativo (ex.: de um _Ready autoload).

Capturando erros de tempo de execução no jogo

No modo de editor, console-get-logs e script-validate exibem os logs do próprio plugin e erros de análise do GDScript. Mas erros levantados dentro de um jogo em execução — um erro de tempo de execução do GDScript (uma desreferência nula, um índice ruim), um push_error/push_warning, um erro de shader ou uma exceção C# não tratada — não são visíveis para um agente por meio dessas ferramentas do editor. Sem isso, um agente pode iniciar o jogo, consultar logs, ver silêncio e concluir erroneamente que o jogo está saudável. Essa é a lacuna que bloqueia um loop não supervisionado "continue corrigindo até não haver erros" para bugs reais de jogabilidade/tempo de execução.

Opte por participar com WithRuntimeErrorCapture():

_mcp = GodotMcpRuntime.Initialize(builder =>
{
    builder.WithConfig(cfg => { /* host / token … */ });
    builder.WithRuntimeErrorCapture();   // capture in-game runtime errors + expose the runtime-errors-* tool
}).Build();

await _mcp.Connect();

Essa única chamada instala três canais de captura de melhor esforço e registra a ferramenta runtime-errors-*:

1. Fluxo de erros do motor (Godot 4.5+) — registra um Godot.Logger via OS.AddLogger, para que erros de tempo de execução do GDScript, push_error/push_warning e erros de shader levantados no jogo em execução sejam capturados com sua origem (file / line / function).
2. Exceções C# não tratadas — AppDomain.CurrentDomain.UnhandledException, com o rastreamento de pilha gerenciado completo.
3. Exceções C# não observadas de Task — TaskScheduler.UnobservedTaskException, com o rastreamento de pilha gerenciado completo. (Ele apenas observa para registro — não chama SetObserved(), portanto o comportamento de escalonamento do seu jogo permanece inalterado.)

Um cliente MCP consulta os erros capturados com a ferramenta runtime-errors-get (e limpa o buffer com runtime-errors-clear):

Ferramenta	O que retorna / faz
runtime-errors-get	Uma lista limitada, mantendo os mais recentes, de { sequence, message, type, source, file, line, function, stackTrace, frames, timestamp }. Passe o highestSequence do resultado anterior como sinceSequence para consultar apenas erros novos — o loop "algo quebrou desde a última vez que olhei?". Retorna available:false quando a captura nunca foi habilitada (para que uma lista vazia nunca seja confundida com saúde).
runtime-errors-clear	Limpa o buffer capturado (o contador monotônico sequence é preservado, portanto uma consulta sinceSequence anterior à limpeza ainda se comporta).

Fidelidade do rastreamento de pilha (leia isto). As duas fontes de erro diferem em profundidade:

• Erros do motor (source: Engine) carregam a origem do erro — file:line e o function de origem — além da mensagem e um type (Error / Warning / Script / Shader). No Godot 4.5+, um erro de tempo de execução do GDScript também carrega a pilha de chamadas profunda de vários quadros: frames é o backtrace ordenado (do mais interno para o mais externo) — cada { function, file, line } — e stackTrace é a renderização formatada do motor dele. No Godot < 4.5 (ou uma compilação de lançamento sem rastreamento de pilha de chamadas) frames é null e stackTrace é null (somente origem). Os quadros são materializados fora do ScriptBacktrace não seguro para threads do motor dentro do callback do registrador na thread de origem — apenas valores gerenciados simples cruzam para o coletor, nunca um objeto vivo do motor.
• Falhas C# (source: UnhandledException / UnobservedTaskException) carregam o rastreamento de pilha gerenciado completo (exceções internas embutidas) em stackTrace, além do nome do tipo de exceção CLR em type. (frames é null — a pilha gerenciada vive na string stackTrace.)

Degradação graciosa. No Godot < 4.5 não há hook gerenciado OS.AddLogger, portanto o canal do motor fica silenciosamente indisponível — os canais de exceção C# ainda funcionam, e runtime-errors-get ainda funciona (apenas não verá erros de tempo de execução do GDScript). E como no restante do modo de tempo de execução, a captura é estritamente opcional — sem WithRuntimeErrorCapture() nada é conectado e não há mudança de comportamento. Descartar o handle (handle.Dispose()) desinstala os hooks. ⚠️ Segurança — divulgação de informações. Erros capturados encaminham a mensagem completa e (para falhas em C#) o stack trace gerenciado completo para o agente conectado por meio de runtime-errors-get. Essas strings podem incorporar dados sensíveis de runtime — caminhos absolutos de sistema de arquivos, nomes de máquina/usuário, strings de consulta ou um segredo/token que por acaso apareceu em uma mensagem de exceção ou argumento. Esse é o valor diagnóstico pretendido, mas amplia o que é exposto pela conexão. Habilite WithRuntimeErrorCapture() somente em uma conexão confiável: um host de loopback (http://localhost:… / 127.0.0.1) com AuthOption = Consts.MCP.Server.AuthOption.token e um token real — nunca uma interface pública não autenticada em uma build de lançamento. Consulte Segurança e docs/runtime-security.md.

Exemplo: uma ferramenta de estado de jogo ao vivo

Uma ferramenta de runtime é escrita exatamente como uma ferramenta de editor — uma partial class decorada [AiToolType], cada método decorado [AiTool("tool-name", …)] com um [Description] no método e em cada parâmetro. Qualquer chamada de API do Godot (Node, SceneTree, …) deve ser executada na thread principal do motor — faça o marshaling por meio de MainThread.Instance.Run(...) (o MainThread do ReflectorNet, apoiado pelo dispatcher Initialize() inicializado para você).

Este análogo Godot do exemplo "Chess bot" do Unity-MCP expõe o SceneTree em execução ao vivo para o LLM — um round-trip game-ping puramente gerenciado mais um game-scene-tree-summary que lê o estado real do Node:

using System.ComponentModel;
using com.IvanMurzak.McpPlugin;              // [AiToolType], [AiTool]
using com.IvanMurzak.ReflectorNet.Utils;     // MainThread
using Godot;

[AiToolType]
public partial class GameMcpTools
{
    [AiTool("game-ping", Title = "Game Ping", ReadOnlyHint = true, IdempotentHint = true)]
    [Description("Runtime readiness probe. Echoes 'message' back, or returns 'pong-from-game' when omitted.")]
    public string GamePing(
        [Description("Optional message to echo back. When null/empty, returns 'pong-from-game'.")]
        string? message = null)
    {
        return string.IsNullOrEmpty(message) ? "pong-from-game" : message;
    }

    [AiTool("game-scene-tree-summary", Title = "Game Scene-Tree Summary", ReadOnlyHint = true)]
    [Description("Summary of the LIVE running game's SceneTree (current scene + root child node names).")]
    public SceneTreeSummary GameSceneTreeSummary()
    {
        // Touch the live SceneTree on the engine main thread — MainThread.Instance was installed by
        // GodotMcpRuntime.Initialize(...). Touching Node APIs off the main thread would fault.
        return MainThread.Instance.Run(() =>
        {
            var summary = new SceneTreeSummary();
            if (Engine.GetMainLoop() is not SceneTree tree || tree.Root == null)
            {
                summary.CurrentSceneName = "<no-scene-tree>";
                return summary;
            }

            summary.CurrentSceneName = tree.CurrentScene?.Name ?? "<none>";
            summary.RootChildCount   = tree.Root.GetChildCount();
            foreach (var child in tree.Root.GetChildren())
                summary.RootChildNames.Add(child.Name);
            return summary;
        });
    }
}

// Structured result (ReflectorNet-serialized — never ad-hoc string formatting for parseable output).
public sealed class SceneTreeSummary
{
    public string CurrentSceneName { get; set; } = string.Empty;
    public int RootChildCount { get; set; }
    public System.Collections.Generic.List<string> RootChildNames { get; set; } = new();
}

Registre-o a partir do bloco Initialize(...) acima (WithToolsFromAssembly(Assembly.GetExecutingAssembly()) o detecta automaticamente), conecte-se, e o LLM agora pode chamar game-ping / game-scene-tree-summary contra seu jogo ao vivo. Exemplo real de terceirização de lógica de bot: uma ferramenta chess-do-turn que chama seu controlador de jogo na thread principal, além de uma ferramenta chess-get-board que retorna um modelo de tabuleiro estruturado.

Mesmo contrato [AiToolType]/[AiTool]/MainThread.Instance.Run(...) da seção Personalizar Ferramentas do editor — a única diferença é que em uma build de jogo você registra as ferramentas e você chama Connect().

Exemplo: um prompt e um recurso

Ferramentas não são a única coisa que você pode expor — o MCP também tem prompts (modelos de instrução reutilizáveis que um LLM pode solicitar por nome) e recursos (conteúdo endereçável e somente leitura que o LLM pode buscar por URI). Eles registram exatamente como ferramentas: uma partial class decorada [AiPromptType] / [AiResourceType], com cada membro decorado [AiPrompt(...)] / [AiResource(...)] e um [Description]. Registre suas classes de prompt e recurso da mesma forma que registra ferramentas — WithPromptsFromAssembly(...) / WithResourcesFromAssembly(...) (ou os por tipo WithPrompts(...) / WithResources(...)) a partir do bloco Initialize(...) acima. Cada tipo é independentemente opcional — um jogo pode expor prompts e/ou recursos sem nenhuma ferramenta.

using System.ComponentModel;
using com.IvanMurzak.McpPlugin;               // [AiPromptType], [AiPrompt], [AiResourceType], [AiResource]
using com.IvanMurzak.McpPlugin.Common.Model;  // Role, ResponseResourceContent
using com.IvanMurzak.ReflectorNet.Utils;      // MainThread
using Godot;

// A PROMPT — a named, reusable instruction the LLM can request. Returns the prompt text; Role marks who
// the message is from. Set Enabled = false to ship a prompt registered-but-off until you flip it on.
[AiPromptType]
public partial class GameMcpPrompts
{
    [AiPrompt(Name = "explain-game-state", Role = Role.User)]
    [Description("Ask the assistant to summarize the current game state for the player.")]
    public string ExplainGameState()
    {
        return "Read the live SceneTree via the game tools and explain the current game state in one paragraph.";
    }
}

// A RESOURCE — addressable read-only content fetched by URI. Route is the URI template; the method
// returns ResponseResourceContent[]. Any Godot API access marshals onto the main thread, exactly like a tool.
[AiResourceType]
public partial class GameMcpResources
{
    [AiResource(
        Name = "Live SceneTree node names",
        Route = "game://scene-tree/nodes",
        MimeType = "application/json",
        Description = "The root child node names of the live running game's SceneTree.")]
    public ResponseResourceContent[] SceneTreeNodes(string uri)
    {
        return MainThread.Instance.Run(() =>
        {
            var names = new System.Collections.Generic.List<string>();
            if (Engine.GetMainLoop() is SceneTree tree && tree.Root != null)
            {
                foreach (var child in tree.Root.GetChildren())
                    names.Add(child.Name);
            }

            var json = System.Text.Json.JsonSerializer.Serialize(names);
            return new[] { ResponseResourceContent.CreateText(uri, json, "application/json") };
        });
    }
}

Mesmo contrato de registro manual independentemente opcional das ferramentas. Os nomes de atributos [AiPrompt]/[AiResource], o enum Role e o auxiliar ResponseResourceContent vêm todos do pacote com.IvanMurzak.McpPlugin reutilizado que o caminho do editor já usa — nada específico do Godot para aprender.

De onde vêm a URL do servidor e o token

Uma build de jogo nunca carrega automaticamente a configuração salva do editor (isso é uma conveniência apenas do editor). Você fornece host/token de uma de duas maneiras — e elas se compõem, com env vencendo sobre código no momento da resolução:

1. No código — builder.WithConfig(c => { c.Host = …; c.Token = …; }), como acima.

2. Fora de banda — variáveis de ambiente do processo GODOT_MCP_* ou um arquivo de projeto .env (lido ao vivo por GodotMcpConfig, para que uma build possa ser reconfigurada sem recompilar):

   Variável de ambiente	Valores	Descrição
   GODOT_MCP_CONNECTION_MODE	Cloud / Custom	Modo de conexão (um host de loopback implica Custom).
   GODOT_MCP_CLOUD_URL	URL	Substitui a URL base da Cloud (padrão https://ai-game.dev).
   GODOT_MCP_HOST	URL	Host do servidor no modo personalizado (padrão http://localhost:8080).
   GODOT_MCP_AUTH_OPTION	none / oauth / token	Autenticação do modo personalizado: anônimo / conta (oauth) / bearer offline (token).
   GODOT_MCP_TOKEN	string	O token bearer (roteado para Cloud ou Personalizado pelo modo ativo).
   GODOT_MCP_LOG_LEVEL	Trace…None	Limite de verbosidade de log.
   GODOT_MCP_SERVER_PATH	caminho absoluto	Somente editor (dev / CI). Inicie este gamedev-mcp-server(.exe) existente em vez da versão fixada: ignora o download e a correspondência de versão, e desativa a limpeza de servidores órfãos enquanto ativo. Um valor que não nomeia um arquivo existente é ignorado.

   GODOT_MCP_SERVER_PATH é resolvido pelo gerenciador de servidores do plugin do editor, não por GodotMcpConfig, então afeta apenas qual binário de servidor hospedado localmente o editor inicia, e não tem efeito em uma build de jogo. É lido uma vez por carregamento de assembly do plugin e armazenado em cache — um hot-reload em C# o relê, mas alternar o plugin desligado e ligado não. Ele usa a mesma precedência processo-env → projeto .env das linhas acima. A limpeza de órfãos é desativada enquanto está definido porque essa limpeza reivindica cada processo de servidor em execução no mesmo diretório, que um binário de substituição deve compartilhar com outros projetos e ferramentas. Um valor que não nomeia um arquivo existente é ignorado com um aviso no log do editor. No Linux/macOS o arquivo já deve ser executável — o chmod aplicado a uma versão baixada não é aplicado a um binário de substituição.

   export GODOT_MCP_CONNECTION_MODE=Custom
   export GODOT_MCP_HOST=http://localhost:8080
   export GODOT_MCP_AUTH_OPTION=token
   export GODOT_MCP_TOKEN=your-secret-token
   

• Modo Cloud (GodotMcpConnectionMode.Cloud) conecta-se a https://ai-game.dev (substituível com GODOT_MCP_CLOUD_URL).
• Modo personalizado (GodotMcpConnectionMode.Custom) conecta-se ao seu próprio servidor — um servidor de desenvolvimento local, auto-hospedado ou um endereço de loopback. Este é o modo recomendado para um jogo lançado (veja abaixo).

Segurança: somente opt-in, DESLIGADO por padrão

Expor um servidor MCP dentro de um jogo lançado abre uma superfície de controle remoto: qualquer coisa que suas ferramentas registradas possam fazer, um cliente MCP conectado pode acionar. O runtime do Godot-MCP é construído para que isso só possa acontecer deliberadamente:

• Somente opt-in / DESLIGADO por padrão. Criar um handle não conecta. Nada acontece até que seu código chame Connect(). Não há caminho de conexão automática em uma build de jogo.
• Zero ferramentas por padrão. Um runtime sem chamada WithTools… registra nada. A superfície de ataque é exatamente o conjunto de ferramentas que você escolheu registrar — nada mais.
• Sem carregamento automático de configuração persistida. Uma build de jogo nunca lê silenciosamente um arquivo de configuração salvo; host/token vêm apenas do seu código ou GODOT_MCP_* env / .env.
• Prefira loopback + um token obrigatório. Para ferramentas locais, vincule a um host de loopback (http://localhost:… / 127.0.0.1) e defina AuthOption = Consts.MCP.Server.AuthOption.token com um Token real. Evite expor a conexão em uma interface pública em uma build de lançamento, a menos que você tenha explicitamente projetado e protegido essa superfície.
• A captura de erros de runtime encaminha dados sensíveis. WithRuntimeErrorCapture() está DESLIGADO por padrão. Quando habilitado, mensagens capturadas e stack traces são enviados literalmente ao agente conectado via runtime-errors-get e podem conter caminhos absolutos, nomes de máquina/usuário ou um segredo que apareceu em uma exceção — então habilite apenas em uma conexão confiável de loopback + token (nota completa em Capturando erros de runtime no jogo).

Notas de segurança do lado do editor (postura aceita)

Os pontos acima são sobre uma build de jogo. Duas superfícies do lado do editor são documentadas aqui para completude; ambas são por design hoje:

• O armazenamento de token do editor é texto simples em repouso. Quando você conecta o plugin do editor (auth de dispositivo Cloud ou um token de modo personalizado), o plugin persiste sua configuração de conexão — incluindo o token bearer (token) e o token Cloud (cloudToken) — como JSON em texto simples em user://godot-mcp-config.json (resolvido por diretório de dados user:// do Godot). Ele não é criptografado ou armazenado em um keystore do SO. A suposição de confiança é a conta de usuário local: qualquer pessoa com acesso de leitura ao seu diretório de dados de usuário pode ler o token. Trate esse arquivo como um segredo — não o envie, sincronize ou compartilhe. Para rotacionar, limpe o token salvo no dock (ou exclua o arquivo) e reconecte. (Substituições de env de processo / .env via GODOT_MCP_TOKEN sempre sobrepõem o valor persistido e não são gravadas de volta neste arquivo.)
• A ponte de controle de desenvolvimento é não autenticada, mas bloqueada por padrão. Uma ponte HTTP de injeção/controle apenas para desenvolvimento existe para acionar o dock do editor em testes. Ela é não autenticada, mas seu limite de segurança é triplo: é apenas do editor (#if TOOLS, nunca compilada em um jogo), vincula 127.0.0.1 apenas, e inicia somente quando GODOT_MCP_DEV_CONTROL=1 — um addon lançado (e qualquer sessão de editor sem a variável de env) nunca escuta. Esse portão de env é essencial e aplicado por um teste de unidade + uma asserção no momento da inicialização, então nunca pode ser silenciosamente lançado habilitado.

Uma cópia curta e independente deste contrato vive em docs/runtime-security.md.

Como a Arquitetura do Godot MCP Funciona

Godot-MCP é uma ponte entre LLMs e o editor Godot. Ele expõe e explica as ferramentas do Godot ao LLM, que então entende a interface e usa as ferramentas de acordo com suas solicitações.

No carregamento do editor, o [Tool] EditorPlugin (GodotMcpPlugin) inicializa o plugin: ele instala um dispatcher de thread principal, constrói um ReflectorNet Reflector com conversores de tipo Godot e abre uma conexão SignalR para um servidor MCP sobre o cliente com.IvanMurzak.McpPlugin reutilizado. As ferramentas de IA que ele registra são então chamáveis por qualquer agente de IA compatível com MCP.

O que é MCP

MCP — Model Context Protocol. Em poucas palavras, é USB Type-C para IA, especificamente para LLMs (Large Language Models). Ele ensina ao LLM como usar recursos externos — como o Godot Engine neste caso, ou até mesmo seu próprio método C# personalizado. Documentação oficial.

O que é um AI agent

É um aplicativo com uma janela de chat. Pode ter agentes inteligentes para operar melhor e ferramentas MCP avançadas incorporadas. Um cliente MCP bem construído é 50% do sucesso da IA na execução de uma tarefa — por isso é importante escolher um bom.

O que é o MCP Server

É a ponte entre o MCP Client e "algo mais" — neste caso, o editor Godot. No modo Cloud este é o backend ai-game.dev hospedado; no modo Personalizado é o host GameDev-MCP-Server compartilhado que você executa (ou deixa o addon baixar e executar para você).

O que é um MCP Tool

Um MCP Tool é uma função que o LLM pode chamar para interagir com o Godot. Essas ferramentas são a ponte entre solicitações em linguagem natural e operações reais do Godot. Quando você pede à IA para "criar um nó" ou "abrir uma cena", ela usa ferramentas MCP para executar a ação. As ferramentas têm parâmetros tipados e descritos; retornam resultados estruturados; e são conscientes de thread (thread principal para chamadas de API do Godot, thread de fundo para processamento pesado).

Construindo e contribuindo

Godot.NET.Sdk é um SDK NuGet, então nenhum binário Godot é necessário para compilar ou testar unitariamente:

dotnet restore Godot-MCP.sln
dotnet build  Godot-MCP.sln --configuration Debug --no-restore   # 0 errors required (CI gate)
dotnet test   Godot-MCP.Tests/Godot-MCP.Tests.csproj --configuration Debug --no-build

Um editor Godot 4.3+ só é necessário para verificação comportamental ao vivo das ferramentas que acionam o motor. Consulte CLAUDE.md para o runbook completo de build/teste/execução, a correção de carregamento de assembly editor-runtime, convenções e o teste de fumaça do testbed headless.

Contribuições são muito apreciadas. Por favor, dê uma estrela 🌟 a este projeto se você o achar útil!

1. 👉 Faça um fork do projeto
2. Clone o fork e abra-o em um editor Godot 4.3+ (mono)
3. Implemente novas funcionalidades, faça commit e envie para o GitHub
4. Crie um Pull Request direcionado ao repositório original Godot-MCP, branch main.

Licença

Apache-2.0 © Ivan Murzak