Edgegap

Edgegap MCP Server

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

👉 支持的功能

提示

使用 Unity、Unreal Engine 或 Godot？ 对于这些引擎，我们的 Unity、Unreal Engine 和 Godot 指南及插件仍是最快的接入方式。MCP 服务可与它们配合使用，也可独立用于任何引擎。

以下场景适合使用我们的 MCP 服务：

• 将游戏服务端容器化 - Agent 根据 Edgegap 的要求为你的构建编写 Dockerfile（或检查现有文件），然后将镜像推送到你的 Edgegap 私有容器注册表。
• 部署专用服务端 - 创建应用和版本，在靠近玩家的位置进行部署，并获取连接地址。
• 设置匹配服务 - 生成指向已部署版本的匹配器配置，以便上传到控制面板。
• 运行主机-客户端游戏 - 如果你的游戏采用一名玩家作为主机的模式，则创建中继会话。请先参阅专用服务端还是中继？。
• 构建 CI/CD 流水线 - 从构建系统测试部署并拆除部署。
• 排查游戏服务端问题 - 检查应用版本和部署状态、读取容器日志，或复现部署失败的问题。

警告

MCP 不支持以下功能：创建或运行匹配服务（MCP 只会生成配置，你需要在控制面板中上传）；服务端浏览器；大厅；托管集群；私有集群；或计费。

说明

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

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

Edgegap 可以通过两种方式托管你的多人游戏。我们建议使用专用服务器，我们的 MCP 服务也同样建议如此：你的 Agent 默认会使用专用服务器，只有在你选择了主机-客户端设置时才会使用中继。

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

说明

还没有服务器镜像？ 这不是选择中继的理由。你的 Agent 可以使用 edgegap_generate_dockerfile 为你的构建版本编写 Dockerfile。在分布式中继中了解有关中继的更多信息。

🚀 安装

安装 MCP 服务非常简单：

1. 为常用 Agent安装 MCP 服务，或通过自定义集成进行安装。
2. 生成并附加 API 令牌，供你的 Agent 在使用我们的 MCP 服务时使用。

在 Dashboard - User Settings / Tokens 中生成（并查看）Edgegap API 的机密令牌。

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

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

注意

不要在游戏客户端中集成 Edgegap API 端点，因为你的 API 令牌可以不受限制地访问你的账户。有关安全的面向客户端 API 端点和函数，请参阅集成。

提示

如果你的机密令牌遭到泄露，请从控制面板中删除并重新创建。

该令牌适用于整个组织，无法限定为仅用于一个应用。在将令牌提供给无人值守的 Agent 之前，请阅读 DESIGN.md。

常用 Agent

使用本页顶部的 Cursor 或 VS Code 按钮，在你首选的 Agent 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 agent mode）

点击本页顶部的 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"
            }
        }
    }
}

自定义集成

在 Agent 的虚拟化环境中安装远程 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 令牌保存在自己的计算机上，请改为在本地运行服务。不要提供令牌，Agent 首次使用时会提示你输入，并且仅在该会话期间将其保存在内存中：

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

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

本地服务还可以限制 Agent 的操作范围。这些变量对托管端点 mcp.edgegap.dev 不起作用：

变量	默认值	用途
EDGEGAP_API_TOKEN	（提示输入）	API 令牌。可选：不提供时会在首次使用时提示输入。系统会自动添加 token 前缀。切勿将其作为命令行参数传入。
EDGEGAP_READ_ONLY	0	设为 1 后，将不再注册会更改内容的工具（在工具中以 ● 标记），从而防止 Agent 被诱导调用这些工具。
EDGEGAP_APP_ALLOWLIST	（空）	以逗号分隔的应用名称。限制 Agent 可创建应用和部署应用的范围。读取操作（列出应用和版本）不受限制，部署运行后也不受限制。请参阅 DESIGN.md。
EDGEGAP_MAX_DURATION_MINUTES	60	限制 Agent 可为某个版本设置的 max_duration 上限。
EDGEGAP_MAX_AGENT_DEPLOYMENTS	5	当运行中的 edgegap-mcp 标记部署数量达到此值时，edgegap_deploy 会拒绝执行。设为 0 可关闭此上限。
EDGEGAP_TIMEOUT_MS	30000	每个请求的 HTTP 超时时间。
EDGEGAP_SKILLS_CHECK	on	设为 off 后，技能工具将不再从 GitHub 读取最新技能版本。

📚 技能

此服务包含 Edgegap Agent 技能：经过测试、循序渐进的工作流，帮助你将多人游戏上线，其中包括模板（Dockerfile、匹配器配置、Unity C# 和 Unreal C++ 插件）以及已知问题。任何连接到 Edgegap MCP 的 Agent 都能使用这些技能，无需单独安装，也无需令牌；系统会要求 Agent 在处理游戏项目之前加载相应的技能。

技能	适用场景
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	Photon 的 Simple FPS 示例，运行在 Edgegap 专用服务器上。
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	使用 EOS Voice 为运行在 Edgegap 上的 Unreal 游戏提供语音聊天：服务端房间令牌、对局房间和队伍房间。
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 也会在技能标题下方添加相同提示。 保持已安装的技能为最新版本。 如果你也在 Agent 中安装了这些技能（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 中传入你已加载的版本，它会告知哪些版本落后，以及如何更新。

🧰 工具

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

工具	功能
edgegap_context	显示此服务连接的 API、其版本、服务是本地还是托管，以及当前生效的限制措施。不调用 API；绝不显示令牌。

首次部署前

工具	功能
edgegap_generate_dockerfile	为服务器构建编写 Dockerfile：包括构建文件夹、服务器二进制文件或启动脚本、端口和启动参数，并设置正确的无头模式标志（Unity -batchmode -nographics、Godot --headless）、为 Unreal 配置非 root 用户，以及匹配的端口。它会列出所有需要假设的事项，供你的 Agent 确认。适用于 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 令牌，它会让你的 Agent 提示你改从控制面板的 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 ●	修改现有版本：更换镜像标签、开启或关闭版本、最长运行时长、注册表登录信息、镜像缓存（force_cache）、关闭宽限期、端口和环境变量。仅修改传入的字段，但 ports 和 env 会替换整个列表。正在运行的部署仍使用旧设置。
edgegap_list_locations	列出 Edgegap 部署服务的城市；也可指定一个版本，仅列出当前有容量的城市。
edgegap_list_ping_beacons	列出游戏客户端在匹配前用于测量延迟的 ping 信标。
edgegap_deploy ●	在靠近玩家的位置部署权威专用服务器。始终带有 edgegap-mcp 标签，并报告 Edgegap 将在何时停止该服务器。
edgegap_wait_for_deployment	等待服务器就绪并返回连接地址。
edgegap_get_deployment	读取部署的状态。
edgegap_list_deployments	列出运行中的部署，可按应用、版本、状态、标签等筛选，并按运行时长排序。查找仍在运行的服务器；only_agent_deployments: true 会列出 Agent 启动的所有服务器。请参阅筛选部署。
edgegap_get_deployment_logs	在部署运行期间读取容器日志和崩溃详情。部署停止后，仅当已设置 Endpoint Storage 时才会保留日志。
edgegap_get_deployment_metrics	汇总 CPU、CPU 限流、内存和网络用量（最新值、平均值、峰值），用于确定版本规格或检查崩溃原因。
edgegap_stop_deployment ●	根据确切的请求 ID 停止一个部署。不支持批量停止。

匹配

工具	功能
edgegap_build_matchmaker_config	生成匹配配置（队伍、队伍人数、可选的延迟规则和扩展规则），并检查要部署的版本是否存在。浏览器（WebGL）客户端请设置 allowed_cors_origins。将结果上传到控制面板以创建匹配服务；该服务会为每场比赛启动一台专用服务器。

在匹配中了解有关配置的更多信息。

中继（仅适用于主机-客户端游戏）

中继不是游戏服务器：它会在一名玩家的游戏托管比赛期间转发流量。请参阅专用服务器还是中继？。

工具	功能
edgegap_create_relay_session ●	为玩家创建中继会话，并返回中继地址和每位玩家的授权令牌。
edgegap_get_relay_session	读取中继会话。
edgegap_list_relay_sessions	列出打开的中继会话，以查找仍在运行的会话。不包含授权令牌。
edgegap_authorize_relay_user ●	添加稍后加入的玩家。
edgegap_revoke_relay_user ●	从中继会话中移除一名玩家。
edgegap_delete_relay_session ●	关闭中继会话。

警告

部署和中继会话在运行期间会产生费用。请让你的 Agent 在测试部署结束后停止它们，并删除测试中继会话。

示例提示词

• “为我的 Unity 服务器构建编写一个 Dockerfile，然后推送并部署一台离我近的服务器。”
• “检查我的 Edgegap Dockerfile 并修复问题。”
• “为我最新版本的 2v2 对局创建匹配器配置。”
• “我的部署失败了。读取日志并告诉我原因。”
• “我的游戏使用主机-客户端网络。为两名玩家设置 Edgegap 中继。”

🛡️ 防护措施

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

防护措施	作用
试运行	每个会产生更改的工具都需要设置 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 没有针对单次部署的时间限制，因此，在其他位置创建的版本可以运行至其自身时限（默认值为 1440 分钟）；如果超过一小时或没有时限，结果会发出警告。
不允许使用可变镜像标签	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、通配符和列表都会被拒绝。不支持批量停止。
每个结果都显示主机	每个结果都会以 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 状态、耗时、是否为试运行、关于调用的少量信息（部署等待的结束方式、验证结果、加载了哪项技能）、到达的黄金路径步骤，以及服务版本和 Cloudflare 的国家/地区代码。调用失败时，还会发送错误消息（移除你的令牌、所传参数的值，以及任何看起来像凭据、IP 地址或 ID 的内容，并截断至 300 个字符）。部署 ID 只会以带密钥的哈希形式发送。只允许发送命名元数据属性。它绝不会发送你的令牌、工具参数值（IP 地址、环境变量、应用或镜像名称）或结果，并且 GeoIP 已关闭。它不会向工具添加任何参数。来自同一令牌的事件会按该令牌的带密钥、不可逆哈希进行分组。完整列表见 docs/analytics.md。若要退出，请发送请求头 X-Edgegap-Telemetry: off（或 DNT: 1），或者使用本地服务。

🚨 故障排除

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

401 Unauthorized

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

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 应执行下一步，而不是重试。

尚无令牌

技能（edgegap_list_skills、edgegap_get_skill）、edgegap_context、edgegap_generate_dockerfile 和 edgegap_validate_server_config 无需令牌即可使用，因此 Agent 可以先准备服务构建。在 app.edgegap.com 创建账户，并在 User Settings → Tokens 下创建令牌。使用 check_token: true 调用 edgegap_context，会告知会话是否存在令牌且已通过验证，并显示令牌末四位，方便你在该页面找到它。

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

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

其他 API 错误

请参阅我们的 API 参考，了解各个 API 端点可能返回的错误响应。

说明

如果需要帮助，请通过 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。在将其暴露到专用网络之外之前，请阅读 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 生成器、注册表、部署、relay 和 matchmaker 工具
test/http.mjs	自托管 HTTP 服务：无需令牌即可发现服务、每个请求使用各自的令牌、外部凭据
test/spec.mjs	服务发送的每个端点和请求正文字段都列在 spec/ 中（通过空运行检查写入工具）
test/snapshot.mjs	工具名称、描述、架构和说明与 test/tools.snapshot.json 一致；有意修改后运行 npm run snapshot:update
test/live-check.mjs	不包含在 npm test 中。使用来自非生产组织的令牌对真实 API 运行测试

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