Edgegap

Edgegap MCP 服务

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

👉 支持的功能

提示

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

在以下情况下使用我们的 MCP 服务：

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

警告

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

说明

如需帮助，请通过 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 模式）

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

大多数 Agentic 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]），而不要使用始终指向最新版本的配置。已在官方 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 都可以使用这些技能，无需单独安装或提供令牌，并且会被告知在处理游戏项目之前加载相应的技能。

技能	适用场景
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_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 并修复所有问题。”
• “我的部署失败了。读取日志并告诉我原因。”
• “我上一场对局用了多少 CPU 和内存？据此调整我的版本配置。”
• “我的游戏使用主机－客户端网络。为两名玩家设置一个 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 未授权

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

工具调用失败

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

警告

这是一个已知限制，将在近期解决，敬请关注后续更新！

403 禁止访问

你的 MCP 集成可能使用了模板令牌或已删除的令牌。请确认集成使用的令牌值与控制面板中显示的令牌完全一致。

424 无法拉取镜像

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

注册表凭据不可用

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

"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 创建账户，并在 用户设置 → 令牌下创建令牌。使用 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 生成器、注册表、部署、转发和匹配器工具
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。