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

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

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

本頁說明 AI 用戶端如何連到你的 Unreal Editor、登入機制怎麼運作，以及如何為每個支援的代理撰寫 MCP 設定。如果你只想走最快的路徑，編輯器 **AI agent** 區段中的 **Configure** 按鈕（參見 [開始使用](https://ai-game.dev/zh-hant/docs/wiki/unreal/getting-started#ai-client)）就會幫你完成這一切。

## Cloud 或 Custom：選擇連線模式

AI Game Developer 視窗的 **Connection** 區段有 **Custom / Cloud** 切換開關。同樣的設定是 `UNREAL_MCP_CONNECTION_MODE`（參見 [設定](https://ai-game.dev/zh-hant/docs/wiki/unreal/configuration)）。

|  | Cloud（預設） | Custom |
| --- | --- | --- |
| 伺服器 | 位於 ai-game.dev 的託管端點 | 由你自行執行、通常位於 `localhost` 的 `gamedev-mcp-server` |
| 登入 | 你的 ai-game.dev 帳號，裝置代碼流程 | 選用：無、共用權杖或 OAuth |
| 本機執行的項目 | 編輯器及其橋接器 | 編輯器、其橋接器以及本機伺服器 |
| 適用於 | 大多數使用者、多台機器、跨防火牆作業 | 全本機環境、離線作業、CI |

## Cloud 模式

在 Cloud 模式下，橋接器會連線到 ai-game.dev，而你的 AI 用戶端也連到同一個端點 `https://ai-game.dev/mcp`。伺服器會把用戶端的工具呼叫路由到你的編輯器。端點本身的說明請參見 [MCP 端點頁面](https://ai-game.dev/zh-hant/mcp-endpoint-info)。

### 使用裝置代碼流程登入

每台機器只需登入一次。以下任一方式皆可，而且它們與應用程式、其他引擎外掛及 CLI 共用同一個認證存放區（`~/.ai-game-dev/credentials.json`）：

- 在編輯器中：選擇 **Cloud**，點擊 **Authorize**，開啟驗證頁面，輸入視窗中顯示的使用者代碼並核准。
- 在終端機中：`unreal-mcp-cli login`。
- 在 AI Game Dev 應用程式中：照平常方式登入。

**警告：** 在編輯器中按 **Revoke** 會登出整台機器，而不只是這個專案。編輯器會先要求確認，因為所有共用該認證的 AI Game Dev 工具（引擎外掛、CLI 及桌面應用程式）都會一併登出。

帳號、裝置與權杖的運作方式請參見 [驗證頁面](https://ai-game.dev/docs/auth)。

### 專案釘選 URL

如果你的帳號連接了多個編輯器，使用單純 `https://ai-game.dev/mcp` URL 的用戶端可能會連到錯誤的那一個。因此外掛與 `unreal-mcp-cli setup-mcp` 預設會寫入**專案釘選** URL：

```text
https://ai-game.dev/mcp/p/<pin>
```

釘選值是從專案資料夾衍生的，因此用戶端一定會路由到這個專案的編輯器。若要改寫單純的 URL，請使用 `setup-mcp --no-pin`。

### 專案金鑰

當機器已登入時，Cloud 設定還會帶上**專案金鑰**，也就是綁定到此專案的 `Authorization: Bearer agd_pk_…` 標頭。有了它，代理本身就不需要再登入。此金鑰不會過期、可以撤銷，並會快取在 `~/.ai-game-dev/project-keys.json`，讓專案的每個代理重複使用。

- `setup-mcp --oauth` 則會改寫僅含 URL 的設定；代理接著會自行執行 OAuth 登入。
- `setup-mcp --regenerate-key`，或編輯器 AI agent 區段中的 **Regenerate key** 按鈕，會建立新金鑰、用新金鑰改寫已設定的代理，並撤銷舊金鑰。
- 明確指定的 `--token` 優先於上述兩者。

如果機器尚未登入，設定就只含 URL，由代理自行登入。

## Custom 模式：本機伺服器

在 Custom 模式下，橋接器會連線到你自行控管的伺服器，通常是在你機器上執行的共用 `gamedev-mcp-server`。每個專案都會從專案路徑衍生出一個固定介於 20000 到 29999 之間的本機連接埠，因此編輯器與 CLI 無需任何設定就能對上。

若要從編輯器啟動它：

1. 將 Connection 區段切換為 **Custom**。
2. 在 **MCP server** 卡片中，選擇 **http** 傳輸方式並點擊 **Start**。若缺少釘選版本的伺服器，編輯器會下載它、啟動它，並在編輯器結束時停止它。Start 按鈕僅在 Custom 模式與 http 傳輸方式下有效。
3. 選擇 **Authorization** 模式：**none**（本機、匿名）、**token**（共用密鑰；**New** 會產生一個，按住 **Reveal** 即可查看），或 **oauth**。

若要改從終端機啟動，請使用 `unreal-mcp-cli open ./YourProject --start-server --connection-mode Custom`，或以 `unreal-mcp-cli configure` 設定 `UNREAL_MCP_START_SERVER=true`。

\*\*注意：\*\*如果你把本機伺服器指向編輯器，但視窗仍顯示 Cloud，代表橋接器連線到 ai-game.dev，而你的本機伺服器回應「No connected clients」。請明確設定為 Custom 模式。將 `--host` 傳給 `unreal-mcp-cli open` 會自動選用 Custom。

## 使用 setup-mcp 撰寫用戶端設定

`unreal-mcp-cli setup-mcp <agent>` 會為單一 agent 寫入一筆 MCP 設定項目。它會讀取專案已儲存的連線設定，因此請先在編輯器中開啟專案一次（或傳入 `--url`）。

```bash
# Claude Code: writes .mcp.json in the project
unreal-mcp-cli setup-mcp claude-code --path ./YourProject

# Cursor, with the local server over stdio instead of http
unreal-mcp-cli setup-mcp cursor --path ./YourProject --transport stdio

# Print the snippet without writing anything
unreal-mcp-cli setup-mcp vscode-copilot --path ./YourProject --dry-run

# List every agent and its config path
unreal-mcp-cli setup-mcp --list
```

加上 `--transport stdio` 時，CLI 會把固定版本的 `gamedev-mcp-server` 發行版下載到 `<project>/Intermediate/UnrealMCP/server/`，並由 agent 自行啟動該伺服器。

### 支援的 agent

| Agent | `setup-mcp` id | 設定檔 |
| --- | --- | --- |
| Claude Code | `claude-code` | `.mcp.json`（專案） |
| Claude Desktop | `claude-desktop` | `claude_desktop_config.json`（使用者） |
| 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/` 下的 `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`（專案） |

編輯器的 **AI agent** 下拉選單提供同樣的一鍵設定功能，另外還有 **Remove** 可刪除項目、**Tutorial** 與 **Download / Docs** 連結，以及為支援 skills 的 agent 提供的 **Generate skill files**。

## Claude Code 與 Unreal Engine

Claude Code 會從你啟動它的資料夾讀取 `.mcp.json`。因此在 Unreal 中使用 Claude Code 的方式如下：

1. 執行 `unreal-mcp-cli setup-mcp claude-code --path ./YourProject`（或在編輯器中選取 Claude Code 後點擊 **Configure**）。
2. 從專案資料夾啟動 Claude Code。
3. 請它「列出目前關卡中的 actor」，以確認 Unreal 工具可供使用。

你也可以選擇執行 `unreal-mcp-cli setup-skills --path ./YourProject`，它會寫入一個 Claude Code skill（`.claude/skills/unreal-mcp/SKILL.md`），告訴 Claude 如何操作此專案的 MCP 伺服器。

## 其他用戶端

許多用戶端（包括上方未列出的）的現成設定片段都在 [MCP endpoint 頁面](https://ai-game.dev/zh-hant/mcp-endpoint-info)。[生態系總覽](https://ai-game.dev/zh-hant/docs/ecosystem) 說明伺服器、外掛與應用程式如何協同運作。

---

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

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