設定
在 AI Game Developer 面板中設定 Godot MCP、選擇 AI 代理可看到的工具，並用 GODOT_MCP_* 環境變數覆寫設定。
大多數人從來不需要改任何設定：外掛預設以 Cloud 模式啟動，你登入後就會連線，並開放它所有的工具。本頁說明在需要時你可以調整哪些設定，包括 AI Game Developer 面板、已儲存的設定，以及供 CI 與腳本執行使用的環境變數。
AI Game Developer 面板
此外掛會在 Godot 編輯器右上方的面板區加入一個名為 AI Game Developer 的面板。由上到下分為以下幾個區段。
標頭
標頭會顯示外掛版本與 Log Level 選擇器。記錄等級控制外掛與其連線在 Output 面板印出多少訊息（Trace、Debug、Info、Warning、Error、None；預設為 Info）。在診斷連線問題時，可調高為 Debug 或 Trace。若已設定 GODOT_MCP_LOG_LEVEL，該選擇器會停用，並顯示一則說明。
連線
- Cloud / Custom：連線模式。Cloud 會連線到 ai-game.dev；Custom 則連線到你指定的伺服器 URL。
- Connect / Stop：開始或停止連線到 MCP 伺服器。外掛會持續在背景重試，直到連線成功。
- 在 Cloud 模式下：顯示你的登入狀態，並提供 Authorize（啟動瀏覽器裝置登入）與 Sign out。
- 一行三個點的圖示，分別是 Godot、MCP 伺服器與 AI 代理，用來顯示目前的連線狀況。AI 代理那一列會列出已連線的用戶端名稱；若尚未有用戶端連線，則顯示「(connects on demand)」。
在 Custom 模式下，會多出一張 MCP server 卡片，內容包括：
- Server URL：要連線的伺服器，預設為
http://localhost:8080。 - Authorization Token：
none、oauth（你的 ai-game.dev 帳號權杖，只會傳送給 localhost 伺服器）或token（bearer 權杖；按 New 可產生一個）。 - Start Server / Stop Server：下載、啟動與停止符合此外掛所固定伺服器版本的本機伺服器。請參閱 Connecting AI clients。
若環境變數強制指定模式或主機，會顯示一則黃色提示「Overridden by environment (GODOT_MCP_*)」，此時在面板中的變更不會生效。
AI 代理
選擇你使用的 AI 用戶端（預設為 Claude Code）。接著此區段會顯示：
- Skills：代理的技能檔案存放位置、載入外掛時自動更新這些檔案的 Auto-generate 開關，以及 Generate 按鈕。不支援技能的代理會顯示「Skills not supported by this agent」。
- Model Context Protocol (MCP)：代理的 MCP 設定是否已設定完成，並提供 Configure / Reconfigure 與 Remove。若在你設定代理之後伺服器設定發生變更，會出現 Reconfiguration Required 提示。
MCP 功能
共三列：Tools、Prompts 與 Resources，每一列都會顯示可見項目數與總數（工具列還會顯示預估的權杖成本），並附有一個 Open 按鈕。開啟的視窗會列出所有項目，每個項目都有 Visible 開關，並提供篩選欄位。
Visible 只決定 MCP 用戶端是否會在工具清單中看到該項目。隱藏用不到的工具可讓代理的上下文更精簡。這不是存取控制：若用戶端以名稱呼叫被隱藏的工具，它仍會執行。
擴充功能
可選 Godot MCP 擴充功能的清單，附有 Install 與 Update 按鈕。它會讀取內嵌於你的 .csproj 中的擴充功能目錄；若清單為空，請參閱 Extensions。
頁尾
取得協助與回報問題的連結，以及一個 Serialization Check 視窗，可顯示所選節點或物件如何序列化給 AI（回報錯誤時很有用）。
設定儲存位置
此面板會將設定存到 user://godot-mcp-config.json，也就是 Godot 為該專案儲存的每位使用者資料夾中（不在專案內）。內容包含連線模式、自訂主機、授權選項、記錄等級、所選代理、工具可見性，以及你使用過的權杖。
Cloud 登入憑證另外儲存在機器層級的 ~/.ai-game-dev/credentials.json，與其他 AI Game Developer 工具共用。代理設定的專案金鑰則位於 ~/.ai-game-dev/project-keys.json。
在終端機中，godot-cli configure 可列出並變更專案檔 .godot-mcp/features.json 中的工具、提示與資源可見性：
godot-cli configure ./MyGodotProject --list
godot-cli configure ./MyGodotProject --disable-tools script-delete,script-execute
godot-cli configure ./MyGodotProject --enable-all-tools環境變數
環境變數可在不編輯任何檔案的情況下覆寫已儲存的設定，這對 CI、無頭執行與本機開發都很方便。此外掛也會從專案中的 .env 檔案讀取這些變數；行程環境變數的優先順序高於 .env。
| 變數 | 值 | 用途 |
|---|---|---|
GODOT_MCP_CONNECTION_MODE | Cloud、Custom | 強制指定連線模式。預設為 Cloud。 |
GODOT_MCP_CLOUD_URL | URL | 覆寫雲端基底 URL。預設為 https://ai-game.dev。 |
GODOT_MCP_HOST | URL | Custom 模式的伺服器 URL。預設為 http://localhost:8080。 |
GODOT_MCP_AUTH_OPTION | none、oauth、token | Custom 模式的授權方式。 |
GODOT_MCP_TOKEN | string | 目前模式使用的 Bearer token。會覆寫已儲存的 token，且永遠不會寫回。 |
GODOT_MCP_LOG_LEVEL | Trace 至 None | 記錄詳細程度。 |
GODOT_MCP_CREDENTIALS_DIR | 絕對路徑 | 使用獨立的認證資料存放區，以便進行隔離測試。 |
GODOT_MCP_TOOL_FORMAT | Rql、Json | 工具如何接收引數並回傳結果。預設為 Rql（精簡文字）；Json 會保留 JSON schema 與結果。 |
GODOT_MCP_SERVER_PATH | 絕對路徑 | 僅限編輯器：啟動這個既有的伺服器執行檔，而非下載固定版本的發行版。 |
GODOT_MCP_RUNTIME_FROM_EDITOR | 1 | 讓以 Play 啟動的遊戲也能連接自己的遊戲內 MCP 執行環境。 |
範例：以本機伺服器啟動編輯器。
export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:8080
godot --editor --path ./MyGodotProjectgodot-cli open 會透過 --mode、--url、--cloud-url、--token、--auth 與 --log-level 幫你設定這些項目。請參閱 godot-cli 參考文件。
工具格式
使用預設的 Rql 格式時，工具會以 RQL 值作為引數（例如節點路徑 "Level/Player"，或 godot.find("Name")），並回傳更精簡、消耗更少 token 的文字。Json 格式可透過 GODOT_MCP_TOOL_FORMAT=Json 或 toolFormat 鍵設定，會保留完整的 JSON schema 與結構化結果，適合偏好這類格式的用戶端。更多關於 RQL 的說明：工具。