Edgegap

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

edgegap-mcp

Một máy chủ MCP dành cho Edgegap giúp một tác nhân lập trình đưa nhà phát triển từ trạng thái "tôi có một container máy chủ trò chơi" đến "người chơi đã kết nối với nó" mà không cần nhà phát triển phải đọc tài liệu tham khảo API.

Mười công cụ, được chọn lọc kỹ lưỡng. Không được tạo tự động từ đặc tả OpenAPI — xem Phạm vi để biết lý do.

Cài đặt

Có hai cách để chạy. Chọn dựa trên mức độ bạn quan tâm đến việc token của mình đi đâu — xem Token của bạn đi đâu.

Điểm cuối từ xa

Được Edgegap lưu trữ dưới dạng Cloudflare Worker. Không cần cài đặt gì.

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

Cũng hoạt động như một trình kết nối tùy chỉnh trong claude.ai: thêm https://mcp.edgegap.dev/mcp và cung cấp cùng một token.

Cục bộ

Chạy trên máy của chính bạn, được khởi chạy bởi trình soạn thảo của bạn. Một dòng trong cấu hình máy khách MCP của bạn, không cần clone gì, không cần build gì.

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

Hoạt động trong Claude Code, Cursor, Codex và VS Code. Ghim một phiên bản trong môi trường sản xuất (@edgegap/mcp@0.1.5) thay vì trôi nổi trên bản mới nhất.

Được đăng ký trong sổ đăng ký MCP chính thức với tên dev.edgegap/mcp.

Phiên bản Node: máy chủ cục bộ cần Node 18+. Việc triển khai bản sao Cloudflare Worker của riêng bạn cần Node 22+, vì wrangler yêu cầu điều đó.

Token của bạn đi đâu

Điều này khác nhau theo chế độ, và sự khác biệt đó là lý do cả hai chế độ tồn tại.

Cục bộ. Máy chủ chạy như một tiến trình trên máy tính của chính bạn. Lệnh gọi công cụ đầu tiên yêu cầu bạn cung cấp token, hiển thị những gì nó ủy quyền và yêu cầu xác nhận rõ ràng trước khi chấp nhận. Nơi token đó tồn tại, một cách đầy đủ:

• một biến trong bộ nhớ của tiến trình đó, trong suốt phiên làm việc của trình soạn thảo của bạn

Đó là toàn bộ danh sách. Không nằm trên đĩa. Không nằm trong tệp cấu hình. Không nằm trong nhật ký. Không nằm trên bất kỳ máy chủ Edgegap nào — thứ duy nhất được gửi đến Edgegap là chính lệnh gọi API, giống hệt như bạn đã chạy curl. Đóng trình soạn thảo của bạn sẽ thu hồi hoàn toàn quyền truy cập của máy chủ này.

Từ xa. Token của bạn được gửi đến mcp.edgegap.dev trong mỗi yêu cầu và được chuyển tiếp từ đó đến API Edgegap. Nó đi qua cơ sở hạ tầng mà Edgegap vận hành. Worker giữ token trong suốt thời gian tồn tại của yêu cầu và không lưu trữ nó, nhưng đó là tuyên bố "chúng tôi không lưu trữ nó" chứ không phải "chúng tôi không bao giờ nhìn thấy nó". Hai điều này khác nhau, và chỉ chế độ cục bộ mới có điều thứ hai.

Tạo token tại https://app.edgegap.com/user-settings?tab=tokens.

Trong chế độ cục bộ, việc đặt EDGEGAP_API_TOKEN sẽ được ưu tiên hơn lời nhắc, dành cho CI và cho các máy khách không thể hiển thị lời nhắc. Không truyền token dưới dạng đối số dòng lệnh — các đối số có thể nhìn thấy được bởi các tiến trình khác qua ps, và máy chủ sẽ cảnh báo nếu phát hiện một đối số như vậy.

Nên dùng cái nào. Từ xa cho lần thử đầu tiên, bản demo hoặc phiên có giám sát nơi sự phức tạp trong thiết lập quan trọng hơn quyền giữ token. Cục bộ cho bất kỳ thứ gì không có người giám sát, bất kỳ thứ gì trong tổ chức có trò chơi đang hoạt động và bất kỳ thứ gì bạn không muốn mở rộng sự tin tưởng mà bạn không cần phải làm. Các rào cản được mô tả bên dưới chỉ tồn tại trong chế độ cục bộ.

Đọc phần này trước khi kết nối một tác nhân

Token API Edgegap không thể giới hạn phạm vi. Một token ủy quyền cho mọi ứng dụng, mọi phiên bản, mọi triển khai đang chạy và việc sử dụng của bạn trên toàn bộ tổ chức. Không có token chỉ dành cho triển khai và không có token theo từng ứng dụng.

Những hậu quả đáng để bạn cân nhắc kỹ:

• Một tác nhân giữ token này có thể dừng các triển khai sản xuất, không chỉ những triển khai thử nghiệm mà nó đã tạo.
• Việc tiêm lời nhắc đến tác nhân — từ tệp kho lưu trữ, một vấn đề, một trang được tải — cũng đến được token.
• Bất cứ thứ gì tác nhân ghi nhật ký, lặp lại hoặc gửi đến nhà cung cấp mô hình là nơi token có thể kết thúc. Máy chủ này không ghi nhật ký token, nhưng nó không thể kiểm soát những gì phần còn lại của tác nhân làm.
• Trên điểm cuối từ xa, cùng một token không giới hạn phạm vi cũng được xử lý bởi worker của Edgegap trong mỗi lệnh gọi.

Thiết lập được khuyến nghị, theo thứ tự giảm dần mức độ thận trọng:

Tình huống	Thiết lập
Tác nhân không có người giám sát hoặc tự động	Chế độ cục bộ. Tổ chức riêng không dành cho sản xuất, cộng với EDGEGAP_READ_ONLY=1
Tác nhân có giám sát, trò chơi đang hoạt động trong tổ chức	Chế độ cục bộ. EDGEGAP_APP_ALLOWLIST giới hạn phạm vi cho ứng dụng đang được làm việc, cộng với EDGEGAP_MAX_DURATION_MINUTES. Đọc Phạm vi của danh sách cho phép trước — các triển khai đã đang chạy không được bao phủ
Nhà phát triển độc lập, không có khối lượng công việc sản xuất	Một trong hai chế độ. Các mặc định là đủ; thu hồi token khi hoàn thành

Danh sách cho phép và cờ chỉ đọc được thực thi trong máy chủ cục bộ, nghĩa là chúng bảo vệ chống lại một tác nhân mắc lỗi, chứ không phải chống lại một tác nhân đã bị xâm nhập để gọi API trực tiếp. Chúng thu hẹp bán kính nổ; chúng không loại bỏ nó.

Phạm vi của danh sách cho phép

EDGEGAP_APP_ALLOWLIST được thực thi bởi bốn công cụ nhận tên ứng dụng: edgegap_create_app, edgegap_list_app_versions, edgegap_create_app_version và edgegap_deploy.

Nó không được thực thi bởi năm công cụ khóa trên request_id: edgegap_get_deployment, edgegap_wait_for_deployment, edgegap_list_deployments, edgegap_stop_deployment và edgegap_get_deployment_logs. Một tác nhân chạy với danh sách cho phép được đặt có thể liệt kê mọi triển khai trong tổ chức và sau đó kiểm tra, đọc nhật ký hoặc dừng bất kỳ triển khai nào trong số đó — bao gồm cả các triển khai thuộc về các ứng dụng ngoài danh sách.

Vì vậy, danh sách cho phép giới hạn phạm vi những gì một tác nhân có thể tạo và triển khai vào, chứ không phải những gì nó có thể chạm vào khi đang chạy. Điều đó hẹp hơn so với các phiên bản trước của tài liệu này ngụ ý.

Để có một đảm bảo mạnh hơn ngay hôm nay, hãy sử dụng EDGEGAP_READ_ONLY=1, công cụ không bao giờ đăng ký năm công cụ đột biến, hoặc trỏ tác nhân đến một tổ chức riêng không dành cho sản xuất. Cả hai đều không bị ảnh hưởng bởi khoảng trống này.

Được báo cáo bởi Syed Anas Mohiuddin, tháng 9 năm 2026.

Biến môi trường

Các biến này cấu hình máy chủ cục bộ. Trên điểm cuối từ xa, chúng được đặt bởi Edgegap và không thể thay đổi theo từng nhà phát triển — nếu bạn cần bất kỳ biến nào trong số này, hãy chạy cục bộ.

Biến	Mặc định	Mục đích
EDGEGAP_API_TOKEN	(được nhắc)	Token API. Tùy chọn — bỏ qua nó và nhà phát triển sẽ được hỏi ở lần sử dụng đầu tiên. Tiền tố token được thêm cho bạn.
EDGEGAP_READ_ONLY	0	Đặt thành 1 và năm công cụ đột biến không bao giờ được đăng ký. Tác nhân không thể nhìn thấy chúng, vì vậy nó không thể bị thuyết phục gọi chúng.
EDGEGAP_APP_ALLOWLIST	(trống)	Danh sách tên ứng dụng phân tách bằng dấu phẩy. Khi được đặt, bốn công cụ khóa theo ứng dụng từ chối chạm vào bất kỳ thứ gì khác. Không giới hạn phạm vi năm công cụ khóa theo request_id — xem Phạm vi của danh sách cho phép.
EDGEGAP_MAX_DURATION_MINUTES	60	Trần cho max_duration mà tác nhân có thể đặt trên một phiên bản. Giới hạn chi phí chạy không kiểm soát từ một tác nhân không có người giám sát.
EDGEGAP_TIMEOUT_MS	30000	Thời gian chờ HTTP cho mỗi yêu cầu.

Công cụ

Mười công cụ, được liệt kê theo thứ tự chúng nằm dọc theo con đường vàng. Mười công cụ giống nhau trong cả hai chế độ.

Công cụ	Đột biến	Mục đích
edgegap_list_apps		Định hướng trước khi làm bất cứ điều gì. Ngăn chặn các ứng dụng trùng lặp.
edgegap_create_app	●	Tạo container cho các phiên bản.
edgegap_list_app_versions		Tìm một phiên bản có thể triển khai, hoặc sao chép cài đặt từ một phiên bản đang hoạt động.
edgegap_create_app_version	●	Đăng ký một hình ảnh container với CPU, bộ nhớ và cổng.
edgegap_deploy	●	Khởi động một phiên bản gần những người chơi được chỉ định.
edgegap_get_deployment		Đọc trạng thái một lần.
edgegap_wait_for_deployment		Thăm dò đến trạng thái sẵn sàng với backoff, sau đó trả về địa chỉ kết nối.
edgegap_list_deployments		Tìm các máy chủ mồ côi từ các phiên trước đó.
edgegap_stop_deployment	●	SIGTERM nhẹ nhàng, một triển khai tại một thời điểm.
edgegap_get_deployment_logs		Đầu ra container và mã thoát do sự cố sau một lỗi.

Quyết định thiết kế

Được tuyển chọn, không được tạo tự động. API Edgegap có khoảng sáu mươi thao tác. Việc tự động tạo một công cụ cho mỗi thao tác đặt tất cả sáu mươi mô tả vào ngữ cảnh của tác nhân trong mỗi lượt và làm giảm đáng kể khả năng chọn công cụ. Mười công cụ này bao phủ con đường chuyển đổi một nhà phát triển mới.

wait_for_deployment là một công cụ, không phải một vòng lặp. Để tự nó, một tác nhân sẽ gọi một điểm cuối trạng thái trong một vòng lặp chặt, đốt cháy lượt và bỏ cuộc sớm. Việc gộp việc thăm dò và backoff vào một lệnh gọi loại bỏ lỗi phổ biến nhất trong các triển khai do tác nhân điều khiển.

Các lỗi được viết để tự sửa. Mã 424 trả về nói rằng hình ảnh không thể được kéo và những trường nào cần kiểm tra. Mã 422 nói hãy thử tọa độ khác hoặc giảm yêu cầu tài nguyên. Tác nhân có thể hành động dựa trên những điều này mà không cần một vòng lặp đến con người.

Xác thực cục bộ trước khi lên mạng. Tỷ lệ bộ nhớ trên CPU và vị trí người chơi bị thiếu được bắt ở đây thay vì xuất hiện dưới dạng mã 400 không rõ ràng.

Các thao tác hàng loạt cố tình vắng mặt. stop nhận một request_id. Không có công cụ dừng hàng loạt, vì một tác nhân với một biểu thức lọc và một lỗi có thể dừng một đội tàu sản xuất.

Cả một điểm cuối được lưu trữ và một gói cục bộ. Điểm cuối được lưu trữ loại bỏ mọi bước giữa việc tìm thấy máy chủ này và gọi một công cụ, nơi hầu hết các nhà phát triển bỏ cuộc. Gói cục bộ là cách duy nhất để chạy máy chủ mà không mở rộng quyền giữ một token không giới hạn phạm vi cho bên thứ ba, bao gồm cả chúng tôi. Không cái nào thống trị cái kia, vì vậy cả hai đều được phát hành. Xem worker/DECISION.md để biết phiên bản dài hơn.

Phạm vi

Không được hiển thị, có chủ đích: đối sánh trận đấu, relay, đội tàu riêng, đội tàu thông minh, lưu trữ điểm cuối, mục ACL/danh sách trắng, thẻ triển khai, số liệu, quản lý sổ đăng ký container, cấu hình DNS.

Đây là những khả năng thực sự, nhưng chúng thuộc về các studio đã hoạt động trên nền tảng, không phải cho một nhà phát triển triển khai máy chủ đầu tiên của họ. Thêm chúng sẽ đánh đổi con đường chuyển đổi lấy diện tích bề mặt.

Hạn chế đã biết: yêu cầu token ngay từ đầu

Điều này áp dụng cho chế độ cục bộ, nơi token được thu thập thông qua elicitation thay vì đọc từ cấu hình.

Đặc tả MCP nói rằng các máy chủ không nên sử dụng elicitation để thu thập dữ liệu nhạy cảm, và một token API là nhạy cảm. Máy chủ này vẫn làm điều đó, vì yêu cầu một token trong tệp cấu hình trước khi mọi thứ hoạt động là điểm rơi lớn nhất trong kênh onboarding, và toàn bộ mục đích của máy chủ là loại bỏ sự phức tạp trong thiết lập.

Đó là một sự đánh đổi có chủ đích chứ không phải một mẫu để sao chép. Điều làm cho nó có thể bảo vệ được là tập hợp các biện pháp giảm thiểu trong src/auth.ts — lưu trữ chỉ trong bộ nhớ, tiết lộ bằng ngôn ngữ đơn giản, yêu cầu xác nhận, che giấu khỏi mọi đầu ra và biến môi trường luôn thắng khi có mặt. Loại bỏ bất kỳ biện pháp nào trong số chúng sẽ phá vỡ sự đánh đổi.

Giải pháp thực sự nằm ở phía Edgegap và sẽ cải thiện cả hai chế độ: thông tin xác thực có giới hạn phạm vi, có thể thu hồi, chỉ dành cho triển khai, được cấp qua OAuth thay vì dán dưới dạng bí mật. Cho đến khi những thứ đó tồn tại, lời nhắc tương tác là một giải pháp tạm thời và được gắn nhãn như vậy trong mã.

Phát triển

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

Không có cái nào trong số này thực hiện các lệnh gọi mạng. elicit.mjs khẳng định rằng lời nhắc nêu rõ phạm vi toàn tổ chức, rằng việc xác nhận là bắt buộc, rằng token không bao giờ xuất hiện trong đầu ra công cụ và rằng việc từ chối tạo ra một thông báo dừng và báo cáo thay vì một vòng lặp thử lại.