連接 AI 用戶端 — Unity · AI Game Developer Wiki

本頁說明 AI 用戶端如何連上 Unity Editor、使用哪個端點與登入方式，以及如何從 AI Game Developer 視窗、unity-mcp-cli 或手動設定各個支援的代理。

兩種連線方式

你的 AI 用戶端從不直接與 Unity 通訊。兩者都連線到 MCP 伺服器，伺服器再透過 SignalR 連線將工具呼叫路由到 Editor。

	雲端（預設）	自訂（本機）
伺服器	託管端點 `https://ai-game.dev/mcp`	`gamedev-mcp-server`，由外掛下載並啟動
Editor 連線	外掛連線到 ai-game.dev	外掛連線到 `http://localhost:<port>`
用戶端端點	`https://ai-game.dev/mcp/p/<pin>`（已釘選）或 `https://ai-game.dev/mcp`	`http://localhost:<port>`，或透過 stdio 使用伺服器二進位檔
登入	ai-game.dev 帳號（OAuth 裝置流程）	無、ai-game.dev OAuth，或共用權杖
可離線運作	否	是，搭配 `none` 或 `token` 授權

在 AI Game Developer 視窗中以 Connection 開關（Custom / Cloud）選擇模式。Configuration 涵蓋本機伺服器設定。

釘選的 URL

基底端點 https://ai-game.dev/mcp 會以遞補方式路由到你其中一個已連線的編輯器。只有一個開啟中的專案時沒問題，但有多個專案時就會產生歧義。

釘選的 URL https://ai-game.dev/mcp/p/<pin> 一律路由到某個專案的 Editor。釘選值衍生自專案的身分識別。視窗中的 Configure 按鈕與 unity-mcp-cli setup-mcp 預設會寫入釘選的 URL；setup-mcp --no-pin 則改寫入基底 URL。使用 stdio 傳輸時，釘選值會以 project=<pin> 引數傳入。

Editor、CLI 與桌面應用程式共用同一份整台機器通用的登入資訊，位於 ~/.ai-game-dev/credentials.json。在其中任一處登入一次即可：

在視窗中：切換到 Cloud 模式，按 Authorize，然後在瀏覽器中核准驗證碼。
在終端機中：unity-mcp-cli login。
在 AI Game Dev 應用程式中：Sign in。

權杖會在背景自動更新。視窗中的 Revoke 會登出這台機器上所有 AI Game Dev 工具（所有引擎外掛、CLI 與桌面應用程式），並在伺服器端撤銷權杖。

AI 用戶端本身如何驗證，取決於所寫入的設定：

專案金鑰（已登入時 Cloud HTTP 的預設值）。 設定檔會帶有 Authorization: Bearer agd_pk_…，這是不會過期、可撤銷且僅綁定此專案的金鑰。金鑰保存在 ~/.ai-game-dev/project-keys.json。視窗中的 Regenerate key 或 setup-mcp --regenerate-key 會替換金鑰並撤銷舊的。
OAuth（僅 URL）。 檔案中不含任何憑證；用戶端首次連線時會開啟瀏覽器登入。未登入時，或使用 setup-mcp --oauth 時，會得到這個。
個人存取權杖。 供 CI 或無法進行瀏覽器登入的用戶端使用；請在你的 ai-game.dev 帳號中建立權杖（見 Authentication），並以 setup-mcp --token <token> 傳入。

請把專案金鑰與權杖視同密碼。.mcp.json 等檔案位於你的專案資料夾中，因此提交前請檢查 .gitignore。Authentication 說明帳號端的部分。

支援的 AI 代理

視窗中的 AI agent 下拉選單列出這些設定器。Configure 會寫入所顯示的檔案；Remove 則會移除該項目。

代理	寫入的設定檔	CLI 識別碼
Claude Code	`.mcp.json`（專案根目錄）	`claude-code`
Claude Desktop	Claude 應用程式資料夾中的 `claude_desktop_config.json`	`claude-desktop`
Cursor	`.cursor/mcp.json`	`cursor`
Visual Studio Code (Copilot)	`.vscode/mcp.json`	`vscode-copilot`
Visual Studio (Copilot)	`.vs/mcp.json`	`vs-copilot`
Rider (Junie)	`.junie/mcp/mcp.json`	`rider-junie`
GitHub Copilot CLI	`~/.copilot/mcp-config.json`	`github-copilot-cli`
Gemini	`.gemini/settings.json`	`gemini`
Antigravity	`~/.gemini/config/mcp_config.json` 與 `~/.gemini/antigravity/mcp_config.json`	`antigravity`
Cline	VS Code 全域儲存空間中的 `cline_mcp_settings.json`	`cline`
Open Code	`opencode.json`	`open-code`
Codex	`.codex/config.toml`	`codex`
Kilo Code	`.kilocode/mcp.json`	僅限視窗
Zoo Code	`.roo/mcp.json`	僅限視窗
Unity AI	`UserSettings/mcp.json`	`unity-ai`
其他 - 自訂	顯示可複製的 JSON	`custom`

相對路徑位於你的 Unity 專案內。伺服器項目一律命名為 ai-game-developer。執行 unity-mcp-cli setup-mcp --list 可查看你的 CLI 版本支援的識別碼。

使用 unity-mcp-cli 進行設定

setup-mcp 會寫入與視窗中 Configure 按鈕相同的輸出，而且不必開啟 Unity：

unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-mcp cursor ./MyUnityProject --transport stdio
unity-mcp-cli setup-mcp claude-code ./MyUnityProject --no-pin

預設的傳輸方式是 http。若改用 --transport stdio，設定則會改為啟動本機伺服器執行檔。所有旗標都列在 CLI 參考文件中。

手動設定

任何支援 HTTP 的 MCP 用戶端都能使用託管端點。Claude Code 範例：

claude mcp add --transport http ai-game-developer https://ai-game.dev/mcp

通用的 mcpServers JSON 設定：

{
  "mcpServers": {
    "ai-game-developer": {
      "url": "https://ai-game.dev/mcp"
    }
  }
}

將 URL 換成你專案釘選的 URL（顯示在視窗的手動設定步驟中），即可指定單一專案。MCP 端點頁面提供了各種用戶端的片段，包括 VS Code 的 servers 格式與 PAT 標頭。

透過 HTTP 連線的本機伺服器

在 Custom 模式搭配 HTTP 傳輸時，將用戶端指向本機伺服器。連接埠就是視窗中 Server URL 所用的那一個；視窗中針對你的代理所顯示的手動設定步驟含有確切的 URL，包括專案固定碼：

{
  "mcpServers": {
    "ai-game-developer": {
      "url": "http://localhost:<port>"
    }
  }
}

透過 stdio 連線的本機伺服器

使用 stdio 傳輸時，用戶端會自行啟動伺服器執行檔。在 Windows 上：

claude mcp add ai-game-developer "<project>/Library/mcp-server/win-x64/gamedev-mcp-server.exe" port=<port> plugin-timeout=10000 client-transport=stdio

其他平台請使用 osx-arm64、osx-x64、linux-x64、linux-arm64、win-x86 或 win-arm64（Windows 以外不加 .exe）。將 <project> 換成完整的專案路徑，並將 <port> 換成視窗中的連接埠。同一時間只能有一個代理使用 stdio 伺服器，而且視窗的 Start/Stop 按鈕會停用，因為該程序由代理所擁有。除非你的用戶端不支援 HTTP，否則請優先使用 HTTP。

設定完成後

重新啟動 AI 用戶端，或重新連線它的 MCP 伺服器，讓它讀取新的設定。接著依照開始使用檢查連線。如果用戶端沒有顯示任何工具，請參閱疑難排解。

兩種連線方式#

釘選的 URL#

登入#

支援的 AI 代理#

使用 unity-mcp-cli 進行設定#

手動設定#

透過 HTTP 連線的本機伺服器#

透過 stdio 連線的本機伺服器#

設定完成後#

兩種連線方式

釘選的 URL

登入

支援的 AI 代理

使用 unity-mcp-cli 進行設定

手動設定

透過 HTTP 連線的本機伺服器

透過 stdio 連線的本機伺服器

設定完成後