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에는 약 60개의 작업이 있습니다. 작업당 하나의 도구를 자동 생성하면 모든 60개의 설명이 매 턴 에이전트의 컨텍스트에 들어가고 도구 선택이 눈에 띄게 저하됩니다. 이 열 개는 새 개발자를 전환하는 경로를 다룹니다.

wait_for_deployment은 도구이지 루프가 아닙니다. 에이전트가 스스로 상태 엔드포인트를 빠르게 반복 호출하고, 턴을 소모하고, 일찍 포기할 수 있습니다. 폴링과 백오프를 하나의 호출로 접으면 에이전트 주도 배포에서 가장 흔한 실패를 제거합니다.

오류는 자기 수정을 위해 작성되었습니다. 424는 이미지를 가져올 수 없고 어떤 필드를 확인해야 하는지 알려줍니다. 422는 다른 좌표를 시도하거나 리소스 요청을 낮추라고 말합니다. 에이전트는 인간에게 왕복하지 않고 이에 따라 행동할 수 있습니다.

네트워크 전 로컬 검증. 메모리 대 CPU 비율과 누락된 플레이어 위치는 불투명한 400으로 표시되지 않고 여기서 잡힙니다.

대량 작업은 의도적으로 없습니다. stop은 하나의 request_id을 사용합니다. 대량 중지 도구는 없습니다. 필터 표현식과 버그가 있는 에이전트가 프로덕션 플릿을 중지할 수 있기 때문입니다.

호스팅 엔드포인트와 로컬 패키지 모두. 호스팅 엔드포인트는 이 서버를 찾는 것과 도구를 호출하는 것 사이의 모든 단계를 제거하며, 대부분의 개발자가 여기서 포기합니다. 로컬 패키지는 범위 없는 토큰의 관리권을 제3자(우리 포함)에게 확장하지 않고 서버를 실행하는 유일한 방법입니다. 어느 쪽도 다른 쪽을 지배하지 않으므로 둘 다 제공합니다. 더 긴 버전은 worker/DECISION.md을 참조하세요.

범위

의도적으로 노출하지 않음: 매치메이킹, 릴레이, 프라이빗 플릿, 스마트 플릿, 엔드포인트 저장, ACL/화이트리스트 항목, 배포 태그, 메트릭, 컨테이너 레지스트리 관리, DNS 구성.

이들은 실제 기능이지만, 플랫폼에서 이미 운영 중인 스튜디오를 위한 것이지 첫 서버를 배포하는 개발자를 위한 것이 아닙니다. 추가하면 전환 경로를 표면적과 맞바꾸게 됩니다.

알려진 제한: 토큰을 아예 요청하는 것

로컬 모드에 적용되며, 토큰이 구성에서 읽히지 않고 elicitation을 통해 수집됩니다.

MCP 사양은 서버가 민감한 데이터를 수집하기 위해 elicitation을 사용하지 말아야 한다고 말하며, 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은 프롬프트가 조직 전체 범위를 명시하고, 확인이 필수이며, 토큰이 도구 출력에 절대 나타나지 않고, 거부 시 재시도 루프가 아닌 중지 및 보고 메시지를 생성하는지 확인합니다.