Edgegap

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

edgegap-mcp

一个用于 Edgegap 的 MCP 服务器，让编码代理能够帮助开发者从“我有一个游戏服务器容器”到“玩家已连接到它”，而无需开发者阅读 API 参考文档。

十个工具，精心挑选。并非从 OpenAPI 规范生成——原因请参阅 范围。

安装

有两种运行方式。根据您对令牌去向的在意程度来选择——请参阅 您的令牌去向。

远程端点

由 Edgegap 作为 Cloudflare Worker 托管。无需安装任何内容。

{
  "mcpServers": {
    "edgegap": {
      "type": "http",
      "url": "https://mcp.edgegap.dev/mcp",
      "headers": { "Authorization": "token YOUR_API_TOKEN" }
    }
  }
}

也可作为 claude.ai 中的自定义连接器使用：添加 https://mcp.edgegap.dev/mcp 并提供相同的令牌。

本地

在您自己的机器上运行，由您的编辑器启动。在 MCP 客户端配置中添加一行即可，无需克隆，无需构建。

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

适用于 Claude Code、Cursor、Codex 和 VS Code。在生产环境中固定版本（@edgegap/mcp@0.1.5），而不是浮动在最新版本上。

已在官方 MCP 注册表中注册为 dev.edgegap/mcp。

Node 版本： 本地服务器需要 Node 18+。自行部署 Cloudflare Worker 副本需要 Node 22+，因为 wrangler 需要它。

您的令牌去向

这因模式而异，而差异正是两种模式都存在的原因。

本地。 服务器作为您自己计算机上的一个进程运行。第一次工具调用会询问您令牌，显示其授权内容，并要求在接受之前明确确认。该令牌随后存放的位置，详尽列出：

• 该进程内存中的一个变量，在您的编辑器会话期间有效

这就是全部列表。不在磁盘上。不在配置文件中。不在日志中。不在任何 Edgegap 服务器上——发送到 Edgegap 的唯一内容是 API 调用本身，就像您运行了 curl 一样。关闭编辑器将完全撤销此服务器的访问权限。

远程。 您的令牌在每个请求中发送到 mcp.edgegap.dev，并从那里转发到 Edgegap API。它经过 Edgegap 运营的基础设施。Worker 在请求生命周期内持有它，并且不会持久化，但这是“我们不存储它”的说法，而不是“我们从未看到它”的说法。两者是不同的，只有本地模式才能实现后者。

在 https://app.edgegap.com/user-settings?tab=tokens 生成令牌。

在本地模式下，设置 EDGEGAP_API_TOKEN 优先于提示，适用于 CI 和无法显示提示的客户端。不要将令牌作为命令行参数传递——参数通过 ps 对其他进程可见，服务器在检测到时会发出警告。

使用哪种。 远程用于首次尝试、演示或监督会话，其中设置摩擦比保管更重要。本地用于任何无人值守、任何组织中有活跃游戏、以及任何您宁愿不扩展不必要信任的情况。下面描述的防护措施仅存在于本地模式。

连接代理之前请阅读

Edgegap API 令牌无法限定范围。 一个令牌授权整个组织中的所有应用程序、所有版本、所有正在运行的部署以及您的使用情况。没有仅部署令牌，也没有按应用程序令牌。

值得深思的后果：

• 持有此令牌的代理可以停止生产部署，而不仅仅是它创建的测试部署。
• 提示注入到达代理——来自仓库文件、问题、获取的页面——也会到达令牌。
• 代理记录、回显或发送给模型提供商的任何内容都是令牌可能最终出现的地方。此服务器不会记录它，但无法控制代理的其余部分做什么。
• 在远程端点上，相同的无范围令牌在每次调用时还会由 Edgegap 的 Worker 处理。

推荐的设置，按谨慎程度递减：

情况	设置
无人值守或自主代理	本地模式。单独的非生产组织，加上 EDGEGAP_READ_ONLY=1
监督代理，组织中有活跃游戏	本地模式。EDGEGAP_APP_ALLOWLIST 限定到正在处理的应用程序，加上 EDGEGAP_MAX_DURATION_MINUTES。先阅读 允许列表的范围——已经运行的部署不在覆盖范围内
独立开发者，无生产工作负载	任一模式。默认设置即可；完成后撤销令牌

允许列表和只读标志在本地服务器中强制执行，这意味着它们保护的是犯错误的代理，而不是已被入侵而直接调用 API 的代理。它们缩小了爆炸半径；它们不会消除它。

允许列表的范围

EDGEGAP_APP_ALLOWLIST 由四个接受应用程序名称的工具强制执行：edgegap_create_app、edgegap_list_app_versions、 edgegap_create_app_version 和 edgegap_deploy。

它不由五个以 request_id 为键的工具强制执行： edgegap_get_deployment、edgegap_wait_for_deployment、 edgegap_list_deployments、edgegap_stop_deployment 和 edgegap_get_deployment_logs。设置了允许列表的代理可以列出组织中的每个部署，然后检查、读取日志或停止其中任何一个——包括列表之外应用程序的部署。

因此，允许列表限定的是代理可以创建和部署到的范围，而不是一旦运行就能触及的范围。这比本文档早期版本暗示的要窄。

要获得今天更强的保证，请使用 EDGEGAP_READ_ONLY=1，它根本不注册五个变更工具，或者将代理指向一个单独的非生产组织。两者都不受此差距的影响。

由 Syed Anas Mohiuddin 于 2026 年 9 月报告。

环境变量

这些配置本地服务器。在远程端点上，它们由 Edgegap 设置，不能按开发者更改——如果您需要其中任何一个，请在本地运行。

变量	默认值	用途
EDGEGAP_API_TOKEN	(提示)	API 令牌。可选——省略它，开发者将在首次使用时被询问。token 前缀会为您添加。
EDGEGAP_READ_ONLY	0	设置为 1，五个变更工具将永远不会被注册。代理无法看到它们，因此无法被诱导调用它们。
EDGEGAP_APP_ALLOWLIST	(空)	逗号分隔的应用程序名称。设置后，四个以应用程序为键的工具拒绝处理其他任何内容。不限定五个以 request_id 为键的工具——请参阅 允许列表的范围。
EDGEGAP_MAX_DURATION_MINUTES	60	代理可以在版本上设置的 max_duration 上限。限制无人值守代理的失控成本。
EDGEGAP_TIMEOUT_MS	30000	每个请求的 HTTP 超时。

工具

十个工具，按黄金路径的顺序列出。两种模式下都是相同的十个。

工具	变更	用途
edgegap_list_apps		在做任何事之前先定位。防止重复应用程序。
edgegap_create_app	●	为版本创建容器。
edgegap_list_app_versions		查找可部署的版本，或从可用的版本复制设置。
edgegap_create_app_version	●	使用 CPU、内存和端口注册容器镜像。
edgegap_deploy	●	在指定玩家附近启动一个实例。
edgegap_get_deployment		单次状态读取。
edgegap_wait_for_deployment		带退避轮询直到就绪，然后返回连接地址。
edgegap_list_deployments		查找早期会话中的孤立服务器。
edgegap_stop_deployment	●	优雅 SIGTERM，一次一个部署。
edgegap_get_deployment_logs		失败后的容器输出和崩溃退出代码。

设计决策

精选而非生成。 Edgegap API 大约有六十个操作。为每个操作自动生成一个工具会将所有六十个描述放入代理的上下文中，每次轮次都会显著降低工具选择质量。这十个覆盖了转化新开发者的路径。

wait_for_deployment 是一个工具，而不是一个循环。 如果放任自流，代理会在紧密循环中调用状态端点，浪费轮次并提前放弃。将轮询和退避折叠到一次调用中，消除了代理驱动部署中最常见的失败。

错误是为自我纠正而编写的。 424 返回时说明镜像无法拉取以及要检查哪些字段。422 表示尝试不同的坐标或降低资源请求。代理可以据此采取行动，而无需往返询问人类。

在发送到网络之前进行本地验证。 内存与 CPU 的比率和缺失的玩家位置在这里被捕获，而不是作为不透明的 400 出现。

批量操作被刻意省略。 stop 接受一个 request_id。没有批量停止工具，因为带有过滤表达式和错误的代理可以停止生产舰队。

既有托管端点又有本地包。 托管端点消除了从找到此服务器到调用工具之间的每一步，这是大多数开发者放弃的地方。本地包是运行服务器而不将无范围令牌的保管权扩展到第三方（包括我们）的唯一方式。两者都不支配另一个，所以两者都发布。请参阅 worker/DECISION.md 了解更长的版本。

范围

有意不暴露：匹配、中继、私有舰队、智能舰队、端点存储、ACL/白名单条目、部署标签、指标、容器注册表管理、DNS 配置。

这些是真实的功能，但它们属于已经在平台上运营的工作室，而不是部署第一个服务器的开发者。添加它们会用转化路径换取表面积。

已知限制：询问令牌

这适用于本地模式，其中令牌通过引导收集而不是从配置中读取。

MCP 规范说服务器不应使用引导来收集敏感数据，而 API 令牌是敏感的。此服务器仍然这样做，因为在任何工作之前要求在配置文件中提供令牌是入门漏斗中最大的流失点，而服务器的全部意义就是消除设置摩擦。

这是一个刻意的权衡，而不是要复制的模式。使其可辩护的是 src/auth.ts 中的缓解措施集——仅内存存储、通俗易懂的披露、必需的确认、从所有输出中编辑，以及环境变量在存在时始终获胜。移除其中任何一个都会破坏权衡。

真正的修复在 Edgegap 方面，并且会改进两种模式：限定范围、可撤销、仅部署的凭据，通过 OAuth 颁发而不是作为秘密粘贴。在这些存在之前，交互式提示是一种变通方法，并在代码中标记为如此。

开发

npm run typecheck
node smoke.mjs      # handshake, tool registration, read-only mode
node guards.mjs     # local validation and allowlist enforcement
node elicit.mjs     # token prompt: accept, refuse acknowledgement, decline, no support

这些都不会进行网络调用。elicit.mjs 断言提示声明了组织范围的范围，确认是必需的，令牌永远不会出现在工具输出中，并且拒绝会产生停止并报告的消息而不是重试循环。