连接 AI 客户端
通过 ai-game.dev 云端端点或你自己的本地服务器，将 Claude Code、Cursor、Copilot、Codex、Gemini 等 MCP 客户端连接到 Godot MCP。
Godot MCP 有两端，二者都会连接到 MCP 服务器：Godot 编辑器中的插件，以及你与之对话的 AI 客户端。本页说明两种连接模式、登录如何工作，以及如何用 godot-cli setup-mcp 或停靠面板上的 Configure 按钮为每个受支持的 agent 编写 MCP 配置。
云端模式（默认）
在云端模式下，插件连接到 https://ai-game.dev 上托管的后端，你的 AI 客户端连接到 MCP 端点 https://ai-game.dev/mcp。你的机器上无需额外运行任何东西，而且可以跨越防火墙工作。这是默认模式，也是我们推荐给大多数人的模式。
使用设备流程登录
云端身份验证使用 OAuth 2.1 设备授权流程。你永远不需要手动复制令牌：
godot-cli loginCLI 会打印一个短代码，打开你的浏览器并等待你批准。凭据（访问令牌、轮换刷新令牌和过期时间）会保存到机器存储 ~/.ai-game-dev/credentials.json（macOS 和 Linux 上文件模式为 0600，Windows 上由 DPAPI 保护）。编辑器插件、其他引擎 CLI 和 AI Game Dev 应用都会读取它，过期的访问令牌会自动刷新。在停靠面板中点击 Authorize 会从 Godot 内部运行同一流程。
常用的 login 参数：--force 在已有凭据的情况下重新登录，--project <path> 保留一份单独的项目级凭据，--tools-only 为 CI 运行器创建范围更窄的凭据。参见 godot-cli 参考 和 身份验证。
固定项目 URL
普通端点 https://ai-game.dev/mcp 会把你的 agent 路由到你连接的某个编辑器。当同时打开多个项目时这会有歧义，因此 setup-mcp 默认写入固定 URL：https://ai-game.dev/mcp/p/<pin>，其中的 pin 由项目派生而来。用该配置启动的 agent 总能到达此项目的编辑器。如果你想要普通 URL，请传入 --no-pin。
项目密钥
登录后，setup-mcp 会把项目密钥以 Authorization: Bearer agd_pk_… 的形式写入 agent 配置。项目密钥不会过期，且仅对本项目的 pin 有效，因此无法访问你账户下的其他项目。每个项目只创建一次，并从 ~/.ai-game-dev/project-keys.json 复用。
--regenerate-key创建一个新密钥，重写配置并撤销旧密钥。--oauth改为写入仅含 URL 的配置：agent 用自己的 OAuth 提示登录。- 如果没有机器级登录，配置同样仅含 URL。
自定义模式：你自己的服务器
在自定义模式下，插件连接到你自己选择的服务器 URL，例如你自己机器上的服务器。该服务器是开源的 GameDev-MCP-Server，与 Unity MCP 和 Unreal MCP 使用的是同一个二进制文件。
最简单的方式是让插件来运行它：
- 在停靠面板中，将模式切换为 Custom。
- 让 Server URL 保持为
http://localhost:8080，或输入另一个本地 URL。 - 点击 Start Server。插件会从 GitHub（HTTPS，仅限 github.com）下载与其固定服务器版本对应的服务器构建，缓存到
.godot/mcp-server/<platform>/，启动它并连接。
Stop Server 会停止它，关闭编辑器也会停止它。在 CI 环境中会跳过下载。如果你想自己运行服务器，可以下载发布版二进制文件或 aigamedeveloper/mcp-server Docker 镜像：
./gamedev-mcp-server --client-transport streamableHttp --port 8080自定义服务器的授权
自定义模式有一个 Authorization Token 开关，有三种取值：
| 取值 | 含义 |
|---|---|
none | 无身份验证。对于仅监听本机的服务器来说没问题。 |
oauth | 发送你已登录的 ai-game.dev 账户令牌，但只发给 localhost 服务器（localhost、127.0.0.0/8、::1）。 |
token | 一个 bearer 令牌。点击 New 生成一个；它以掩码形式存储。 |
对于任何非本地主机且使用 oauth 的情况，插件会拒绝发送你的账户令牌；请改为设置 GODOT_MCP_TOKEN。两种模式的环境变量列在 配置 中。
要让 agent 指向本地服务器，请把 URL 传给 setup-mcp：
godot-cli setup-mcp claude-code ./MyGodotProject --url http://localhost:8080本地服务器配置从不携带项目密钥。
受支持的 agent 和配置文件
运行 godot-cli setup-mcp --list 可以查看所有 agent id。这些就是当前 CLI 已知的 id，以及它写入配置的位置：
| 智能体 | id | 配置文件 |
|---|---|---|
| Claude Code | claude-code | 项目中的 .mcp.json |
| Claude Desktop | claude-desktop | 使用 Claude 自定义连接器（见下文） |
| 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/config/mcp_config.json 和 ~/.gemini/antigravity/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 |
示例：
godot-cli setup-mcp cursor ./MyGodotProject
godot-cli setup-mcp codex ./MyGodotProject
godot-cli setup-mcp vscode-copilot ./MyGodotProject --oauth每个配置都使用 HTTP 传输（type: http 加一个 URL）。对于 Codex，密钥放在 http_headers 中。
Claude Desktop 和 claude.ai
Claude Desktop 不会从 claude_desktop_config.json 中读取 HTTP 服务器条目。Claude Desktop 和 claude.ai 改为通过 Claude 自定义连接器访问云端端点：在 Claude 的设置中添加自定义连接器，粘贴项目固定的云端 URL，并使用你的 ai-game.dev 账户登录。Claude Desktop 无法使用 Custom 模式的服务器，因为 Godot MCP 没有为其提供 stdio 传输。如需使用本地服务器，请使用表格中支持 HTTP 的智能体，例如 Claude Code。
从停靠面板进行配置
停靠面板中的 AI agent 部分与 setup-mcp 作用相同：从列表中选择你的智能体，然后点击 Configure（或 Reconfigure）。状态行会说明该智能体的配置文件是否已配置好；如果在配置之后更改了服务器 URL、模式或授权信息，就会出现 Reconfiguration Required 提示。Remove 会从该智能体的配置中删除 Godot MCP 条目。
为你的智能体提供技能
有些智能体会读取技能文件（SKILL.md），这些文件教它们如何使用这些工具。AI agent 部分中的 Skills 行可以生成这些文件（Generate，或 Auto-generate 开关）。在终端中：
godot-cli setup-skills claude-code ./MyGodotProject这会把文件写入该智能体的技能文件夹，例如 Claude Code 的 .claude/skills，而且无需运行编辑器。setup-skills --list 会显示哪些智能体支持技能。
可复制粘贴的配置
如果你的客户端不在列表中，任何支持 HTTP 服务器的 MCP 客户端都可以使用：将它指向 https://ai-game.dev/mcp（或固定 URL），让它通过 OAuth 登录，或者添加 bearer 头。许多客户端的现成片段都在 MCP 端点页面 上。