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

透過 ai-game.dev 雲端端點或本機伺服器，將 Claude Code、Cursor、Copilot、Codex、Gemini 等 MCP 用戶端連接到 Unity MCP。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/unity/connecting-ai-clients)。

本頁說明 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](https://ai-game.dev/zh-hant/docs/wiki/unity/configuration#connection-modes) 涵蓋本機伺服器設定。

## 釘選的 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 應用程式](https://ai-game.dev/docs/app)中：**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](https://ai-game.dev/docs/auth)），並以 `setup-mcp --token <token>` 傳入。

請把專案金鑰與權杖視同密碼。`.mcp.json` 等檔案位於你的專案資料夾中，因此提交前請檢查 `.gitignore`。[Authentication](https://ai-game.dev/docs/auth) 說明帳號端的部分。

## 支援的 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 版本支援的識別碼。

**提示**

Claude Desktop 與 Unity AI 不會使用產生的 skills，而 Custom 項目則可讓你選擇 skills 資料夾。至於其他代理，還要開啟 **Skills > Auto-generate**（或執行 `setup-skills`），代理才會學會 RQL。

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

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

```bash
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 參考文件](https://ai-game.dev/zh-hant/docs/wiki/unity/cli#setup-mcp) 中。

## 手動設定

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

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

通用的 `mcpServers` JSON 設定：

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

將 URL 換成你專案釘選的 URL（顯示在視窗的手動設定步驟中），即可指定單一專案。[MCP 端點頁面](https://ai-game.dev/zh-hant/mcp-endpoint-info) 提供了各種用戶端的片段，包括 VS Code 的 `servers` 格式與 PAT 標頭。

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

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

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

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

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

```bash
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 伺服器，讓它讀取新的設定。接著依照 [開始使用](https://ai-game.dev/zh-hant/docs/wiki/unity/getting-started#verify) 檢查連線。如果用戶端沒有顯示任何工具，請參閱 [疑難排解](https://ai-game.dev/zh-hant/docs/wiki/unity/troubleshooting#no-tools)。

---

Source (HTML): https://ai-game.dev/zh-hant/docs/wiki/unity/connecting-ai-clients

Machine-translated (zh-Hant) from the English page: https://ai-game.dev/docs/wiki/unity/connecting-ai-clients