配置
在 AI Game Developer 停靠面板中配置 Godot MCP，选择 AI 智能体可见的工具，并用 GODOT_MCP_* 环境变量覆盖设置。
大多数人从不需要修改任何设置：插件以 Cloud 模式启动，在你登录后自动连接，并公开其全部工具。本页介绍在确有需要时你可以更改的内容，包括 AI Game Developer 停靠面板中的设置、已保存的设置，以及用于 CI 和脚本化运行的环境变量。
AI Game Developer 停靠面板
插件会在 Godot 编辑器右上方的停靠区域添加一个名为 AI Game Developer 的停靠面板。从上到下包含以下分区。
标题栏
标题栏显示插件版本和一个 Log Level 选择器。日志级别控制插件及其连接向输出面板打印的信息量（Trace、Debug、Info、Warning、Error、None；默认 Info）。在诊断连接问题时，可将其提高到 Debug 或 Trace。当设置了 GODOT_MCP_LOG_LEVEL 时，该选择器会被禁用，并显示一条说明。
连接
- Cloud / Custom：连接模式。Cloud 连接到 ai-game.dev；Custom 连接到你所选择的服务器 URL。
- Connect / Stop：开始或停止连接 MCP 服务器。插件会在后台持续重试，直到连接成功。
- 在 Cloud 模式下：显示你的登录状态，以及 Authorize（启动浏览器设备登录）和 Sign out。
- 一行三个圆点（Godot、MCP 服务器和 AI 智能体）显示当前已连接的内容。AI 智能体一行按名称列出已连接的客户端，若尚未连接任何客户端则显示“按需连接”。
在 Custom 模式下，MCP server 卡片会新增：
- Server URL：要连接的服务器，默认
http://localhost:8080。 - Authorization Token：
none、oauth（你的 ai-game.dev 账号令牌，仅发送给 localhost 服务器）或token（一个 bearer 令牌；New 会生成一个）。 - Start Server / Stop Server：下载、启动和停止与插件固定服务器版本匹配的本地服务器。参见 连接 AI 客户端。
如果环境变量强制指定了模式或主机，会显示一条黄色提示“Overridden by environment (GODOT_MCP_*)”，此时在停靠面板中所做的更改不会生效。
AI 智能体
选择你使用的 AI 客户端（默认为 Claude Code）。该分区随后显示：
- Skills：智能体技能文件的存放位置，一个在插件加载时刷新这些文件的 Auto-generate 开关，以及一个 Generate 按钮。不支持技能的智能体会显示“此智能体不支持技能”。
- Model Context Protocol (MCP)：智能体的 MCP 配置是否已设置好，附带 Configure / Reconfigure 和 Remove。如果你在配置智能体之后服务器设置发生了变化，会出现 Reconfiguration Required 提示。
MCP 功能
三行分别是 Tools、Prompts 和 Resources，每行显示可见项数量占总数的比例（工具还会显示预估的 token 开销）和一个 Open 按钮。打开的窗口会列出每个条目，每个条目带一个 Visible 开关，并提供一个筛选输入框。
Visible 只决定 MCP 客户端能否在其工具列表中看到该条目。隐藏你不需要的工具可以让智能体的上下文更小。它并非访问控制：如果客户端按名称调用某个隐藏的工具，该工具仍会执行。
扩展
可选 Godot MCP 扩展的列表，带有 Install 和 Update 按钮。它读取嵌入在你 .csproj 中的扩展目录；如果列表为空，请参见 扩展。
页脚
用于获取帮助和报告问题的链接，以及一个 Serialization Check 窗口，显示所选节点或对象为 AI 序列化的方式（在报告 bug 时很有用）。
设置保存在哪里
停靠面板将其设置保存到 user://godot-mcp-config.json，位于 Godot 为该项目的每个用户分配的数据文件夹中（不在项目内部）。它保存连接模式、自定义主机、授权选项、日志级别、所选智能体、工具可见性以及你使用过的令牌。
Cloud 登录凭据单独存放在机器级存储 ~/.ai-game-dev/credentials.json 中，与其他 AI Game Developer 工具共用。智能体配置的项目密钥位于 ~/.ai-game-dev/project-keys.json。
在终端中，godot-cli configure 可列出并更改项目文件 .godot-mcp/features.json 中工具、提示和资源的可见性：
godot-cli configure ./MyGodotProject --list
godot-cli configure ./MyGodotProject --disable-tools script-delete,script-execute
godot-cli configure ./MyGodotProject --enable-all-tools环境变量
环境变量会覆盖已保存的设置，无需编辑任何文件，这在 CI、无头运行和本地开发中非常方便。该插件还会从项目中的 .env 文件读取这些变量；进程环境优先于 .env。
| 变量 | 取值 | 用途 |
|---|---|---|
GODOT_MCP_CONNECTION_MODE | Cloud、Custom | 强制指定连接模式。默认 Cloud。 |
GODOT_MCP_CLOUD_URL | URL | 覆盖云端基础 URL。默认 https://ai-game.dev。 |
GODOT_MCP_HOST | URL | Custom 模式的服务器 URL。默认 http://localhost:8080。 |
GODOT_MCP_AUTH_OPTION | none、oauth、token | Custom 模式的授权方式。 |
GODOT_MCP_TOKEN | string | 当前模式使用的 Bearer 令牌。会覆盖已保存的令牌，且永远不会被写回。 |
GODOT_MCP_LOG_LEVEL | Trace 至 None | 日志详细程度。 |
GODOT_MCP_CREDENTIALS_DIR | absolute path | 使用独立的凭据存储，用于隔离测试。 |
GODOT_MCP_TOOL_FORMAT | Rql、Json | 工具接收参数和返回结果的方式。默认 Rql（紧凑文本）；Json 保留 JSON schema 和结构化结果。 |
GODOT_MCP_SERVER_PATH | absolute path | 仅编辑器：启动这个已有的服务器二进制文件，而不是下载固定版本的发布包。 |
GODOT_MCP_RUNTIME_FROM_EDITOR | 1 | 让通过 Play 启动的游戏也能连接其自带的游戏内 MCP 运行时。 |
示例：启动编辑器并连接本地服务器。
export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:8080
godot --editor --path ./MyGodotProjectgodot-cli open 会通过 --mode、--url、--cloud-url、--token、--auth 和 --log-level 为你设置这些变量。参见 godot-cli 参考。
工具格式
在默认的 Rql 格式下，工具以 RQL 值作为参数（例如 "Level/Player" 这样的节点路径，或 godot.find("Name")），并返回消耗更少 token 的紧凑文本。而 Json 格式（通过 GODOT_MCP_TOOL_FORMAT=Json 或 toolFormat 键设置）则保留完整的 JSON schema 和结构化结果，适合偏好这种方式的客户端。关于 RQL 的更多内容：工具。