> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/zh/docs/mcp-ji-cheng.md).

# MCP 集成

通过我们的 MCP 服务器将 AI 编码代理连接到 Edgegap：用于将游戏服务器容器化、部署、匹配和排查问题的工具，以及针对每个引擎和网络代码的经过测试的工作流程。

我们的 MCP 服务器为你的自定义 AI 编码代理提供了启动自定义游戏服务器构建所需的工具，并通过我们已验证的测试套件帮助验证每个集成步骤。

## 👉 支持的功能

{% hint style="success" %}
**新用户 - 请从** [Unity](https://docs.edgegap.com/zh/unity.md)**,** [Unreal Engine](https://docs.edgegap.com/zh/unreal-engine.md)**，或** [Godot](https://docs.edgegap.com/zh/godot.md)**.** 建议仅在你已将可工作的容器化游戏服务器上传到容器镜像仓库之后再使用 MCP 服务器。
{% endhint %}

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

* **将你的游戏服务器容器化** - 你的代理会为你的构建编写 Dockerfile（或审查你已有的），并遵循最佳实践，将镜像推送到我们的私有容器镜像仓库，并移除未使用的旧镜像标签以回收仓库容量。
* **部署专用服务器** - 创建并更新应用版本，查看可用位置，将部署放到离玩家最近的地方，并获取带端口的服务器 IP 以测试客户端连接。
* **构建 CI/CD 流水线** - 从构建系统测试你的部署和回收。
* **排查游戏服务器问题** - 检查应用版本和部署状态，读取容器日志以及 CPU/内存使用情况，或复现失败的部署。
* **运行客户端-主机和点对点游戏** - 创建提供 NAT 穿透并避免连接阻塞的中继会话。查看 [编排模型](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#orchestration) 后再决定。

{% hint style="warning" %}
MCP 不支持/超出范围：构建 Linux 服务器可执行文件；创建、启动或停止匹配器（在控制台中上传生成的配置）；服务器浏览器；大厅；托管集群；私有舰队；或计费。
{% endhint %}

{% hint style="info" %}
如果你需要帮助， [请通过 Discord 联系我们](https://discord.gg/MmJf8fWjnt)。关于实时游戏支持，请查看我们的 [工单系统](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### 技能

列出并获取代理技能，包括经过完整测试的工作流、代码模板，以及针对引擎、游戏后端和网络代码已知陷阱的防护措施：

* Unity，包括 Mirror、Netcode for GameObjects、FishNet、PurrNet、Photon Fusion 1 和 2。
* Unreal Engine - 包括 EOS 语音聊天。
* Godot - ENET 和 netfox。
* Colyseus、Nakama、PlayFab、Three.js 和 Manus AI。

你的代理会在行动前加载与项目匹配的技能，并且 `edgegap_update_skills`  会保持你本地安装的副本始终最新。 [独立技能也可在 GitHub 上获取。](https://github.com/edgegap/llm-agent-skills)

### 防护措施

你的 API 令牌可以在组织内执行任何操作，因此 MCP 服务器会限制代理对它的使用：

* **试运行** - 每个会更改内容的工具都可以先显示准确请求，而不发送任何内容。
* **容器中不放令牌** - 如果你的 API 令牌出现在环境变量、标签或 webhook URL 中，部署和版本会被拒绝。
* **不允许移动镜像标签** - `latest`  和空标签也会被拒绝，因为 Edgegap 会按标签缓存镜像。
* **部署上限与自动停止** - 每个部署都会被标记为 `edgegap-mcp`  ，以便找到并停止；系统会报告 Edgegap 何时会停止它，而且循环运行的代理一次最多只能启动少量几个。
* **一次一个** - 停止部署和删除仓库标签都需要一个准确的 ID；不支持批量删除。

### 示例提示

* *"为我的 three.js 服务器构建编写一个 Dockerfile，然后推送并在离我最近的位置部署一个服务器。"*
* *"检查我的 Dockerfile 是否适用于 Edgegap，并修复任何问题。"*
* *"我的部署失败了。读取日志并告诉我原因。"*
* *"我上一场对局用了多少 CPU 和内存？请据此为我的版本做容量规划。"*
* *"我的游戏使用主机-客户端网络。为两个玩家设置一个 Edgegap 中继。"*

## 🚀 安装

MCP 服务器安装非常简单：

1. 为以下环境安装 MCP 服务器 [MCP 集成](https://docs.edgegap.com/zh/docs/mcp-ji-cheng.md#popular-agents) 或使用 [MCP 集成](https://docs.edgegap.com/zh/docs/mcp-ji-cheng.md#custom-integration).
2. 生成并附加一个供你的代理与我们的 MCP 服务器一起使用的 API 令牌：

在以下位置生成 Edgegap API 的秘密令牌： [控制面板 - 用户设置 / 令牌](https://app.edgegap.com/user-settings?tab=tokens).

在每个 API 请求的 HTTP 标头中添加秘密令牌（包含单词 `token`):

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

{% hint style="danger" %}
**请勿在游戏客户端中集成 Edgegap API 端点，因为您的 API 令牌可以无限制地访问您的帐户。请参阅** [集成](https://docs.edgegap.com/zh/docs/api/ji-cheng.md) **，了解面向客户端的安全 API 端点和功能。**
{% endhint %}

{% hint style="success" %}
如果您的秘密令牌遭到泄露或被盗，请在控制面板中将其删除并重新创建。
{% endhint %}

### 常用代理

在你偏好的智能代理 IDE 中安装 Edgegap MCP 服务器： <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=Edgegap&#x26;config=eyJ1cmwiOiJodHRwczovL21jcC5lZGdlZ2FwLmRldi9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiIifX0%3D" class="button secondary" data-icon="cursor">Cursor</a><a href="vscode:mcp/install?%7B%22name%22%3A%22Edgegap%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.edgegap.dev%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22%22%7D%7D" class="button secondary" data-icon="vscode">VS Code</a>

然后将你的令牌添加到 `Authorization` 头中。

#### Claude Code

{% code collapsedlinecount="10" %}

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

{% endcode %}

#### ChatGPT Codex

Codex 会从环境变量中读取令牌。将以下内容添加到 `~/.codex/config.toml`，然后将 `EDGEGAP_API_TOKEN` 设置为 Codex 启动时所使用环境中的令牌：

{% code title="config.toml" collapsedlinecount="10" %}

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

{% endcode %}

#### Claude Desktop

下载 [edgegap-mcp.mcpb](https://github.com/edgegap/llm-mcp-server/releases/latest/download/edgegap-mcp.mcpb) 并打开它。Claude Desktop 会将 MCP 服务器作为扩展安装，并请求你的 API 令牌，然后将其保存在操作系统的安全存储中。

{% hint style="info" %}
claude.ai 和 Claude Desktop 中的自定义连接器目前还不能发送 `Authorization` 头，因此它们会连接到 `mcp.edgegap.dev` ，但每次工具调用都会失败。在 Claude Desktop 中，请改用上面的单击安装扩展。
{% endhint %}

#### mcp.json

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

{% code title="mcp.json" collapsedlinecount="10" %}

```json
{
    "mcpServers": {
        "Edgegap": {
            "type": "http",
            "url": "https://mcp.edgegap.dev/mcp",
            "headers": {
                "Authorization": "EDGEGAP_API_TOKEN"
            }
        }
    }
}
```

{% endcode %}

### 自定义集成

官方仓库是我们 MCP 服务器自定义集成的唯一权威来源：

{% embed url="<https://github.com/edgegap/llm-mcp-server>" %}

为了将你的 API 令牌保留在自己的机器上，请使用 Node 18+ 在本地运行 MCP 服务器。先不提供令牌，你的代理会在首次使用时向你请求：

{% code title="使用 npx 的本地服务器" collapsedlinecount="10" %}

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

{% endcode %}

本地服务器还可以进一步限制，例如仅使用只读工具或限制为应用列表。请参见 [仓库](https://github.com/edgegap/llm-mcp-server#local-server) 中的设置。

或者从你的代理虚拟化环境连接到远程 Edgegap MCP 服务器（切勿在你的项目中这样做！）：

{% code title="使用 npx 包的 node" collapsedlinecount="10" %}

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

{% endcode %}

{% code title="使用 uvx 包的 python" collapsedlinecount="10" %}

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

{% endcode %}

## 🚨 故障排查

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

### 401 未授权

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

### 工具调用失败

你的客户端缺少 Edgegap 令牌。这通常发生在 claude.ai 和 Claude Desktop 自定义连接器上，因为它们不能发送 `Authorization` 头。请参见 [Claude Desktop](https://docs.edgegap.com/zh/docs/mcp-ji-cheng.md#claude-desktop) 了解替代方案。

{% hint style="warning" %}
这是一个已知限制，短期内会得到解决，请关注更新！
{% endhint %}

### 403 禁止访问

你的 MCP 集成很可能使用了模板令牌或已删除的令牌。请验证你的集成所使用的令牌值是否与控制台中显示的令牌完全一致。对于中继工具，403 表示你的组织没有中继访问权限。

### 424 无法拉取镜像

请验证你的仓库、镜像名称和标签，并确认该标签已被推送（请你的代理列出仓库标签）。对于 Edgegap 仓库中的镜像，镜像名称必须包含你的项目，例如 `my-project/my-game-server`.

### 仓库凭据不可用

检索凭据需要一个特殊的快速开始令牌。 [请在控制台中以下位置创建一个： **容器镜像仓库**](https://app.edgegap.com/registry-management/repositories/list)，或推送到其他仓库（例如 Docker Hub、GitHub、AWS ECR、GCP、GitLab）。

请参见 [外部仓库](https://docs.edgegap.com/docs/tools-and-integrations/docker/external-registries) ，了解 Edgegap 容器镜像仓库的完全受支持替代方案。

### 本地可以启动，但在 Edgegap 上不行

请让你的代理验证服务器配置，或生成新的 Dockerfile。最常见的原因是镜像在 Apple Silicon 上构建时没有使用 `docker build --platform linux/amd64`，服务器监听的端口与版本暴露的端口不同，或者将 UDP 传输配置成了 TCP。

### 其他 API 错误

请查阅我们的 [API 参考](https://docs.edgegap.com/zh/docs/api.md) ，了解各个 API 端点可能返回的错误响应。

{% hint style="info" %}
如果你需要帮助， [请通过 Discord 联系我们](https://discord.gg/MmJf8fWjnt)。关于实时游戏支持，请查看我们的 [工单系统](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}
