MCP for Unity 安全策略与实践指南漏洞上报、fail-closed 网络默认值与远程认证加固【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp导读本文基于 SECURITY.md 安全策略文档系统梳理 MCP for UnityUnity MCP的安全模型、漏洞上报流程、受支持版本策略以及默认安全fail-closed的网络设计原则。结合仓库中的 C# 安全策略实现HttpEndpointUtility、EditorPrefKeys、Python 服务端认证架构与配套测试用例你将掌握该开源项目如何守住编辑器与 AI 助手之间的信任边界以及在生产/远程部署场景下如何正确配置 API Key 认证与网络安全开关。读完本文你既能按规范向维护者提交安全漏洞也能像安全工程师一样评估和加固自己的 MCP for Unity 部署。一、安全模型概述一个桥梁项目的威胁边界Unity MCP 的本质是 AI 助手与 Unity Editor 之间的桥梁它给 LLM 提供管理资源、控制场景、编辑脚本、自动化任务的工具集。正因如此这个桥梁一旦被滥用攻击面会直接延伸到编辑器内执行的任意代码工具调用链路项目文件系统的读写远程服务器上的身份认证与会话隔离日志、遥测、错误响应中的凭据泄露。仓库安全策略给出的核心立场是该产品默认采取fail-closed故障即关闭原则——凡是未显式开启的安全敏感能力一律默认拒绝。这一点在 SECURITY.md 的 Network Defaults (Safe by Default) 一节中明确声明并直接映射到 HttpEndpointUtility.cs 与 EditorPrefKeys.cs 的具体实现。二、漏洞上报流程Reporting a Vulnerability2.1 上报渠道项目明确要求不要通过公开的 GitHub issues 提交安全漏洞。正确渠道是邮件上报至securitycoplay.dev。2.2 上报信息清单为了让维护者快速定位与复现邮件中应包含信息项说明问题描述清晰、无歧义地描述漏洞现象复现步骤 / PoC可复现的最小步骤或概念验证代码受影响版本UPM 包Unity 侧与 Python server服务端的版本号运行环境操作系统、Unity Editor 版本、MCP 客户端类型建议修复可选你倾向的修复思路2.3 响应时效SLA3 个工作日内确认收到报告10 个工作日内给出初步评估结论关键漏洞critical会以 patch 版本同时发布到main与 beta 通道。从源码结构看版本相关的检查与升级链路由 PackageUpdateService.cs 等维护漏洞修复以 patch 发布的方式可确保升级成本最低。三、受支持版本Supported Versions版本支持状态latestmain支持latest betabeta支持更早版本不支持请升级安全策略非常明确只有最新稳定版与最新 beta 版处于安全维护窗口内旧版本不受安全支持。这意味着部署时应当跟踪main或beta通道的更新而不是长期停留在历史版本。四、网络默认值Fail-Closed 的两个关键开关SECURITY.md 声明了三条网络底线这里逐条结合源码剖析其真实行为。4.1 HTTP Local 默认只绑定回环地址HTTP Local默认仅绑定回环地址127.0.0.1、localhost、::1。绑定所有网卡LAN bind0.0.0.0、::需要通过高级设置中的Allow LAN Bind (HTTP Local)显式开启。在 HttpEndpointUtility.cs 中AllowLanHttpBind()直接读取EditorPrefKeys.AllowLanHttpBind值为MCPForUnity.Security.AllowLanHttpBind见 EditorPrefKeys.cs默认false。真正的拦截逻辑在IsHttpLocalUrlAllowedForLaunch()HttpEndpointUtility.cs主机名是回环地址localhost/127.0.0.1/::1→ 放行主机名是绑定所有网卡地址0.0.0.0/::→ 仅当AllowLanHttpBind()为 true 时才放行否则返回错误Binding to all interfaces (0.0.0.0/::) is disabled by default. Enable Allow LAN bind for HTTP Local in Advanced Settings to opt in.其他任何主机名 → 一律拒绝要求使用回环 URL。配套的工具提示McpAdvancedSection.cs给出了明确的警告语义Allow HTTP Local to bind on all interfaces (0.0.0.0 / ::). Disabled by default because devices on your LAN may reach MCP tools.也就是说一旦开启 LAN Bind局域网内其他设备就可能触达 MCP 工具——这正是该开关默认关闭的原因。UI 上的开关定义在 McpAdvancedSection.uxml。4.2 HTTP Remote 默认强制 HTTPSHTTP Remote默认要求https://。远程端点使用明文http://需要通过Allow Insecure Remote HTTP显式开启。对应实现为IsRemoteUrlAllowed()HttpEndpointUtility.cshttps://协议 → 直接放行http://协议 → 仅当AllowInsecureRemoteHttp()读取MCPForUnity.Security.AllowInsecureRemoteHttp见 EditorPrefKeys.cs为 true 时放行否则返回HTTP Remote requires HTTPS by default. Enable Allow insecure HTTP for HTTP Remote in Advanced Settings to opt in.其他协议 → 一律拒绝。此外还有一个细节远程 URL 保存时会做归一化处理未显式写协议时自动补全为https://。测试 ServerManagementServiceCharacterizationTests.cs 中的SaveRemoteBaseUrl_WithoutScheme_DefaultsToHttps用例验证了这一点输入example.com:9000归一化结果即为https://example.com:9000。4.3 测试用例对 fail-closed 语义的背书仓库在 ServerManagementServiceCharacterizationTests.cs 中为这两条安全策略专门建立了测试区域HttpEndpointUtility Security Policy TestsIsRemoteUrlAllowed_Http_DisallowedByDefault未开启开关时http://example.com:8080被拒绝且错误信息包含 HTTPS 提示IsRemoteUrlAllowed_Http_AllowedWithOptIn开启AllowInsecureRemoteHttp后放行IsHttpLocalUrlAllowedForLaunch_ZeroBind_DisallowedByDefault未开启 LAN Bind 时绑定0.0.0.0的启动被拒绝。这些测试将安全策略固化为可回归的行为契约如果你没主动拨动开关服务器就拒绝不安全的配置与 transports.md 中 both guards are fail-closed 的表述一致。4.4 操作路径在哪里开启这两个开关在 Unity Editor 中打开Window → MCP for Unity窗口进入高级设置面板Advanced Settings即可看到两个 ToggleMcpAdvancedSection.uxml开关对应 EditorPrefs 键默认值风险提示Allow LAN Bind (HTTP Local)MCPForUnity.Security.AllowLanHttpBindfalseLAN 内设备可能触达 MCP 工具Allow Insecure Remote HTTPMCPForUnity.Security.AllowInsecureRemoteHttpfalse远程流量以明文 HTTP/WS 传输这两个键都归在MCPForUnity.Security.*命名空间下集中管理体现了安全相关配置独立命名、便于审计的设计意图。五、远程托管模式API Key 认证Remote Server AuthSECURITY.md 明确远程托管模式必须启用 API Key 认证。这是该文档中提到的最复杂的防御能力仓库用一套完整的服务端实现支撑详见 remote-server-auth.md使用指南与 remote-auth.md架构设计。5.1 工作原理一句话服务器不自行管理密钥而是把密钥校验委托给外部 HTTP 认证服务MCP 客户端在每次请求中携带X-API-Key请求头服务端中间件拦截所有工具/资源调用向认证端点提交{api_key: ...}换取user_id再以user_id作为会话隔离的维度。5.2 服务端启动参数与环境变量CLI 参数环境变量默认值说明--http-remote-hostedUNITY_MCP_HTTP_REMOTE_HOSTEDfalse启用远程托管模式必须配合 API Key 认证--api-key-validation-url URLUNITY_MCP_API_KEY_VALIDATION_URL无外部密钥校验端点必填--api-key-login-url URLUNITY_MCP_API_KEY_LOGIN_URL无用户获取/管理密钥的登录页地址--api-key-cache-ttl SECONDSUNITY_MCP_API_KEY_CACHE_TTL300校验结果的缓存时长秒--api-key-service-token-header HEADERUNITY_MCP_API_KEY_SERVICE_TOKEN_HEADER无服务端到认证服务的鉴权头名称--api-key-service-token TOKENUNITY_MCP_API_KEY_SERVICE_TOKEN无服务端到认证服务的鉴权令牌环境变量仅在对应 CLI 参数未提供时生效布尔型环境变量取true、1、yes视为开启。启动校验若--http-remote-hosted已设置但未提供校验 URLCLI 与环境变量均未设置服务器会记录错误并以退出码 1 终止启动——启动即 fail-closed 的又一体现。命令行示例python -m src.main \ --transport http \ --http-host 0.0.0.0 \ --http-port 8080 \ --http-remote-hosted \ --api-key-validation-url https://auth.example.com/api/validate-key \ --api-key-login-url https://app.example.com/api-keys \ --api-key-cache-ttl 120环境变量等价形式export UNITY_MCP_TRANSPORThttp export UNITY_MCP_HTTP_HOST0.0.0.0 export UNITY_MCP_HTTP_PORT8080 export UNITY_MCP_HTTP_REMOTE_HOSTEDtrue export UNITY_MCP_API_KEY_VALIDATION_URLhttps://auth.example.com/api/validate-key export UNITY_MCP_API_KEY_LOGIN_URLhttps://app.example.com/api-keys python -m src.main服务端到认证服务鉴权可选但强烈推荐如果你的认证服务要求服务器自证身份可配置服务令牌服务器会在每次校验请求中附加该请求头--api-key-service-token-header X-Service-Token \ --api-key-service-token your-server-secret5.3 校验契约Validation Contract请求POST api-key-validation-url Content-Type: application/json { api_key: the-api-key }若配置了服务令牌则额外携带service-token-header: service-token-value。有效密钥响应{ valid: true, user_id: user-abc-123, metadata: {} }validbool必填必须为trueuser_idstring必填稳定用户标识用于会话隔离metadataobject可选附加元数据。无效密钥响应{ valid: false, error: API key expired }HTTP401状态码同样按无效密钥处理无需解析响应体。超时与重试策略源码常量见 api_key_service.py请求超时 5 秒超时与连接错误重试 1 次100ms 退避任何错误默认拒绝deny by default。5xx、超时、网络错误等瞬时故障不进入缓存后续请求会重新探测认证服务。5.4 WebSocket 认证门槛Unity 插件接入侧Unity 插件通过 WebSocket/hub/plugin连接服务器时握手阶段即校验 API Key实现位于 plugin_hub.py场景WebSocket 关闭码原因缺少 API Key 请求头4401API key requiredAPI Key 无效4403Invalid API key认证服务不可用1013Try again laterAPI Key 有效连接接受user_id存入连接状态5.5 会话隔离与行为变化启用--http-remote-hosted后服务端行为相比本地模式发生多处收紧全量认证所有 MCP 工具/资源调用必须携带有效X-API-Key缺失或无效时中间件抛出RuntimeError以 MCP 错误响应返回会话隔离每个用户只能看到并操作自己的 Unity 实例。set_active_instance、实例列表均按user_id过滤——两个用户操作同一克隆仓库相同project_hash也会得到独立的会话双索引注册表实现见 plugin_registry.py 的_user_hash_to_session关闭自动选择本地模式下服务器会自动选中唯一连接的 Unity 实例远程托管模式下该行为被禁用用户必须显式调用set_active_instance并传入Namehash禁用 CLI 路由POST /api/command、GET /api/instances、GET /api/custom-tools三个无认证层保护的 REST 端点在远程托管模式下被关闭始终可用端点GET /health负载均衡/监控探活与GET /api/auth/login-url返回密钥管理登录地址不受认证影响。会话密钥的推导优先级为client_iduser:{user_id}global其中user:{user_id}兜底机制确保在 MCP 传输层不提供稳定 client_id 时不同用户依然不会共享实例选择状态。5.6 客户端与 Unity 插件配置Unity 插件侧连接远程服务器在 MCP for Unity 窗口中切换为HTTP Remote模式 → 填写 API Key存入 EditorPrefs按机器持久化不入版本库→ 可通过Get API Key按钮打开登录 URL 获取新密钥。该端点从服务器/api/auth/login-url拉取。MCP 客户端侧插件配置器会自动在生成的配置中注入X-API-Key请求头。例如 Cursor~/.cursor/mcp.json{ mcpServers: { mcp-for-unity: { url: http://remote-server:8080/mcp, headers: { X-API-Key: your-api-key } } } }Claude CodeCLIclaude mcp add --transport http mcp-for-unity http://remote-server:8080/mcp \ --header X-API-Key: your-api-key5.7 缓存与密钥吊销延迟api_key_service.py 以内存字典缓存校验结果api_key - (valid, user_id, metadata, expires_at)受asyncio.Lock保护。响应是否缓存原因200 valid: true是确定性有效结果200 valid: false是确定性无效结果401 状态码是确定性拒绝5xx / 超时 / 连接错误 / 异常否瞬时故障下次请求重试因此密钥吊销/轮换后旧密钥最长还能存活一个--api-key-cache-ttl默认 300 秒。需要更快吊销就调低 TTL代价是更频繁的认证请求。密钥脱敏日志中从不输出完整密钥长度超过 8 字符的密钥在日志里统一脱敏为xxxx...yyyy形式。六、什么算安全漏洞What Counts as a Security Issue符合以下任一情形的属于安全漏洞范畴应当走私密上报渠道通过精心构造的 MCP 消息实现远程代码执行远程托管服务器上的认证绕过对 Unity 项目根目录之外的文件系统读写发出逃逸配置白名单的网络请求凭据或 API Key 在日志、遥测或错误响应中泄露。特别值得注意的是第 3、4 条它们把越界访问访问项目根目录以外的文件、向白名单以外的主机发起请求本身定义为漏洞类别呼应了 fail-closed 的整体设计——任何绕过内置防护的方式都值得私密上报。七、什么不算安全漏洞What Doesnt Count以下三类不在安全漏洞范围内上报前请自行甄别工具的正常功能工具有意修改 Unity 项目如管理资源、编辑脚本属于产品设计不算漏洞需要攻击者已拥有宿主机 shell 权限的问题——那已经不是 MCP 的攻击面第三方依赖自身的漏洞请先向上游项目上报维护者会在上游修复后更新依赖锁定版本。八、披露时间线Disclosure Timeline修复发布后维护者会在 GitHub 的 Security 标签页发布安全公告security advisory并在对方同意的前提下对上报者致谢。也就是说上报→确认3 个工作日→初步评估10 个工作日→修复发布关键问题同时进main与 beta 的 patch→公开安全公告与致谢。九、部署安全自查清单结合以上内容给出可操作的加固检查项本地开发确认 HTTP Local 保持回环绑定不要随意打开 Allow LAN Bind除非确实需要局域网共享远程部署务必使用 HTTPShttps://URL 或让归一化逻辑自动补全不要为了省事开启 Allow Insecure Remote HTTP远程托管必须配置--http-remote-hosted与--api-key-validation-url否则启动失败并强烈建议配置 service token 实现服务器与认证服务双向鉴权会话隔离确认 Unity 插件 WebSocket 与 MCP 客户端使用解析到同一user_id的 API Key否则会出现看不到自己的 Unity 实例的隔离问题密钥轮换轮换密钥后为吊销生效留出--api-key-cache-ttl的时间窗口版本跟进只使用main或 beta 最新版本旧版本不在安全支持范围内日志审计排查日志中是否存在密钥明文正常实现下超过 8 字符的密钥应显示为xxxx...yyyy脱敏形式。十、继续深入关键文件索引主题仓库路径安全策略原始文档SECURITY.mdHTTP 安全策略实现回环判断、URL 校验MCPForUnity/Editor/Helpers/HttpEndpointUtility.cs安全配置 EditorPrefs 键MCPForUnity/Editor/Constants/EditorPrefKeys.cs高级设置 UILAN Bind / Insecure HTTP 开关MCPForUnity/Editor/Windows/Components/Advanced/McpAdvancedSection.uxml、MCPForUnity/Editor/Windows/Components/Advanced/McpAdvancedSection.cs安全策略回归测试TestProjects/UnityMCPTests/Assets/Tests/EditMode/Services/Characterization/ServerManagementServiceCharacterizationTests.cs远程认证使用指南website/docs/guides/remote-server-auth.md远程认证架构设计website/docs/architecture/remote-auth.mdAPI Key 校验服务实现Server/src/services/api_key_service.pyWebSocket 认证门槛Server/src/transport/plugin_hub.py会话隔离双索引注册表Server/src/transport/plugin_registry.py传输模式与网络安全说明website/docs/architecture/transports.md【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MCP for Unity 安全策略与实践指南：漏洞上报、fail-closed 网络默认值与远程认证加固
MCP for Unity 安全策略与实践指南漏洞上报、fail-closed 网络默认值与远程认证加固【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp导读本文基于 SECURITY.md 安全策略文档系统梳理 MCP for UnityUnity MCP的安全模型、漏洞上报流程、受支持版本策略以及默认安全fail-closed的网络设计原则。结合仓库中的 C# 安全策略实现HttpEndpointUtility、EditorPrefKeys、Python 服务端认证架构与配套测试用例你将掌握该开源项目如何守住编辑器与 AI 助手之间的信任边界以及在生产/远程部署场景下如何正确配置 API Key 认证与网络安全开关。读完本文你既能按规范向维护者提交安全漏洞也能像安全工程师一样评估和加固自己的 MCP for Unity 部署。一、安全模型概述一个桥梁项目的威胁边界Unity MCP 的本质是 AI 助手与 Unity Editor 之间的桥梁它给 LLM 提供管理资源、控制场景、编辑脚本、自动化任务的工具集。正因如此这个桥梁一旦被滥用攻击面会直接延伸到编辑器内执行的任意代码工具调用链路项目文件系统的读写远程服务器上的身份认证与会话隔离日志、遥测、错误响应中的凭据泄露。仓库安全策略给出的核心立场是该产品默认采取fail-closed故障即关闭原则——凡是未显式开启的安全敏感能力一律默认拒绝。这一点在 SECURITY.md 的 Network Defaults (Safe by Default) 一节中明确声明并直接映射到 HttpEndpointUtility.cs 与 EditorPrefKeys.cs 的具体实现。二、漏洞上报流程Reporting a Vulnerability2.1 上报渠道项目明确要求不要通过公开的 GitHub issues 提交安全漏洞。正确渠道是邮件上报至securitycoplay.dev。2.2 上报信息清单为了让维护者快速定位与复现邮件中应包含信息项说明问题描述清晰、无歧义地描述漏洞现象复现步骤 / PoC可复现的最小步骤或概念验证代码受影响版本UPM 包Unity 侧与 Python server服务端的版本号运行环境操作系统、Unity Editor 版本、MCP 客户端类型建议修复可选你倾向的修复思路2.3 响应时效SLA3 个工作日内确认收到报告10 个工作日内给出初步评估结论关键漏洞critical会以 patch 版本同时发布到main与 beta 通道。从源码结构看版本相关的检查与升级链路由 PackageUpdateService.cs 等维护漏洞修复以 patch 发布的方式可确保升级成本最低。三、受支持版本Supported Versions版本支持状态latestmain支持latest betabeta支持更早版本不支持请升级安全策略非常明确只有最新稳定版与最新 beta 版处于安全维护窗口内旧版本不受安全支持。这意味着部署时应当跟踪main或beta通道的更新而不是长期停留在历史版本。四、网络默认值Fail-Closed 的两个关键开关SECURITY.md 声明了三条网络底线这里逐条结合源码剖析其真实行为。4.1 HTTP Local 默认只绑定回环地址HTTP Local默认仅绑定回环地址127.0.0.1、localhost、::1。绑定所有网卡LAN bind0.0.0.0、::需要通过高级设置中的Allow LAN Bind (HTTP Local)显式开启。在 HttpEndpointUtility.cs 中AllowLanHttpBind()直接读取EditorPrefKeys.AllowLanHttpBind值为MCPForUnity.Security.AllowLanHttpBind见 EditorPrefKeys.cs默认false。真正的拦截逻辑在IsHttpLocalUrlAllowedForLaunch()HttpEndpointUtility.cs主机名是回环地址localhost/127.0.0.1/::1→ 放行主机名是绑定所有网卡地址0.0.0.0/::→ 仅当AllowLanHttpBind()为 true 时才放行否则返回错误Binding to all interfaces (0.0.0.0/::) is disabled by default. Enable Allow LAN bind for HTTP Local in Advanced Settings to opt in.其他任何主机名 → 一律拒绝要求使用回环 URL。配套的工具提示McpAdvancedSection.cs给出了明确的警告语义Allow HTTP Local to bind on all interfaces (0.0.0.0 / ::). Disabled by default because devices on your LAN may reach MCP tools.也就是说一旦开启 LAN Bind局域网内其他设备就可能触达 MCP 工具——这正是该开关默认关闭的原因。UI 上的开关定义在 McpAdvancedSection.uxml。4.2 HTTP Remote 默认强制 HTTPSHTTP Remote默认要求https://。远程端点使用明文http://需要通过Allow Insecure Remote HTTP显式开启。对应实现为IsRemoteUrlAllowed()HttpEndpointUtility.cshttps://协议 → 直接放行http://协议 → 仅当AllowInsecureRemoteHttp()读取MCPForUnity.Security.AllowInsecureRemoteHttp见 EditorPrefKeys.cs为 true 时放行否则返回HTTP Remote requires HTTPS by default. Enable Allow insecure HTTP for HTTP Remote in Advanced Settings to opt in.其他协议 → 一律拒绝。此外还有一个细节远程 URL 保存时会做归一化处理未显式写协议时自动补全为https://。测试 ServerManagementServiceCharacterizationTests.cs 中的SaveRemoteBaseUrl_WithoutScheme_DefaultsToHttps用例验证了这一点输入example.com:9000归一化结果即为https://example.com:9000。4.3 测试用例对 fail-closed 语义的背书仓库在 ServerManagementServiceCharacterizationTests.cs 中为这两条安全策略专门建立了测试区域HttpEndpointUtility Security Policy TestsIsRemoteUrlAllowed_Http_DisallowedByDefault未开启开关时http://example.com:8080被拒绝且错误信息包含 HTTPS 提示IsRemoteUrlAllowed_Http_AllowedWithOptIn开启AllowInsecureRemoteHttp后放行IsHttpLocalUrlAllowedForLaunch_ZeroBind_DisallowedByDefault未开启 LAN Bind 时绑定0.0.0.0的启动被拒绝。这些测试将安全策略固化为可回归的行为契约如果你没主动拨动开关服务器就拒绝不安全的配置与 transports.md 中 both guards are fail-closed 的表述一致。4.4 操作路径在哪里开启这两个开关在 Unity Editor 中打开Window → MCP for Unity窗口进入高级设置面板Advanced Settings即可看到两个 ToggleMcpAdvancedSection.uxml开关对应 EditorPrefs 键默认值风险提示Allow LAN Bind (HTTP Local)MCPForUnity.Security.AllowLanHttpBindfalseLAN 内设备可能触达 MCP 工具Allow Insecure Remote HTTPMCPForUnity.Security.AllowInsecureRemoteHttpfalse远程流量以明文 HTTP/WS 传输这两个键都归在MCPForUnity.Security.*命名空间下集中管理体现了安全相关配置独立命名、便于审计的设计意图。五、远程托管模式API Key 认证Remote Server AuthSECURITY.md 明确远程托管模式必须启用 API Key 认证。这是该文档中提到的最复杂的防御能力仓库用一套完整的服务端实现支撑详见 remote-server-auth.md使用指南与 remote-auth.md架构设计。5.1 工作原理一句话服务器不自行管理密钥而是把密钥校验委托给外部 HTTP 认证服务MCP 客户端在每次请求中携带X-API-Key请求头服务端中间件拦截所有工具/资源调用向认证端点提交{api_key: ...}换取user_id再以user_id作为会话隔离的维度。5.2 服务端启动参数与环境变量CLI 参数环境变量默认值说明--http-remote-hostedUNITY_MCP_HTTP_REMOTE_HOSTEDfalse启用远程托管模式必须配合 API Key 认证--api-key-validation-url URLUNITY_MCP_API_KEY_VALIDATION_URL无外部密钥校验端点必填--api-key-login-url URLUNITY_MCP_API_KEY_LOGIN_URL无用户获取/管理密钥的登录页地址--api-key-cache-ttl SECONDSUNITY_MCP_API_KEY_CACHE_TTL300校验结果的缓存时长秒--api-key-service-token-header HEADERUNITY_MCP_API_KEY_SERVICE_TOKEN_HEADER无服务端到认证服务的鉴权头名称--api-key-service-token TOKENUNITY_MCP_API_KEY_SERVICE_TOKEN无服务端到认证服务的鉴权令牌环境变量仅在对应 CLI 参数未提供时生效布尔型环境变量取true、1、yes视为开启。启动校验若--http-remote-hosted已设置但未提供校验 URLCLI 与环境变量均未设置服务器会记录错误并以退出码 1 终止启动——启动即 fail-closed 的又一体现。命令行示例python -m src.main \ --transport http \ --http-host 0.0.0.0 \ --http-port 8080 \ --http-remote-hosted \ --api-key-validation-url https://auth.example.com/api/validate-key \ --api-key-login-url https://app.example.com/api-keys \ --api-key-cache-ttl 120环境变量等价形式export UNITY_MCP_TRANSPORThttp export UNITY_MCP_HTTP_HOST0.0.0.0 export UNITY_MCP_HTTP_PORT8080 export UNITY_MCP_HTTP_REMOTE_HOSTEDtrue export UNITY_MCP_API_KEY_VALIDATION_URLhttps://auth.example.com/api/validate-key export UNITY_MCP_API_KEY_LOGIN_URLhttps://app.example.com/api-keys python -m src.main服务端到认证服务鉴权可选但强烈推荐如果你的认证服务要求服务器自证身份可配置服务令牌服务器会在每次校验请求中附加该请求头--api-key-service-token-header X-Service-Token \ --api-key-service-token your-server-secret5.3 校验契约Validation Contract请求POST api-key-validation-url Content-Type: application/json { api_key: the-api-key }若配置了服务令牌则额外携带service-token-header: service-token-value。有效密钥响应{ valid: true, user_id: user-abc-123, metadata: {} }validbool必填必须为trueuser_idstring必填稳定用户标识用于会话隔离metadataobject可选附加元数据。无效密钥响应{ valid: false, error: API key expired }HTTP401状态码同样按无效密钥处理无需解析响应体。超时与重试策略源码常量见 api_key_service.py请求超时 5 秒超时与连接错误重试 1 次100ms 退避任何错误默认拒绝deny by default。5xx、超时、网络错误等瞬时故障不进入缓存后续请求会重新探测认证服务。5.4 WebSocket 认证门槛Unity 插件接入侧Unity 插件通过 WebSocket/hub/plugin连接服务器时握手阶段即校验 API Key实现位于 plugin_hub.py场景WebSocket 关闭码原因缺少 API Key 请求头4401API key requiredAPI Key 无效4403Invalid API key认证服务不可用1013Try again laterAPI Key 有效连接接受user_id存入连接状态5.5 会话隔离与行为变化启用--http-remote-hosted后服务端行为相比本地模式发生多处收紧全量认证所有 MCP 工具/资源调用必须携带有效X-API-Key缺失或无效时中间件抛出RuntimeError以 MCP 错误响应返回会话隔离每个用户只能看到并操作自己的 Unity 实例。set_active_instance、实例列表均按user_id过滤——两个用户操作同一克隆仓库相同project_hash也会得到独立的会话双索引注册表实现见 plugin_registry.py 的_user_hash_to_session关闭自动选择本地模式下服务器会自动选中唯一连接的 Unity 实例远程托管模式下该行为被禁用用户必须显式调用set_active_instance并传入Namehash禁用 CLI 路由POST /api/command、GET /api/instances、GET /api/custom-tools三个无认证层保护的 REST 端点在远程托管模式下被关闭始终可用端点GET /health负载均衡/监控探活与GET /api/auth/login-url返回密钥管理登录地址不受认证影响。会话密钥的推导优先级为client_iduser:{user_id}global其中user:{user_id}兜底机制确保在 MCP 传输层不提供稳定 client_id 时不同用户依然不会共享实例选择状态。5.6 客户端与 Unity 插件配置Unity 插件侧连接远程服务器在 MCP for Unity 窗口中切换为HTTP Remote模式 → 填写 API Key存入 EditorPrefs按机器持久化不入版本库→ 可通过Get API Key按钮打开登录 URL 获取新密钥。该端点从服务器/api/auth/login-url拉取。MCP 客户端侧插件配置器会自动在生成的配置中注入X-API-Key请求头。例如 Cursor~/.cursor/mcp.json{ mcpServers: { mcp-for-unity: { url: http://remote-server:8080/mcp, headers: { X-API-Key: your-api-key } } } }Claude CodeCLIclaude mcp add --transport http mcp-for-unity http://remote-server:8080/mcp \ --header X-API-Key: your-api-key5.7 缓存与密钥吊销延迟api_key_service.py 以内存字典缓存校验结果api_key - (valid, user_id, metadata, expires_at)受asyncio.Lock保护。响应是否缓存原因200 valid: true是确定性有效结果200 valid: false是确定性无效结果401 状态码是确定性拒绝5xx / 超时 / 连接错误 / 异常否瞬时故障下次请求重试因此密钥吊销/轮换后旧密钥最长还能存活一个--api-key-cache-ttl默认 300 秒。需要更快吊销就调低 TTL代价是更频繁的认证请求。密钥脱敏日志中从不输出完整密钥长度超过 8 字符的密钥在日志里统一脱敏为xxxx...yyyy形式。六、什么算安全漏洞What Counts as a Security Issue符合以下任一情形的属于安全漏洞范畴应当走私密上报渠道通过精心构造的 MCP 消息实现远程代码执行远程托管服务器上的认证绕过对 Unity 项目根目录之外的文件系统读写发出逃逸配置白名单的网络请求凭据或 API Key 在日志、遥测或错误响应中泄露。特别值得注意的是第 3、4 条它们把越界访问访问项目根目录以外的文件、向白名单以外的主机发起请求本身定义为漏洞类别呼应了 fail-closed 的整体设计——任何绕过内置防护的方式都值得私密上报。七、什么不算安全漏洞What Doesnt Count以下三类不在安全漏洞范围内上报前请自行甄别工具的正常功能工具有意修改 Unity 项目如管理资源、编辑脚本属于产品设计不算漏洞需要攻击者已拥有宿主机 shell 权限的问题——那已经不是 MCP 的攻击面第三方依赖自身的漏洞请先向上游项目上报维护者会在上游修复后更新依赖锁定版本。八、披露时间线Disclosure Timeline修复发布后维护者会在 GitHub 的 Security 标签页发布安全公告security advisory并在对方同意的前提下对上报者致谢。也就是说上报→确认3 个工作日→初步评估10 个工作日→修复发布关键问题同时进main与 beta 的 patch→公开安全公告与致谢。九、部署安全自查清单结合以上内容给出可操作的加固检查项本地开发确认 HTTP Local 保持回环绑定不要随意打开 Allow LAN Bind除非确实需要局域网共享远程部署务必使用 HTTPShttps://URL 或让归一化逻辑自动补全不要为了省事开启 Allow Insecure Remote HTTP远程托管必须配置--http-remote-hosted与--api-key-validation-url否则启动失败并强烈建议配置 service token 实现服务器与认证服务双向鉴权会话隔离确认 Unity 插件 WebSocket 与 MCP 客户端使用解析到同一user_id的 API Key否则会出现看不到自己的 Unity 实例的隔离问题密钥轮换轮换密钥后为吊销生效留出--api-key-cache-ttl的时间窗口版本跟进只使用main或 beta 最新版本旧版本不在安全支持范围内日志审计排查日志中是否存在密钥明文正常实现下超过 8 字符的密钥应显示为xxxx...yyyy脱敏形式。十、继续深入关键文件索引主题仓库路径安全策略原始文档SECURITY.mdHTTP 安全策略实现回环判断、URL 校验MCPForUnity/Editor/Helpers/HttpEndpointUtility.cs安全配置 EditorPrefs 键MCPForUnity/Editor/Constants/EditorPrefKeys.cs高级设置 UILAN Bind / Insecure HTTP 开关MCPForUnity/Editor/Windows/Components/Advanced/McpAdvancedSection.uxml、MCPForUnity/Editor/Windows/Components/Advanced/McpAdvancedSection.cs安全策略回归测试TestProjects/UnityMCPTests/Assets/Tests/EditMode/Services/Characterization/ServerManagementServiceCharacterizationTests.cs远程认证使用指南website/docs/guides/remote-server-auth.md远程认证架构设计website/docs/architecture/remote-auth.mdAPI Key 校验服务实现Server/src/services/api_key_service.pyWebSocket 认证门槛Server/src/transport/plugin_hub.py会话隔离双索引注册表Server/src/transport/plugin_registry.py传输模式与网络安全说明website/docs/architecture/transports.md【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考