Edgegap

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

Edgegap MCP Server

透過我們的 MCP server 將 AI 程式碼代理連接至 Edgegap。您的代理可以從頭到尾完成無頭伺服器建置，直到玩家成功連線：撰寫或檢查 Dockerfile、將映像推送至您的 Edgegap 私有登錄檔、在靠近玩家的位置部署權威專用伺服器，並在發生問題時讀取日誌。

👉 支援的功能

[!TIP] 使用 Unity、Unreal Engine 或 Godot？ 我們的 Unity、Unreal Engine 和 Godot 指南與外掛仍是這些引擎最快速的途徑。MCP server 可與它們搭配使用，也可獨立用於任何引擎。

以下情況適合使用我們的 MCP server：

• 將遊戲伺服器容器化 - 您的代理會依據最佳實務為您的建置撰寫 Dockerfile（或檢查您現有的 Dockerfile）、將映像推送至我們的私有容器登錄檔，並移除未使用的舊映像標籤以釋出登錄檔容量。
• 部署專用伺服器 - 建立及更新應用程式版本、檢視可用位置、在靠近玩家的位置部署，並取得伺服器 IP 與連接埠以測試用戶端連線。
• 建置 CI/CD 管線 - 從建置系統測試部署並拆除部署。
• 疑難排解遊戲伺服器問題 - 檢查應用程式版本與部署狀態、讀取容器日誌及 CPU／記憶體使用率，或重現失敗的部署。
• 執行用戶端託管與點對點遊戲 - 建立提供 NAT 穿透功能的中繼工作階段，避免連線遭到封鎖。決定前請先參閱協調模型和專用伺服器還是中繼？。

[!WARNING] MCP 不支援的範圍：建置 Linux 伺服器可執行檔；建立、啟動或停止配對器（請在儀表板上上傳產生的設定）；伺服器瀏覽器；大廳；受管理叢集；私有機群；或帳單。

[!NOTE] 如需協助，請透過 Discord 聯絡我們。如需正式上線遊戲的支援，請使用我們的支援單系統。

⚖️ 專用伺服器還是中繼？

Edgegap 可透過兩種方式託管您的多人遊戲。我們建議使用專用伺服器，MCP server 也採取相同建議：您的代理預設會使用專用伺服器，只有在您選擇用戶端託管架構時才會使用中繼。

	專用伺服器（建議）	中繼
Edgegap 執行的內容	您的無頭伺服器建置，部署在靠近玩家的位置	僅轉送流量，不執行遊戲程式碼
執行遊戲的一方	伺服器	一名玩家的遊戲（主機）
作弊	困難得多，伺服器具有權威性	主機可以任意修改
公平性	每位玩家都直接連線至伺服器	主機沒有延遲，其他人都要經過兩個節點
主機離開時	對戰會繼續	對戰會結束，除非您的遊戲支援主機遷移
效能受限於	伺服器配置的 CPU 與記憶體	主機的電腦與家用網路上傳速度
您需要	容器映像中的伺服器建置	以監聽伺服器（用戶端託管）模式建置的網路程式碼

[!NOTE] 還沒有伺服器映像？ 這不是選擇中繼的理由。您的代理可以使用 edgegap_generate_dockerfile 為您的建置撰寫 Dockerfile。請參閱分散式中繼，深入了解中繼。

🚀 安裝

安裝 MCP server 非常簡單：

1. 為熱門代理安裝 MCP server，或使用自訂整合。
2. 產生 API token，並提供給您的代理，以便搭配我們的 MCP server 使用。

請在儀表板 - 使用者設定 / Tokens中產生（並檢視）Edgegap API 的密鑰 token。

在每個 API 請求中，將密鑰 token 加入 HTTP 標頭（包含 token 一詞）：

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

[!CAUTION] 請勿在遊戲用戶端中整合 Edgegap API 端點，因為您的 API token 可無限制存取您的帳戶。如需安全的用戶端 API 端點與函式，請參閱整合。

[!TIP] 如果您的密鑰 token 遭到入侵或外洩，請從儀表板刪除並重新建立。

此 token 適用於整個組織，無法限定於單一應用程式。將 token 提供給無人值守的代理前，請先閱讀 DESIGN.md。

熱門代理

使用本頁頂端的 Cursor 或 VS Code 按鈕，在您偏好的代理式 IDE 中安裝 Edgegap MCP server，然後將 token 加入 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 會從環境變數讀取 token，並以 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 設為您的 token。

Claude Desktop 和 claude.ai

claude.ai 和 Claude Desktop 中的自訂連接器無法傳送 Authorization 標頭，因此託管端點永遠收不到它們傳送的 token：連接器會顯示已連線，但每次工具呼叫都會失敗。請改用本機伺服器。

在 Claude Desktop 中，開啟 Settings → Developer → Edit Config，並將本機伺服器加入 claude_desktop_config.json：

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

請勿填入 token，首次使用時系統會提示您輸入。瀏覽器中的 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 server 的用戶端：

{
  "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 server（絕不可安裝在您的專案中！）：

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 token，之後會將 token 保存在作業系統的安全儲存空間中。擴充功能的設定也包含唯讀模式、應用程式允許清單、最長執行時間上限和部署數量上限（即下方的變數）。每個版本都會附上以該版本程式碼建置的套件。任何其他可安裝 MCPB 套件的應用程式也都以相同方式運作。

本機伺服器

若要將 API token 保留在自己的電腦上，請改為在本機執行伺服器。請勿填入 token，代理會在首次使用時提示您輸入，並且只在該工作階段期間將 token 保存在記憶體中：

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

需要 Node 18+。正式環境請固定版本（@edgegap/mcp@0.15.4），不要使用會隨最新版本變動的設定。已在官方 MCP 登錄檔中註冊為 dev.edgegap/mcp。

本機伺服器也能限制代理可執行的操作。這些變數不會影響位於 mcp.edgegap.dev 的託管端點：

變數	預設值	用途
EDGEGAP_API_TOKEN	(提示輸入)	API token。選填：省略後會在首次使用時提示您輸入。系統會自動加上 token 前綴。絕不可將其作為命令列引數傳遞。
EDGEGAP_READ_ONLY	0	設為 1 後，不會註冊會變更內容的工具（在工具中以 ● 標示），因此代理無法被誘導呼叫這些工具。
EDGEGAP_APP_ALLOWLIST	(空白)	以逗號分隔的應用程式名稱。限制代理可建立及部署至哪些應用程式。讀取操作（列出應用程式和版本）不受限制，已啟動的部署也不受限制。請參閱 DESIGN.md。
EDGEGAP_MAX_DURATION_MINUTES	60	代理可為版本設定的 max_duration 上限。若版本的 max_duration 高於此上限或設為無限制，edgegap_deploy 也會拒絕該版本，除非代理在詢問您後傳入 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。若未設定，系統會列出這些命令供您執行。無論如何，手動複製的技能都會從套件改寫。更新程式只會取得路徑、home、temp、locale、proxy 和 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 的代理都能使用這些技能，無須另外安裝或提供 token，並會收到指示，在處理遊戲專案前先載入相符的技能。

技能	適用情境
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	使用 Edgegap 伺服器進行 PlayFab 配對。
edgegap-threejs	使用自有 Node.js 伺服器的 Three.js 和其他瀏覽器遊戲。
edgegap-matchmaking	適用於任何引擎的配對設計：由誰負責、玩家檔案、隊伍、區域選擇、補位、第三方配對器。
edgegap-manus	使用 Manus 建置的瀏覽器遊戲：後端配對、Steam 登入、簽署的加入權杖、Node WebSocket 伺服器。
edgegap-unreal	Unreal Engine 端到端流程：原始碼引擎、Linux 伺服器、配對器、端到端測試。
edgegap-eos-voice	在 Edgegap 上使用 EOS Voice 為 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 則會在技能標題下方加入相同提示。

保持已安裝的技能為最新版本。 如果你也在代理程式中安裝了這些技能（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: true：它會回傳確切的方法、主機、路徑和本文，並遮蔽 token、registry token 和環境變數值，不會送出任何內容。本機檢查仍會執行。
容器中不得包含 token	如果 API token 出現在環境變數名稱或值、標籤或 webhook URL 中，就會拒絕部署或版本操作，且不會送出任何內容。環境變數值絕不會回傳。
Agent 標籤	每次部署都會加上 edgegap-mcp 標籤，即使 agent 傳入自己的標籤也一樣。使用 edgegap_list_deployments 搭配 only_agent_deployments: true 即可找出所有部署。
自動停止	每次部署都會回報 Edgegap 何時會停止該部署：版本的 max_duration，上限為 EDGEGAP_MAX_DURATION_MINUTES（預設為 60），適用於 agent 建立的版本。Edgegap 沒有每次部署的時間限制，因此若部署版本的 max_duration 超過此上限或設為無限制（在其他地方建立的版本預設為 1440 分鐘），就會遭到拒絕；除非 agent 傳入 allow_long_running: true，而且只有在先詢問你之後才會被告知這麼做。
每次執行的部署數	本機伺服器每個程序最多送出 EDGEGAP_MAX_DEPLOYS_PER_RUN 次部署（預設為 20），失敗的部署也計入，因為遭拒的部署仍可能建立部署項目。如果 API 拒絕部署但仍建立了部署項目，錯誤訊息會指出該項目，讓 agent 可以停止它。
不使用可變動的映像標籤	edgegap_create_app_version 會拒絕 latest（不區分大小寫）、空標籤或 Docker 不接受的標籤，且不會送出任何內容：Edgegap 會依標籤快取映像，因此重新推送的標籤可能會部署過時的建置版本。也會拒絕在 latest 上部署現有版本，以及要求提供 latest 的 registry 推送命令。
映像參照檢查	如果 docker_image 同時包含 registry 主機、標籤或摘要（例如 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 會依照確切的 request ID 停止單一部署。空 ID、萬用字元和清單都會遭到拒絕。不提供批次停止功能。使用 EDGEGAP_STOP_OWN_ONLY=1 時，只會停止帶有 edgegap-mcp 標籤的部署。
謹慎刪除	edgegap_delete_app_version 和 edgegap_delete_app 都只接受一個確切名稱，且當該項目仍有部署在執行時會遭到拒絕。只有在 max_versions 涵蓋其版本時，才會刪除含有版本的應用程式。
Webhook 和 bucket URL	部署 webhook 和 Endpoint Storage 端點必須是 https URL，且不得包含憑證；若其中包含你的 API token，也會遭到拒絕。
每個結果都包含主機	每個結果都會以 API 主機開頭，例如 [api.edgegap.com]；若 EDGEGAP_BASE_URL 指向其他位置，則會顯示 [custom · host]。若基底 URL 指定 api.edgegap.com，就必須完全符合 https://api.edgegap.com，否則伺服器會拒絕啟動。
遮蔽	token 會在錯誤傳送給 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 狀態、耗時、是否為試執行、一些呼叫相關資訊（部署等待的結果、驗證結果、載入的技能）、到達的 golden-path 步驟，以及伺服器版本和 Cloudflare 的國家代碼。呼叫失敗時，也會傳送錯誤訊息（移除你的 token、你傳入的引數值，以及任何看起來像憑證、IP 位址或 ID 的內容後，截短至 300 個字元）。部署 ID 只會以帶金鑰的雜湊形式傳送。只有具名的中繼資料屬性會被允許傳送。絕不會傳送你的 token、工具引數值（IP 位址、環境變數、應用程式或映像名稱）或結果，且 GeoIP 已停用。工具不會新增任何參數。同一個 token 的事件會以該 token 的帶金鑰、不可逆雜湊分組。完整清單請見 docs/analytics.md。若要退出，請傳送標頭 X-Edgegap-Telemetry: off（或 DNT: 1），或使用本機伺服器。

🚨 疑難排解

查看常見錯誤代碼，並瞭解如何解除整合的限制。

401 Unauthorized

你的 MCP 整合很可能未正確包含 Authorization 標頭。

Tool Call Failed

你的用戶端缺少 Edgegap token。這會發生在 claude.ai 和 Claude Desktop 自訂連接器上，因為它們無法傳送 Authorization 標頭。替代方案請見 Claude Desktop and claude.ai。

[!WARNING] 這是已知限制，近期將會解決，敬請留意後續更新！

403 Forbidden

你的 MCP 整合可能正在使用範本 token 或已刪除的 token。請確認整合使用的 token 值與儀表板上顯示的 token 完全一致。

424 Image Could Not Be Pulled

Edgegap 無法拉取你的容器映像。請檢查 repository、映像名稱和標籤，並確認標籤已推送（請 agent 列出 registry 標籤）。若映像位於 Edgegap registry，映像名稱必須包含你的專案，例如 my-project/my-game-server。

Registry Credentials Unavailable

Edgegap 只會向 Unity 和 Unreal 外掛程式使用的快速入門 token 提供 registry 憑證，因此使用一般 API token 時，agent 無法擷取憑證，會改為向你索取。請從 儀表板 的 Container Registry 區段複製 Project、Username 和 Token，或推送至 Edgegap 可拉取的其他 registry（Docker Hub、GitHub、AWS ECR、GCP、GitLab）。請見 External Registries。

"status": "empty" 或 "not_configured"

這不是錯誤。清單中沒有項目（尚無應用程式、沒有執行中的部署、從未推送過映像），或組織尚未設定的功能（relays、此 token 無法讀取的 registry），都會以包含 status 和 next_step 的正常結果回傳。你的 agent 應繼續下一步，而不是重試。

尚無 Token

技能（edgegap_list_skills、edgegap_get_skill）、edgegap_context、edgegap_generate_dockerfile 和 edgegap_validate_server_config 不需要 token，因此 agent 可以先準備伺服器建置版本。請在 app.edgegap.com 建立帳戶，並在 User Settings → Tokens 建立 token。使用 edgegap_context 搭配 check_token: true，即可確認工作階段是否有 token 且已通過驗證，並顯示其末四個字元，方便你在該頁面找到它。

本機可啟動，但在 Edgegap 上無法啟動

請 agent 驗證伺服器設定，或產生新的 Dockerfile。最常見的原因包括：在 Apple Silicon 上建置映像時未使用 docker build --platform linux/amd64、伺服器監聽的連接埠與版本公開的連接埠不同，或將 UDP 傳輸設定為 TCP。

其他 API 錯誤

請參閱我們的 API Reference，查看個別 API 端點可能回傳的錯誤。

[!NOTE] 如需協助，請透過 Discord 聯絡我們。如需線上遊戲支援，請使用我們的 ticketing system。

🛠️ 自行託管

位於 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 token 傳給容器：每個用戶端都會在每次請求中傳送自己的 token。在將伺服器公開至私人網路以外之前，請先閱讀 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 的最新 commit，然後照常發布：

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	Token 提示：接受、拒絕確認、拒絕、不支援
test/newtools.mjs	使用本機 mock API 測試驗證器、Dockerfile 產生器、registry、部署、relay 和 matchmaker 工具
test/http.mjs	自架 HTTP 伺服器：無 token 時的探索、每個請求各自提供 token、外部憑證
test/spec.mjs	伺服器傳送的每個端點和請求本文欄位都列於 spec/（寫入工具以試執行檢查）
test/snapshot.mjs	工具名稱、說明、結構描述和指示均符合 test/tools.snapshot.json；刻意變更後的 npm run snapshot:update
test/live-check.mjs	不在 npm test 中。使用非正式環境組織的 token，對真實 API 執行

設計決策、安全模型，以及刻意不納入範圍的項目，請見 DESIGN.md。