Edgegap

npx add-mcp 'https://mcp.edgegap.dev/mcp'

Edgegap MCP 服务器

通过我们的 MCP 服务器将 AI 编码代理连接到 Edgegap。您的代理可以完成从无头服务器构建到玩家连接的整个流程：编写或检查 Dockerfile，将镜像推送到您的 Edgegap 私有注册表，在靠近玩家的位置部署权威专用服务器，并在出现问题时读取日志。

👉 支持的功能

[!TIP] 使用 Unity、Unreal Engine 或 Godot？ 对于这些引擎，我们的 Unity、Unreal Engine 和 Godot 指南及插件仍是最快捷的途径。MCP 服务器可与它们配合使用，也可独立用于任何引擎。

以下情况适合使用我们的 MCP 服务器：

• 容器化游戏服务器 - 您的代理会根据最佳实践为您的构建编写 Dockerfile（或检查现有文件），将镜像推送到我们的私有容器注册表，并删除未使用的旧镜像标签以释放注册表容量。
• 部署专用服务器 - 创建和更新应用版本，查看可用位置，在靠近玩家的位置部署，并获取服务器 IP 和端口以测试客户端连接。
• 构建 CI/CD 流水线 - 从构建系统测试部署并拆除部署。
• 排查游戏服务器问题 - 检查应用版本和部署状态，读取容器日志及 CPU/内存使用情况，或复现失败的部署。
• 运行客户端托管和点对点游戏 - 创建中继会话以提供 NAT 穿透并避免连接受阻。请先查看编排模型和专用服务器还是中继？，再做决定。

[!WARNING] MCP 不支持以下范围：构建 Linux 服务器可执行文件；创建、启动或停止匹配器（请在控制面板中上传生成的配置）；服务器浏览器；大厅；托管集群；私有机群；或计费。

[!NOTE] 如需帮助，请通过 Discord 联系我们。有关在线游戏的支持，请参阅我们的工单系统。

⚖️ 专用服务器还是中继？

Edgegap 可以通过两种方式托管您的多人游戏。我们推荐使用专用服务器，我们的 MCP 服务器也会这样做：您的代理默认使用专用服务器，只有在您选择客户端托管模式时才会使用中继。

	专用服务器（推荐）	中继
Edgegap 运行的内容	您的无头服务器构建，部署在靠近玩家的位置	仅转发流量，不运行游戏代码
谁运行游戏	服务器	一名玩家的游戏（主机）
作弊	难度高得多，服务器拥有权威性	主机可以更改任何内容
公平性	每位玩家都直接连接到服务器	主机没有延迟，其他人都要经过两次跳转
主机离开时	对局继续	对局结束，除非您的游戏支持主机迁移
性能受限于	服务器分配的 CPU 和内存	主机的电脑和家庭网络上行带宽
您需要	容器镜像中的服务器构建	配置为监听服务器（客户端托管）的网络代码

[!NOTE] 还没有服务器镜像？ 这并不是选择中继的理由。您的代理可以使用 edgegap_generate_dockerfile 为您的构建编写 Dockerfile。请在分布式中继中了解更多有关中继的信息。

🚀 安装

安装 MCP 服务器非常简单：

1. 为常用代理安装 MCP 服务器，或使用自定义集成。
2. 生成 API 令牌并将其提供给代理，以便代理通过我们的 MCP 服务器使用该令牌。

在控制面板 - 用户设置 / 令牌中生成（并查看）您的 Edgegap API 密钥令牌。

在每个 API 请求中通过 HTTP 标头添加您的密钥令牌（包含单词 token）：

Authorization: token xxxxxxxx-e458-4592-b607-c2c28afd8b62

[!CAUTION] 请勿在游戏客户端中集成 Edgegap API 端点，因为您的 API 令牌可无限制访问您的账户。有关安全的面向客户端 API 端点和函数，请参阅集成。

[!TIP] 如果您的密钥令牌遭到泄露或暴露，请在控制面板中删除并重新创建。

该令牌适用于整个组织，无法限定到单个应用。将令牌交给无人值守的代理之前，请阅读 DESIGN.md。

常用代理

使用本页顶部的 Cursor 或 VS Code 按钮，在您偏好的智能体 IDE 中安装 Edgegap MCP 服务器，然后将令牌添加到 Authorization 标头。

Claude Code

claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp \
  -H "Authorization: token xxxxxxxx-e458-4592-b607-c2c28afd8b62" --scope user

ChatGPT Codex

Codex 从环境变量中读取令牌，并将其作为 Authorization: Bearer <token> 发送，托管端点可接受此标头。在 ~/.codex/config.toml 中：

[mcp_servers.edgegap]
url = "https://mcp.edgegap.dev/mcp"
bearer_token_env_var = "EDGEGAP_API_TOKEN"

然后在 Codex 启动时所处的环境中，将 EDGEGAP_API_TOKEN 设置为您的令牌。

Claude Desktop 和 claude.ai

claude.ai 和 Claude Desktop 中的自定义连接器无法发送 Authorization 标头，因此托管端点无法从它们接收您的令牌：连接器会显示为已连接，但每次工具调用都会失败。请改用本地服务器。

在 Claude Desktop 中，打开 Settings → Developer → Edit Config，并将本地服务器添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "edgegap": {
      "command": "npx",
      "args": ["-y", "@edgegap/mcp"]
    }
  }
}

不填写令牌，首次使用时系统会提示您输入。浏览器中的 claude.ai 无法运行本地服务器，因此在托管端点支持 OAuth 之前，它无法使用 Edgegap MCP。

Cursor

使用本页顶部的 Cursor 按钮即可安装；如需手动安装，请将以下内容添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "edgegap": {
      "url": "https://mcp.edgegap.dev/mcp",
      "headers": { "Authorization": "token xxxxxxxx-e458-4592-b607-c2c28afd8b62" }
    }
  }
}

VS Code（Copilot 代理模式）

使用本页顶部的 VS Code 按钮即可安装；如需手动安装，请将以下内容添加到 .vscode/mcp.json（VS Code 使用 servers，而不是 mcpServers）：

{
  "servers": {
    "edgegap": {
      "type": "http",
      "url": "https://mcp.edgegap.dev/mcp",
      "headers": { "Authorization": "token xxxxxxxx-e458-4592-b607-c2c28afd8b62" }
    }
  }
}

Windsurf

在 ~/.codeium/windsurf/mcp_config.json 中运行本地服务器，它适用于所有通过命令启动 MCP 服务器的客户端：

{
  "mcpServers": {
    "edgegap": {
      "command": "npx",
      "args": ["-y", "@edgegap/mcp"],
      "env": { "EDGEGAP_API_TOKEN": "xxxxxxxx-e458-4592-b607-c2c28afd8b62" }
    }
  }
}

mcp.json

大多数智能体 IDE 也支持通过粘贴 JSON 配置进行集成：

{
    "mcpServers": {
        "Edgegap": {
            "type": "http",
            "url": "https://mcp.edgegap.dev/mcp",
            "headers": {
                "Authorization": "token xxxxxxxx-e458-4592-b607-c2c28afd8b62"
            }
        }
    }
}

自定义集成

在代理的虚拟化环境中安装远程 Edgegap MCP 服务器（切勿安装在您的项目中！）：

Node，使用 mcp-remote npx 包

{
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://mcp.edgegap.dev/mcp", "--transport", "http-only"]
}

Python，使用 mcp-proxy uvx 包

{
  "command": "uvx",
  "args": ["mcp-proxy", "--transport", "streamablehttp", "https://mcp.edgegap.dev/mcp"]
}

一键安装（Claude Desktop）

下载 edgegap-mcp.mcpb 并打开：Claude Desktop 会将本地服务器作为扩展安装，并提示您输入 API 令牌，然后将其保存在操作系统的安全存储中。扩展的设置还包含只读模式、应用允许列表、最长时长上限和部署数量上限（即下方的变量）。每个版本都会附带根据该版本代码构建的安装包。其他任何支持安装 MCPB 安装包的应用也都采用相同方式。

本地服务器

若要将 API 令牌保留在自己的计算机上，请改为在本地运行服务器。不填写令牌，代理会在首次使用时提示您输入，并且只会在该会话期间将令牌保存在内存中：

{
  "mcpServers": {
    "Edgegap": {
      "command": "npx",
      "args": ["-y", "@edgegap/mcp"],
      "env": { "EDGEGAP_API_TOKEN": "xxxxxxxx-e458-4592-b607-c2c28afd8b62" }
    }
  }
}

需要 Node 18+。在生产环境中请固定版本（@edgegap/mcp@0.15.4），而不要使用浮动的 latest 版本。已在官方 MCP 注册表中登记为 dev.edgegap/mcp。

本地服务器还可以限制代理的操作权限。以下变量对托管端点 mcp.edgegap.dev 无效：

变量	默认值	用途
EDGEGAP_API_TOKEN	（提示输入）	API 令牌。可选：不填写时，首次使用会提示您输入。系统会自动添加 token 前缀。切勿将其作为命令行参数传递。
EDGEGAP_READ_ONLY	0	设置为 1 后，不会注册会更改内容的工具（在工具中以 ● 标记），因此代理无法被诱导调用这些工具。
EDGEGAP_APP_ALLOWLIST	（空）	以逗号分隔的应用名称。限制代理可以创建应用和部署到的应用。读取操作（列出应用和版本）不受限制，运行中的部署也不受限制。请参阅 DESIGN.md。
EDGEGAP_MAX_DURATION_MINUTES	60	代理可为版本设置的 max_duration 上限。edgegap_deploy 还会拒绝 max_duration 超出此上限或不受限制的版本，除非代理在征求您的同意后传入 allow_long_running: true。
EDGEGAP_MAX_AGENT_DEPLOYMENTS	5	当有这么多个标记为 edgegap-mcp 的部署正在运行时，edgegap_deploy 会拒绝请求。0 会关闭此上限。
EDGEGAP_MAX_DEPLOYS_PER_RUN	20	部署一个服务器进程可以发送的数量，包括失败的部署。重启服务器即可重置。0 会关闭此限制。
EDGEGAP_STOP_OWN_ONLY	0	设置为 1 后，edgegap_stop_deployment 只会停止标记为 edgegap-mcp 的部署，因此代理无法停止并非由它启动的服务器。
EDGEGAP_ENABLE_SKILLS_UPDATE	0	设置为 1 后，允许 edgegap_update_skills 使用 apply: true 运行 npx skills@1.7.4 update 或 claude plugin update。否则，它会列出这些命令供您运行。无论哪种情况，手动复制的技能都会从安装包中重写。更新程序只会获取路径、主目录、临时目录、本地化设置、代理和 npm 设置，不会获取 EDGEGAP_* 变量，也不会获取任何名称中包含 token、secret、password 或 key 的内容。
EDGEGAP_TIMEOUT_MS	30000	每个请求的 HTTP 超时时间。
EDGEGAP_SKILLS_CHECK	on	设置为 off 后，技能工具不会从 GitHub 读取最新的技能版本。

Windows

本地服务器可在安装了 Node.js 18 或更高版本的 Windows 上运行，CI 也会在 Windows 上运行构建和 stdio 测试。

• 许多 Windows MCP 客户端无法直接启动 npx，因为它是一个 .cmd 脚本。请通过 cmd /c 启动它："command": "cmd", "args": ["/c", "npx", "-y", "@edgegap/mcp"]。在 Claude Code 中：claude mcp add Edgegap --env EDGEGAP_API_TOKEN=<token> -- cmd /c npx -y @edgegap/mcp。
• 在 PowerShell 中，手动运行时请输入 npx.cmd，而不是 npx：新安装的 Windows 会阻止运行 npx PowerShell 脚本（“此系统上已禁用脚本运行”）。
• 首次启动时会下载软件包，可能需要一些时间；之后启动会很快。
• edgegap_update_skills 会像在 macOS 和 Linux 上一样，在 %USERPROFILE% 中查找已安装的技能。

📚 技能

服务器包含 Edgegap 代理技能：经过测试的分步工作流程，帮助您让多人游戏上线，并提供模板（Dockerfile、匹配器配置、Unity C# 和 Unreal C++ 插件代码）及已知问题。任何连接到 Edgegap MCP 的代理都可以使用这些技能，无需单独安装，也无需令牌，并且会被告知在处理游戏项目之前加载相应的技能。

技能	适用场景
edgegap	除 Unity 或 Unreal Engine 之外的任何引擎，或平台相关问题，都从这里开始。它会引导你使用其他技能。
edgegap-unity	Unity 端到端流程：服务器构建、匹配器、客户端、端到端测试。
edgegap-ngo	Unity 搭配 Netcode for GameObjects 的端到端流程：启动并自行停止服务器、Find Match 面板、Boss Room 适配器、匹配器。
edgegap-fishnet	Unity 搭配 FishNet 的端到端流程：无头服务器、Bayou/WebGL、匹配器、端到端测试。
edgegap-purrnet	Unity 搭配 PurrNet 的端到端流程：专用服务器、连接面板、匹配器、端到端测试。
edgegap-fusion	Unity 搭配 Photon Fusion 2 的端到端流程：IL2CPP Linux 服务器、绑定到 0.0.0.0 的服务器、Edgegap 部署、BR200 套件。
edgegap-fusion-simplefps	在 Edgegap 专用服务器上运行 Photon 的 Simple FPS 示例。
edgegap-godot	Godot 4 搭配 Godot 专用服务器：无头导出、ENet 或 WebSocket、匹配器。
edgegap-colyseus	在 Edgegap 上运行 Colyseus 服务器，可直接连接或通过匹配器连接。
edgegap-nakama	使用 Nakama 作为后端，为其对局启动 Edgegap 服务器。
edgegap-playfab	使用 PlayFab Matchmaking 搭配 Edgegap 服务器。
edgegap-threejs	使用 Three.js 和其他浏览器游戏，并搭配自有 Node.js 服务器。
edgegap-matchmaking	适用于任何引擎的匹配设计：由谁负责、玩家档案、队伍、区域选择、补位、第三方匹配器。
edgegap-manus	使用 Manus 构建的浏览器游戏：后端匹配、Steam 登录、签名加入令牌、Node WebSocket 服务器。
edgegap-unreal	Unreal Engine 端到端流程：源代码引擎、Linux 服务器、匹配器、端到端测试。
edgegap-eos-voice	在 Edgegap 上为 Unreal 游戏使用 EOS Voice 进行语音聊天：服务器端房间令牌、对局和队伍房间。
edgegap-server-design	权威服务器设计和部署生命周期。
edgegap-containerize	容器规范、Dockerfile、镜像仓库、应用版本。
edgegap-local-testing	先在本机进行一致性测试，再进行一次冒烟测试部署。
edgegap-troubleshoot	拉取错误、崩溃循环、内存不足、客户端无法连接。
edgegap-deployments-api	用于部署服务器的后端代码：webhook、清理、Nakama、PlayFab、UGS、EOS。
edgegap-launch	发布检查清单、逐步发布、缓存、成本控制。

这些内容通过三种方式提供，因此每个 MCP 客户端都能访问：

• 工具： edgegap_list_skills 和 edgegap_get_skill，后者会加载技能的 SKILL.md，或通过 file 加载其参考文档或模板之一。
• 提示： deploy-game-server（“将我的游戏服务器部署到 Edgegap”）是开始的入口：它会识别引擎和网络代码，加载匹配的技能，并引导你完成标准流程，包括清理。每项技能也各有一个以技能名称命名的提示。在 Claude Code 中，它们会显示为斜杠命令，例如 /mcp__edgegap__deploy-game-server。
• 资源： 每项技能的 SKILL.md 都列在 edgegap-skill://<skill>/SKILL.md 中；其他文件则通过 edgegap-skill://{skill}/{+path} 模板读取，例如 edgegap-skill://edgegap-unity/references/deploy.md。

每个版本都会打包固定在 scripts/skills-pin.txt 提交上的技能；edgegap_context 会报告当前加载的是哪个技能包。edgegap_list_skills 还会从 GitHub 读取最新技能包版本（一个版本号，每小时缓存一次；EDGEGAP_SKILLS_CHECK=off 可关闭此功能），并提示是否有更新版本；edgegap_get_skill 会在技能标题下方添加相同提示。

保持已安装的技能为最新版本。 如果你也在代理中安装了这些技能（Claude Code 插件 edgegap@edgegap、npx skills add edgegap/llm-agent-skills，或复制到 ~/.claude/skills 的文件夹），edgegap_update_skills 会逐一将它们与 GitHub 上的最新版本进行比较。在本地服务器上，它会自行查找这些安装；使用 apply: true 时，它会运行 npx skills update（仅限 Edgegap 技能）或 claude plugin update，并用此版本中打包的文件重写手动复制的技能，同时保留你添加的文件，不改动符号链接和 git 检出内容。它绝不会下载技能文本。托管服务器无法访问你的磁盘：在 installed_versions 中传入已加载的版本，它会告知哪些版本落后以及如何更新。

🧰 工具

代理会根据你的请求选择合适的工具。你不必指定工具名称，但了解可用工具有助于你提出请求。标记为 ● 的工具会更改你账户中的内容，需要 dry_run，并且在 EDGEGAP_READ_ONLY=1 时会被隐藏。

工具	功能
edgegap_context	显示此服务器所连接的 API、版本、运行于本地还是托管环境，以及当前生效的防护措施。不调用 API；绝不显示令牌。

首次部署前

工具	功能
edgegap_generate_dockerfile	为服务器构建编写 Dockerfile：包括构建文件夹、服务器二进制文件或启动脚本、端口和启动参数，并设置正确的无头模式标志（Unity -batchmode -nographics、Godot --headless）、为 Unreal 设置非 root 用户，以及匹配端口。它会列出所有需要自行假设的内容，供代理确认。适用于 Unity、Unreal Engine、Godot 和其他任何引擎。
edgegap_validate_server_config	在构建前检查现有 Dockerfile、端口、资源和镜像标签。它会发现 ARM 或 Windows 镜像（Edgegap 运行 linux/amd64）、以 root 身份运行的 Unreal 服务器、缺少的 Unity -batchmode -nographics、绑定到 localhost 的服务器、与网络代码传输方式不匹配的端口，以及 latest 标签。
edgegap_get_registry_credentials ●	返回用于 Edgegap 私有容器镜像仓库的推送凭据，以及准确的 docker login、构建和推送命令。Edgegap 仅会通过 Unity/Unreal 插件的快速入门令牌提供这些凭据；使用常规 API 令牌时，它会提示代理向你索取仪表板 Container Registry 页面中的登录信息。
edgegap_list_registry_tags	在注册镜像前，确认镜像已成功推送。只需提供镜像名称，例如 my-game-server：项目会根据你的令牌确定。
edgegap_delete_registry_tag ●	删除一个标签及其指向的镜像，以清理旧构建。每次调用只能指定一个确切标签；拒绝 latest、通配符和列表。

专用服务器（推荐）

工具	功能
edgegap_list_apps	列出你的应用程序。
edgegap_create_app ●	创建应用程序。
edgegap_update_app ●	开启或关闭应用程序，以控制是否接受新的部署。
edgegap_list_app_versions	列出版本及其镜像、资源、端口（含 TLS Upgrade），以及是否已设置镜像仓库登录信息。
edgegap_get_app_version	完整读取一个版本的信息：镜像、资源、端口、最长运行时间、镜像缓存、重启策略和环境变量名称（绝不显示变量值）。
edgegap_create_app_version ●	将容器镜像注册为可部署版本。支持在 WS 和 HTTP 端口上使用 TLS Upgrade，这是浏览器（WebGL）客户端使用 wss:// 所必需的。
edgegap_update_app_version ●	修改现有版本：新的镜像标签、启用/停用、CPU 和内存（必须同时设置）、最长运行时间、镜像仓库登录信息、镜像缓存（force_cache）、关闭宽限期、端口、环境变量，以及日志写入的 Endpoint Storage。只会更改传入的字段，但 ports 和 env 会替换整个列表。正在运行的部署会继续使用旧设置。
edgegap_delete_app_version ●	删除一个版本，以清理测试版本。该版本仍有部署在运行时会拒绝删除。镜像仓库中的镜像会保留。
edgegap_delete_app ●	删除应用程序及其版本。只要该应用程序仍有任何部署在运行，或其版本数量超过 max_versions（默认值为 0），就会拒绝删除。
edgegap_list_locations	列出 Edgegap 可部署到的城市；指定一个版本时，则只列出当前有容量的城市。
edgegap_list_ping_beacons	列出游戏客户端用于测量各区域延迟的 ping 信标。
edgegap_deploy ●	在靠近玩家的位置部署权威专用服务器。始终带有 edgegap-mcp 标签，并报告 Edgegap 将在何时停止该服务器。可选项：仅用于此次部署的 CPU 和内存、Edgegap 在服务器就绪、失败或结束时调用的 webhook、用于加快启动的 require_cached_locations，以及优先将服务器部署到私有机群的 private_host_ids。
edgegap_list_fleet_hosts	列出某个私有机群中的主机及其状态和位置，以便部署到这些主机上。
edgegap_wait_for_deployment	等待服务器就绪并返回连接地址。
edgegap_get_deployment	读取部署状态。
edgegap_list_deployments	按应用程序、版本、状态、标签等筛选并按运行时长排序，列出正在运行的部署。用于查找遗留的运行中服务器；only_agent_deployments: true 会列出代理启动的所有服务器。请参阅筛选部署。
edgegap_get_deployment_logs	在部署运行期间读取容器日志和崩溃详情。部署停止后，只有设置了 Endpoint Storage 才会保留日志。
edgegap_get_deployment_metrics	汇总 CPU、CPU 限流、内存和网络使用情况（最新值、平均值、峰值），用于调整版本规格或检查崩溃原因。
edgegap_stop_deployment ●	根据确切的请求 ID 停止一个部署。不支持批量停止。
edgegap_tag_deployment ●	为正在运行的部署添加或移除标签，例如标记一场对局。edgegap-mcp 标签会保留。
edgegap_report_deployment ●	向 Edgegap 报告部署及其原因，供工作室的审核后端使用。服务器会继续运行。

日志和文件（Endpoint Storage）

除非将容器日志导出到你自己的 S3 兼容存储桶，否则部署结束后日志会消失。

工具	功能
edgegap_list_endpoint_storage	列出你的 Endpoint Storage 存储桶及其拉取配置。绝不返回密钥。
edgegap_create_endpoint_storage ●	注册用于导出日志的存储桶（AWS S3、Cloudflare R2、DigitalOcean Spaces 等）。在版本上设置 endpoint_storage 即可启用导出。绝不会回显密钥。
edgegap_create_pull_profile ●	在启动时将存储桶中的文件或文件夹复制到容器中（地图、配置、大型资源）。
edgegap_link_pull_profile ●	将拉取配置关联到某个版本，或取消关联。
edgegap_delete_pull_profile ●	删除一个拉取配置。存储桶及其文件会保留。
edgegap_delete_endpoint_storage ●	删除一个 Endpoint Storage；除非 max_pull_profiles 允许删除其拉取配置，否则在仍有关联配置时会拒绝删除。存储桶及其日志会保留。

中继（仅限主机-客户端游戏）

中继不是游戏服务器：它会转发流量，而对局由一名玩家的游戏主机承载。请参阅专用服务器还是中继？。

工具	功能
edgegap_create_relay_session ●	为玩家创建中继会话，并返回中继地址以及每位玩家的授权令牌。
edgegap_get_relay_session	读取中继会话。
edgegap_list_relay_sessions	列出开放的中继会话，以查找遗留会话。不返回授权令牌。
edgegap_authorize_relay_user ●	添加后来加入的玩家。
edgegap_revoke_relay_user ●	从中继会话中移除一名玩家。
edgegap_delete_relay_session ●	关闭中继会话。

[!WARNING] 部署和中继会话在运行期间都会产生费用。完成后，请让代理停止测试部署并删除测试中继会话。

示例提示

• “为我的 Unity 服务器构建编写 Dockerfile，然后推送镜像并在我附近部署服务器。”
• “检查我的 Dockerfile 是否适用于 Edgegap，并修复任何问题。”
• “我的部署失败了。读取日志并告诉我原因。”
• “我上一场对局用了多少 CPU 和内存？据此调整我的版本规格。”
• “我的游戏使用主机-客户端网络。为两名玩家设置 Edgegap 中继。”

🛡️ 防护措施

你的 API 令牌可以执行组织中的任何操作，因此服务器会对代理使用令牌的行为施加自身限制。这些限制同时适用于本地服务器和托管端点。

防护措施	作用
Dry run	每个会更改内容的工具都会执行 dry_run: true：它会返回确切的方法、主机、路径和请求体，并对令牌、注册表令牌和环境变量值进行遮蔽，且不会发送任何内容。本地检查仍会运行。
容器中不含令牌	如果 API 令牌出现在环境变量名称或值、标签或 webhook URL 中，则会拒绝部署或版本操作，且不会发送任何内容。环境变量值绝不会回显。
Agent 标签	每次部署都会添加 edgegap-mcp 标签，即使 agent 传入了自己的标签也是如此。使用 edgegap_list_deployments 和 only_agent_deployments: true 可找到所有这些部署。
自动停止	每次部署都会报告 Edgegap 将在何时停止该部署：版本的 max_duration，但对于 agent 创建的版本，最长不超过 EDGEGAP_MAX_DURATION_MINUTES（默认值为 60）。Edgegap 没有单次部署的时间限制，因此，如果版本的 max_duration 超过此上限或为无限（在其他位置创建的版本默认值为 1440 分钟），则会拒绝部署，除非 agent 传入 allow_long_running: true；只有在先征求你的同意后，才会告知 agent 这样做。
每次运行的部署数	本地服务器每个进程最多发送 EDGEGAP_MAX_DEPLOYS_PER_RUN 次部署（默认值为 20），失败的部署也计入其中，因为被拒绝的部署仍可能创建部署记录。如果 API 拒绝部署但仍创建了部署，错误信息会指出该部署，以便 agent 停止它。
不使用可变镜像标签	edgegap_create_app_version 会拒绝 latest（不区分大小写）、空标签或 Docker 会拒绝的标签，且不会发送任何内容：Edgegap 会按标签缓存镜像，因此重新推送的标签可能会部署过期的构建。在 latest 上部署现有版本也会被拒绝，为 latest 请求注册表推送命令同样会被拒绝。
镜像引用检查	如果 docker_image 同时包含注册表主机、标签或摘要（例如 registry.edgegap.com/proj/server:v2），则会被拒绝，错误信息会给出正确的 docker_repository / docker_image / docker_tag 拆分方式。edgegap_validate_server_config 也会标记相同的问题。
部署上限	如果已有 EDGEGAP_MAX_AGENT_DEPLOYMENTS（默认值为 5）个带有 edgegap-mcp 标签的部署正在运行，则会拒绝 edgegap_deploy，以防循环运行的 agent 不断创建计费服务器。拒绝信息会说明如何列出并停止这些部署。
隐藏的机密环境变量	名称看起来像机密的环境变量（TOKEN、SECRET、PASSWORD、API_KEY、CREDENTIAL、AUTH…）会以 is_hidden 发送，因此仪表板不会以明文显示其值。
严格停止	edgegap_stop_deployment 根据确切的请求 ID 停止单个部署。空 ID、通配符和列表都会被拒绝。不支持批量停止。使用 EDGEGAP_STOP_OWN_ONLY=1 时，它只会停止带有 edgegap-mcp 标签的部署。
谨慎删除	edgegap_delete_app_version 和 edgegap_delete_app 只接受一个确切名称；如果该名称对应的部署正在运行，则会拒绝操作。只有当 max_versions 涵盖某个应用的所有版本时，才会删除该应用。
Webhook 和存储桶 URL	部署 webhook 和 Endpoint Storage 端点必须是 https URL，且不得包含凭据；如果其中包含你的 API 令牌，也会被拒绝。
每个结果都包含主机	每个结果都会以 API 主机开头，例如 [api.edgegap.com]；如果 EDGEGAP_BASE_URL 指向其他位置，则会显示 [custom · host]。如果基础 URL 指定了 api.edgegap.com，则必须与 https://api.edgegap.com 完全一致，否则服务器会拒绝启动。
脱敏	令牌会在每条错误信息传给 agent 之前被移除。

服务器在每次 API 调用中都会使用 User-Agent: edgegap-mcp/<version> (<MCP client name>) 标识自身。

使用情况分析。 本地服务器和自托管 Docker 镜像除了 API 调用本身之外，不会发送任何内容。托管端点 mcp.edgegap.dev 使用 PostHog MCP Analytics（@posthog/mcp），并向 Edgegap 的 PostHog 发送使用情况事件：连接的 MCP 客户端、使用的工具、提示或技能资源、传入参数的名称（不含值）、调用是否成功、错误代码、失败阶段和 Edgegap API 状态、耗时、是否为 dry run、有关调用的少量信息（等待部署的结果、验证结果、加载的技能）、到达的黄金路径步骤，以及服务器版本和 Cloudflare 国家/地区代码。调用失败时，还会发送错误信息（移除你的令牌、传入参数的值，以及任何看起来像凭据、IP 地址或 ID 的内容后，截断至 300 个字符）。部署 ID 只会以带密钥的哈希形式发送。只有指定名称的元数据属性会被允许通过。它绝不会发送你的令牌、工具参数值（IP 地址、环境变量、应用或镜像名称）或结果，并且已关闭 GeoIP。它不会为工具添加任何参数。来自同一令牌的事件会归入该令牌的带密钥、不可逆哈希之下。完整列表见 docs/analytics.md。如需选择退出，请发送标头 X-Edgegap-Telemetry: off（或 DNT: 1），或使用本地服务器。

🚨 故障排除

查看常见错误代码，了解如何解锁集成。

401 Unauthorized

你的 MCP 集成很可能未正确包含 Authorization 标头。

Tool Call Failed

你的客户端缺少 Edgegap 令牌。claude.ai 和 Claude Desktop 自定义连接器会出现此问题，因为它们无法发送 Authorization 标头。替代方案请参阅 Claude Desktop and claude.ai。

[!WARNING] 这是一个已知限制，近期将会解决，敬请关注更新！

403 Forbidden

你的 MCP 集成可能正在使用模板令牌或已删除的令牌。请确认集成使用的令牌值与仪表板中显示的令牌完全一致。

424 Image Could Not Be Pulled

Edgegap 无法拉取你的容器镜像。请检查仓库、镜像名称和标签，并确认该标签已推送（请让 agent 列出注册表标签）。对于 Edgegap 注册表中的镜像，镜像名称必须包含你的项目，例如 my-project/my-game-server。

Registry Credentials Unavailable

Edgegap 只会向 Unity 和 Unreal 插件使用的快速入门令牌提供注册表凭据，因此使用常规 API 令牌时，agent 无法检索这些凭据，只能向你询问。请从 仪表板 的 Container Registry 下复制 Project、Username 和 Token，或者推送到 Edgegap 可以拉取镜像的其他注册表（Docker Hub、GitHub、AWS ECR、GCP、GitLab）。请参阅 External Registries。

"status": "empty" 或 "not_configured"

这不是错误。空列表（尚无应用、没有正在运行的部署、从未推送过镜像）或组织尚未设置的功能（中继、此令牌无法读取的注册表）会作为正常结果返回，其中包含 status 和 next_step。agent 应继续执行下一步，而不是重试。

No Token Yet

技能（edgegap_list_skills、edgegap_get_skill）、edgegap_context、edgegap_generate_dockerfile 和 edgegap_validate_server_config 无需令牌即可使用，因此 agent 可以先准备服务器构建。在 app.edgegap.com 创建账户，并在 User Settings → Tokens 下创建令牌。使用 edgegap_context 和 check_token: true 可查看当前会话是否存在有效令牌，并显示其末四位字符，方便你在该页面找到它。

本地可以启动，但在 Edgegap 上无法启动

请让 agent 验证服务器配置，或生成新的 Dockerfile。最常见的原因包括：在 Apple Silicon 上构建镜像时未使用 docker build --platform linux/amd64、服务器监听的端口与版本公开的端口不同，或将 UDP 传输配置成了 TCP。

其他 API 错误

请查阅我们的 API Reference，了解各个 API 端点可能返回的错误。

[!NOTE] 如需帮助，请通过 Discord 联系我们。如需获取在线游戏支持，请使用我们的工单系统。

🛠️ 自托管

托管端点 mcp.edgegap.dev 以 Cloudflare Worker 形式运行（参见 worker/INSTALL.md）。如需在自己的基础设施上运行相同的无状态 HTTP 服务器，请使用 Docker 镜像：

docker build -t edgegap-mcp .
docker run --rm -p 8080:8080 edgegap-mcp

客户端使用自己的 Authorization 标头连接到 http://<host>:8080/mcp，方式与连接托管端点相同。镜像不包含任何凭据，且 /health 无需凭据即可响应。PORT、HOST、EDGEGAP_READ_ONLY、EDGEGAP_APP_ALLOWLIST、EDGEGAP_MAX_DURATION_MINUTES、EDGEGAP_MAX_AGENT_DEPLOYMENTS 和 EDGEGAP_STOP_OWN_ONLY 均适用；请使用 -e NAME=value 传入每一项。切勿向容器传入 API 令牌：每个客户端都会在每次请求中发送自己的令牌。在将其暴露到专用网络之外之前，请阅读 worker/DECISION.md。

适用于 linux/amd64 和 linux/arm64 的预构建镜像已发布到 ghcr.io/edgegap/llm-mcp-server（对于现有设置，也会发布到旧名称 ghcr.io/edgegap/edgegap-mcp），每次推送到 main 时都会标记为 main 和 sha-<commit>，此外还会为 v* 标签发布对应版本：

docker run --rm -p 8080:8080 ghcr.io/edgegap/llm-mcp-server:main

开发

有关更改必须通过的检查，请参阅 CONTRIBUTING.md；有关各版本的更改，请参阅 CHANGELOG.md；如需报告漏洞，请参阅 SECURITY.md。

npm ci
npm run build
npm test                  # mock-API tests; none reach Edgegap
npm run typecheck:worker

如需将捆绑的技能更新到 llm-agent-skills 的最新提交，然后按常规流程发布：

npm run sync-skills -- --ref main
npm run check-skills      # exit 1 if src/skills.generated.ts differs from the pin

测试	覆盖内容
test/unit.test.mjs	针对标签、镜像、机密名称、URL 和脱敏规则的单元测试
test/package.mjs	打包：一个 bin、运行时依赖项、步骤中的版本
test/skills.mjs	通过 MCP 使用技能：工具、提示、资源、路径安全性、捆绑内容与固定版本匹配
test/smoke.mjs	握手、工具注册、只读模式
test/guards.mjs	本地验证和允许列表强制执行
test/elicit.mjs	令牌提示：接受、拒绝确认、拒绝、不支持
test/newtools.mjs	针对本地模拟 API 测试验证器、Dockerfile 生成器、注册表、部署、中继和匹配器工具
test/http.mjs	自托管 HTTP 服务器：无需令牌即可发现服务、每个请求使用独立令牌、外部凭据
test/spec.mjs	服务器发送的每个端点和请求体字段都包含在 spec/ 中（通过 dry run 检查写入工具）
test/snapshot.mjs	工具名称、描述、架构和说明与 test/tools.snapshot.json 一致；有意更改后执行 npm run snapshot:update
test/live-check.mjs	不在 npm test 中。使用来自非生产组织的令牌对真实 API 运行

设计决策、安全模型以及明确不在范围内的内容，请参阅 DESIGN.md。