连接 AI 客户端
通过 ai-game.dev 云端端点或本地服务器，将 Claude Code、Cursor、Copilot、Codex、Gemini 等 MCP 客户端连接到 Unreal MCP。
本页说明 AI 客户端如何连接到你的 Unreal Editor、登录如何工作，以及如何为每个受支持的 agent 编写 MCP 配置。如果你只想走最快的路径，编辑器 AI agent 区域中的 Configure 按钮（参见快速开始）会替你完成所有这些工作。
Cloud 或 Custom：选择连接模式
AI Game Developer 窗口的 Connection 区域有一个 Custom / Cloud 开关。同样的设置是 UNREAL_MCP_CONNECTION_MODE（参见配置）。
| 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 端点页面。
使用设备码流程登录
每台机器只需登录一次。以下任一方式都可以，并且它们与应用程序、其他引擎插件以及各个 CLI 共用同一个凭据存储（~/.ai-game-dev/credentials.json）：
- 在编辑器中：选择 Cloud，点击 Authorize，打开验证页面，输入窗口中显示的用户码并批准。
- 在终端中：
unreal-mcp-cli login。 - 在 AI Game Dev 应用中：照常登录。
警告： 编辑器中的 Revoke 会注销整台机器，而不只是这个项目。编辑器会先请求确认，因为所有共享该凭据的 AI Game Dev 工具（引擎插件、CLI 和桌面应用）都会被注销。
关于账号、设备和令牌如何工作，请参见身份验证页面。
项目固定 URL
如果你的账号连接了多个编辑器，使用普通 https://ai-game.dev/mcp URL 的客户端可能会连到错误的那一个。因此，插件和 unreal-mcp-cli setup-mcp 默认会写入一个项目固定的 URL：
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 无需任何配置就能达成一致。
要从编辑器中启动它：
- 将 Connection 区域切换为 Custom。
- 在 MCP server 卡片中，选择 http 传输方式并点击 Start。如果缺少固定版本的服务器发行包，编辑器会下载它，然后启动它，并在编辑器退出时停止它。Start 按钮仅在 Custom 模式和 http 传输方式下可用。
- 选择一种 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）。
# 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 时：
- 运行
unreal-mcp-cli setup-mcp claude-code --path ./YourProject（或在编辑器中选择 Claude Code 后点击 Configure）。 - 从项目文件夹启动 Claude Code。
- 让它“列出当前关卡中的 actor”以确认 Unreal 工具可用。
可选地，运行 unreal-mcp-cli setup-skills --path ./YourProject 会写入一个 Claude Code skill（.claude/skills/unreal-mcp/SKILL.md），告诉 Claude 如何驱动本项目的 MCP 服务器。
其他客户端
许多客户端的现成配置片段（包括上面未列出的客户端）位于 MCP endpoint 页面。生态概览 展示了服务器、插件与应用如何协同工作。