# 连接 AI 客户端 — Unreal Engine · AI Game Developer Wiki

通过 ai-game.dev 云端端点或本地服务器，将 Claude Code、Cursor、Copilot、Codex、Gemini 等 MCP 客户端连接到 Unreal MCP。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/unreal/connecting-ai-clients)。

本页说明 AI 客户端如何连接到你的 Unreal Editor、登录如何工作，以及如何为每个受支持的 agent 编写 MCP 配置。如果你只想走最快的路径，编辑器 **AI agent** 区域中的 **Configure** 按钮（参见[快速开始](https://ai-game.dev/zh-hans/docs/wiki/unreal/getting-started#ai-client)）会替你完成所有这些工作。

## Cloud 或 Custom：选择连接模式

AI Game Developer 窗口的 **Connection** 区域有一个 **Custom / Cloud** 开关。同样的设置是 `UNREAL_MCP_CONNECTION_MODE`（参见[配置](https://ai-game.dev/zh-hans/docs/wiki/unreal/configuration)）。

|  | Cloud（默认） | Custom |
| --- | --- | --- |
| 服务器 | ai-game.dev 上托管的端点 | 你自己运行的 `gamedev-mcp-server`，通常在 `localhost` 上 |
| 登录 | 你的 ai-game.dev 账号，设备码流程 | 可选：无、共享令牌或 OAuth |
| 本地运行的内容 | 编辑器及其桥接程序 | 编辑器、其桥接程序以及本地服务器 |
| 适用场景 | 大多数用户、多台机器、跨防火墙工作 | 完全本地的环境、离线工作、CI |

## Cloud 模式

在 Cloud 模式下，桥接程序连接到 ai-game.dev，你的 AI 客户端连接到同一个端点 `https://ai-game.dev/mcp`。服务器会把客户端的工具调用路由到你的编辑器。关于端点本身，请参见 [MCP 端点页面](https://ai-game.dev/zh-hans/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_…` 请求头。有了它，agent 自身无需登录。该密钥不会过期，可以吊销，并缓存在 `~/.ai-game-dev/project-keys.json` 中，以便项目的每个 agent 复用它。

- `setup-mcp --oauth` 则会写入仅含 URL 的配置；随后由 agent 自行执行 OAuth 登录。
- `setup-mcp --regenerate-key`，或编辑器 AI agent 区域中的 **Regenerate key** 按钮，会创建新密钥、用它重写已配置的 agent，并吊销旧密钥。
- 显式指定的 `--token` 会覆盖以上两者。

如果机器未登录，配置就只包含 URL，由 agent 自行登录。

## 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 模式。给 `unreal-mcp-cli open` 传入 `--host` 会自动选择 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-hans/mcp-endpoint-info)。[生态概览](https://ai-game.dev/zh-hans/docs/ecosystem) 展示了服务器、插件与应用如何协同工作。

---

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

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