連接 AI 用戶端
透過 ai-game.dev 雲端端點或你自己的本機伺服器，將 Claude Code、Cursor、Copilot、Codex、Gemini 及其他 MCP 用戶端連線到 Godot MCP。
Godot MCP 有兩個部分，兩者都會連線到 MCP 伺服器：Godot 編輯器中的外掛，以及你與之對話的 AI 用戶端。本頁說明兩種連線模式、登入的運作方式，以及如何用 godot-cli setup-mcp 或停靠面板上的 Configure 按鈕，為每個支援的代理撰寫 MCP 設定。
Cloud 模式（預設）
在 Cloud 模式下，外掛會連線到 https://ai-game.dev 的託管後端，而你的 AI 用戶端則連線到 MCP 端點 https://ai-game.dev/mcp。你的機器上不會額外執行任何東西，而且能跨越防火牆運作。這是預設模式，也是我們對大多數人的建議。
使用裝置流程登入
Cloud 驗證採用 OAuth 2.1 裝置授權流程。你完全不需要手動複製權杖：
godot-cli loginCLI 會印出一組短代碼、開啟瀏覽器，並等待你核准。憑證（存取權杖、會輪替的重新整理權杖與到期時間）會儲存到機器儲存區 ~/.ai-game-dev/credentials.json（macOS 與 Linux 上檔案模式為 0600，Windows 上受 DPAPI 保護）。編輯器外掛、其他引擎 CLI 與 AI Game Dev 應用程式都會取用它，過期的存取權杖也會自動重新整理。在停靠面板中點選 Authorize 會在 Godot 內執行相同的流程。
實用的 login 旗標：--force 會在已有憑證的情況下重新登入，--project <path> 會保留一份獨立的各專案憑證，而 --tools-only 會為 CI runner 建立範圍較窄的憑證。請參閱 godot-cli 參考文件 與 驗證。
固定的專案 URL
純端點 https://ai-game.dev/mcp 會把你的代理路由到你其中一個已連線的編輯器。同時開啟多個專案時這會有歧義，因此 setup-mcp 預設會寫入固定 URL：https://ai-game.dev/mcp/p/<pin>，其中 pin 由專案衍生而來。以此設定啟動的代理一定連得到這個專案的編輯器。若想要純 URL，請傳入 --no-pin。
專案金鑰
當你登入後，setup-mcp 會把專案金鑰寫入代理設定，形式為 Authorization: Bearer agd_pk_…。專案金鑰不會過期，且只能用於此專案的 pin，因此無法存取你帳號下的其他專案。每個專案只會建立一次，並從 ~/.ai-game-dev/project-keys.json 重複使用。
--regenerate-key會建立新金鑰、改寫設定並撤銷舊金鑰。--oauth則改為寫入僅含 URL 的設定：由代理以自己的 OAuth 提示登入。- 若機器上沒有登入，設定也會是僅含 URL 的形式。
自訂模式：你自己的伺服器
在自訂模式下，外掛會連線到你選擇的伺服器 URL，例如你自己機器上的伺服器。該伺服器是開源的 GameDev-MCP-Server，與 Unity MCP 和 Unreal MCP 使用的是同一個二進位檔。
最簡單的方式是讓外掛來執行它：
- 在停靠面板中，把模式切換為 Custom。
- 讓 Server URL 保持為
http://localhost:8080，或輸入另一個本機 URL。 - 點選 Start Server。外掛會從 GitHub（僅限 HTTPS、github.com）下載其固定伺服器版本的伺服器建置檔，快取到
.godot/mcp-server/<platform>/，啟動它並連線。
Stop Server 會停止它，關閉編輯器也會停止。在 CI 環境中會略過下載。若想自行執行伺服器，可下載發行版二進位檔或 aigamedeveloper/mcp-server Docker 映像檔：
./gamedev-mcp-server --client-transport streamableHttp --port 8080自訂伺服器的授權
自訂模式有一個 Authorization Token 開關，共三種值：
| 值 | 意義 |
|---|---|
none | 不驗證。適用於只在自己機器上監聽的伺服器。 |
oauth | 傳送你已登入的 ai-game.dev 帳號權杖，但僅限於 localhost 伺服器（localhost、127.0.0.0/8、::1）。 |
token | Bearer 權杖。點選 New 產生一個；它會以遮蔽方式儲存。 |
對於任何非本機主機搭配 oauth，外掛會拒絕傳送你的帳號權杖；請改為設定 GODOT_MCP_TOKEN。兩種模式的環境變數都列在 組態設定。
若要讓代理指向本機伺服器，請把 URL 傳給 setup-mcp：
godot-cli setup-mcp claude-code ./MyGodotProject --url http://localhost:8080本機伺服器設定永遠不會帶有專案金鑰。
支援的代理與設定檔
執行 godot-cli setup-mcp --list 可查看每個 agent id。以下是目前 CLI 所知道的所有 id，以及它寫入設定的位置：
| Agent | id | 設定檔 |
|---|---|---|
| Claude Code | claude-code | 專案中的 .mcp.json |
| Claude Desktop | claude-desktop | 使用 Claude 自訂連接器（見下文） |
| Cursor | cursor | .cursor/mcp.json |
| Visual Studio Code (Copilot) | vscode-copilot | .vscode/mcp.json |
| Visual Studio (Copilot) | vs-copilot | .vs/mcp.json |
| Rider (Junie) | rider-junie | .junie/mcp/mcp.json |
| GitHub Copilot CLI | github-copilot-cli | ~/.copilot/mcp-config.json |
| Gemini | gemini | .gemini/settings.json |
| Antigravity | antigravity | ~/.gemini/config/mcp_config.json 與 ~/.gemini/antigravity/mcp_config.json |
| Cline | cline | VS Code 全域儲存空間中的 cline_mcp_settings.json |
| Open Code | open-code | opencode.json |
| Codex | codex | .codex/config.toml |
| Kilo Code | kilo-code | .kilocode/mcp.json |
| 任何其他 MCP 用戶端 | custom | 專案中的 mcp.json |
範例：
godot-cli setup-mcp cursor ./MyGodotProject
godot-cli setup-mcp codex ./MyGodotProject
godot-cli setup-mcp vscode-copilot ./MyGodotProject --oauth每個設定都使用 HTTP 傳輸（type: http 與一個 URL）。Codex 則是把金鑰放進 http_headers。
Claude Desktop 與 claude.ai
Claude Desktop 不會從 claude_desktop_config.json 接受 HTTP 伺服器項目。Claude Desktop 與 claude.ai 改為以 Claude 自訂連接器的方式連上雲端端點：在 Claude 的設定中新增自訂連接器、貼上專案固定的雲端 URL，並以你的 ai-game.dev 帳號登入。Claude Desktop 無法使用 Custom 模式的伺服器，因為 Godot MCP 並未為它提供 stdio 傳輸。若要使用本機伺服器，請改用表中支援 HTTP 的 agent，例如 Claude Code。
從 dock 面板設定
dock 的 AI agent 區塊功能等同於 setup-mcp：從清單中選擇你的 agent，然後點選 Configure（或 Reconfigure）。狀態列會顯示該 agent 的設定檔是否已設定完成；若你在設定後變更伺服器 URL、模式或授權，就會出現 Reconfiguration Required 提示。Remove 會從該 agent 的設定中刪除 Godot MCP 項目。
你的 agent 適用的 Skills
有些 agent 會讀取 skill 檔案（SKILL.md），從中學習如何使用這些工具。dock 的 AI agent 區塊中的 Skills 列可以產生這些檔案（Generate，或 Auto-generate 開關）。從終端機執行：
godot-cli setup-skills claude-code ./MyGodotProject這會在沒有執行編輯器的情況下，把檔案寫入該 agent 的 skills 資料夾，例如 Claude Code 的 .claude/skills。setup-skills --list 會顯示哪些 agent 支援 skills。
可直接複製貼上的設定
如果你的用戶端不在清單中，任何支援 HTTP 伺服器的 MCP 用戶端都能使用：將它指向 https://ai-game.dev/mcp（或固定的 URL），讓它以 OAuth 登入，或加入 bearer 標頭。許多用戶端的現成片段可在 MCP 端點頁面 找到。