# 连接 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` 或手动配置每个受支持的 agent。

## 两种连接方式

你的 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-hans/docs/wiki/unity/configuration#connection-modes) 介绍了本地服务器设置。

## 固定 URL

基础端点 `https://ai-game.dev/mcp` 会按回退规则路由到你已连接的某个编辑器。在只打开一个项目时这没问题，但有多个项目时会产生歧义。

**固定** URL `https://ai-game.dev/mcp/p/<pin>` 始终路由到某个项目的 Editor。pin 由项目的标识派生而来。窗口中的 **Configure** 按钮和 `unity-mcp-cli setup-mcp` 默认写入固定 URL；`setup-mcp --no-pin` 则写入基础 URL。对于 stdio 传输方式，pin 以 `project=<pin>` 参数传递。

## 登录

Editor、CLI 和桌面应用共享位于 `~/.ai-game-dev/credentials.json` 的机器级登录信息。在任意一处登录一次即可：

- 在窗口中：切换到 Cloud 模式，然后点击 **Authorize**，再在浏览器中确认代码。
- 在终端中：`unity-mcp-cli login`。
- 在 [AI Game Dev app](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` 时会得到这种形式。
- **个人访问令牌（Personal Access Token）。** 对于 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 agent

窗口中的 **AI agent** 下拉列表列出了这些配置器。**Configure** 会写入所示的文件；**Remove** 会把该条目移除。

| Agent | 写入的配置文件 | CLI id |
| --- | --- | --- |
| 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` |
| Other - Custom | 显示可复制的 JSON | `custom` |

相对路径位于你的 Unity 项目内。服务器条目始终命名为 `ai-game-developer`。运行 `unity-mcp-cli setup-mcp --list` 可查看你的 CLI 版本支持的 id。

**提示**

Claude Desktop 和 Unity AI 不使用生成的 skills，而 Custom 条目可以让你选择 skills 文件夹。对于其他 agent，还要开启 **Skills > Auto-generate**（或运行 `setup-skills`），这样 agent 才能学习 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-hans/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 endpoint 页面](https://ai-game.dev/zh-hans/mcp-endpoint-info) 提供了适用于每个客户端的片段，包括 VS Code 的 `servers` 格式和 PAT 请求头。

### 通过 HTTP 使用本地服务器

在 Custom 模式且使用 HTTP 传输时，将客户端指向本地服务器。端口就是窗口中 **Server URL** 里的端口；窗口中为你的 agent 显示的手动配置步骤包含确切的 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>` 替换为窗口中的端口。同一时间只能有一个 agent 使用 stdio 服务器，并且窗口的 Start/Stop 按钮处于禁用状态，因为该进程归 agent 所有。除非你的客户端不支持 HTTP，否则优先使用 HTTP。

## 配置之后

重启 AI 客户端，或重新连接其 MCP 服务器，以便它读取新配置。然后按照 [入门](https://ai-game.dev/zh-hans/docs/wiki/unity/getting-started#verify) 检查连接。如果客户端没有显示任何工具，请参阅 [故障排查](https://ai-game.dev/zh-hans/docs/wiki/unity/troubleshooting#no-tools)。

---

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

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