连接 AI 客户端 — Unity · AI Game Developer Wiki

本页说明 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 介绍了本地服务器设置。

固定 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 中：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），并通过 setup-mcp --token <token> 传入。

请像对待密码一样对待项目密钥和令牌。.mcp.json 之类的文件位于你的项目文件夹中，因此提交前请检查 .gitignore。Authentication 解释了账号侧的相关内容。

受支持的 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。

使用 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 endpoint 页面提供了适用于每个客户端的片段，包括 VS Code 的 servers 格式和 PAT 请求头。

通过 HTTP 使用本地服务器

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

配置之后

重启 AI 客户端，或重新连接其 MCP 服务器，以便它读取新配置。然后按照入门检查连接。如果客户端没有显示任何工具，请参阅故障排查。

两种连接方式#

固定 URL#

登录#

受支持的 AI agent#

使用 unity-mcp-cli 进行配置#

手动配置#

通过 HTTP 使用本地服务器#

通过 stdio 使用本地服务器#

配置之后#

两种连接方式

固定 URL

登录

受支持的 AI agent

使用 unity-mcp-cli 进行配置

手动配置

通过 HTTP 使用本地服务器

通过 stdio 使用本地服务器

配置之后