Edgegap

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

edgegap-mcp

Um servidor MCP para Edgegap que permite que um agente de codificação leve um desenvolvedor de "eu tenho um contêiner de servidor de jogo" para "os jogadores estão conectados a ele" sem que o desenvolvedor leia a referência da API.

Dez ferramentas, escolhidas a dedo. Não geradas a partir da especificação OpenAPI — veja Escopo para entender o porquê.

Instalação

Duas maneiras de executá-lo. Escolha com base em o quanto você se importa com onde seu token vai — veja Para onde seu token vai.

Endpoint remoto

Hospedado pela Edgegap como um Cloudflare Worker. Nada para instalar.

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

Também funciona como um conector personalizado no claude.ai: adicione https://mcp.edgegap.dev/mcp e forneça o mesmo token.

Local

Executa na sua própria máquina, iniciado pelo seu editor. Uma linha na configuração do seu cliente MCP, nada para clonar, nada para compilar.

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

Funciona no Claude Code, Cursor, Codex e VS Code. Fixe uma versão em produção (@edgegap/mcp@0.1.5) em vez de flutuar na versão mais recente.

Registrado no registro oficial de MCP como dev.edgegap/mcp.

Versão do Node: o servidor local precisa do Node 18+. Implantar sua própria cópia do Cloudflare Worker precisa do Node 22+, porque wrangler exige isso.

Para onde seu token vai

Isso difere por modo, e a diferença é o motivo pelo qual ambos os modos existem.

Local. O servidor roda como um processo no seu próprio computador. A primeira chamada de ferramenta pede um token, mostra o que ele autoriza e exige uma confirmação explícita antes de aceitá-lo. Onde esse token então reside, de forma exaustiva:

• uma variável na memória desse processo, pela vida útil da sua sessão de editor

Essa é a lista completa. Não em disco. Não em um arquivo de configuração. Não em logs. Não em nenhum servidor Edgegap — a única coisa enviada para a Edgegap é a própria chamada de API, exatamente como se você tivesse executado curl. Fechar seu editor revoga completamente o acesso deste servidor.

Remoto. Seu token é enviado para mcp.edgegap.dev em cada solicitação e encaminhado de lá para a API da Edgegap. Ele transita pela infraestrutura que a Edgegap opera. O worker o mantém pela vida útil da solicitação e não o persiste, mas isso é uma afirmação de "não armazenamos" em vez de "nunca vemos". As duas coisas são diferentes, e apenas o modo local faz a segunda.

Gere um token em https://app.edgegap.com/user-settings?tab=tokens.

No modo local, definir EDGEGAP_API_TOKEN tem precedência sobre o prompt, para CI e para clientes que não podem exibir prompts. Não passe um token como argumento de linha de comando — argumentos são visíveis para outros processos via ps, e o servidor avisa se detectar um.

Qual usar. Remoto para uma primeira tentativa, uma demonstração ou uma sessão supervisionada onde o atrito de configuração importa mais do que a custódia. Local para qualquer coisa não supervisionada, qualquer coisa em uma organização com um jogo ativo, e qualquer coisa onde você prefere não estender confiança que não precisa. As proteções descritas abaixo existem apenas no modo local.

Leia isto antes de conectar um agente

O token da API Edgegap não pode ser escopado. Um token autoriza todos os aplicativos, todas as versões, todas as implantações em execução e seu uso em toda a organização. Não há token somente de implantação e nenhum token por aplicativo.

Consequências que valem a pena considerar com cuidado:

• Um agente que detém este token pode parar implantações de produção, não apenas as de teste que ele criou.
• Injeção de prompt que chega ao agente — de um arquivo de repositório, uma issue, uma página buscada — também chega ao token.
• Qualquer coisa que o agente registre, ecoe ou envie a um provedor de modelo é um lugar onde o token pode acabar. Este servidor não o registra, mas não pode controlar o que o resto do agente faz.
• No endpoint remoto, o mesmo token sem escopo é adicionalmente manipulado pelo worker da Edgegap em cada chamada.

Configuração recomendada, em ordem decrescente de cautela:

Situação	Configuração
Agente não supervisionado ou autônomo	Modo local. Organização separada de não produção, além de EDGEGAP_READ_ONLY=1
Agente supervisionado, jogo ativo na organização	Modo local. EDGEGAP_APP_ALLOWLIST escopado ao aplicativo em que se está trabalhando, além de EDGEGAP_MAX_DURATION_MINUTES. Leia Escopo da lista de permissões primeiro — implantações já em execução não são cobertas
Desenvolvedor solo, sem carga de produção	Qualquer modo. Os padrões são suficientes; revogue o token quando terminar

A lista de permissões e o sinalizador somente leitura são aplicados no servidor local, o que significa que protegem contra um agente que comete um erro, não contra um que foi comprometido a chamar a API diretamente. Eles reduzem o raio de explosão; não o eliminam.

Escopo da lista de permissões

EDGEGAP_APP_ALLOWLIST é aplicado pelas quatro ferramentas que recebem um nome de aplicativo: edgegap_create_app, edgegap_list_app_versions, edgegap_create_app_version e edgegap_deploy.

Ele não é aplicado pelas cinco ferramentas baseadas em request_id: edgegap_get_deployment, edgegap_wait_for_deployment, edgegap_list_deployments, edgegap_stop_deployment e edgegap_get_deployment_logs. Um agente rodando com uma lista de permissões definida pode listar todas as implantações na organização e então inspecionar, ler os logs ou parar qualquer uma delas — incluindo implantações pertencentes a aplicativos fora da lista.

Portanto, a lista de permissões limita o que um agente pode criar e implantar, não o que ele pode tocar uma vez em execução. Isso é mais restrito do que versões anteriores deste documento implicavam.

Para uma garantia mais forte hoje, use EDGEGAP_READ_ONLY=1, que nunca registra as cinco ferramentas de mutação, ou aponte o agente para uma organização separada de não produção. Ambos não são afetados por essa lacuna.

Relatado por Syed Anas Mohiuddin, setembro de 2026.

Variáveis de ambiente

Estas configuram o servidor local. No endpoint remoto, elas são definidas pela Edgegap e não podem ser alteradas por desenvolvedor — se você precisar de alguma delas, execute localmente.

Variável	Padrão	Finalidade
EDGEGAP_API_TOKEN	(solicitado)	Token da API. Opcional — omita-o e o desenvolvedor será perguntado no primeiro uso. O prefixo token é adicionado para você.
EDGEGAP_READ_ONLY	0	Defina como 1 e as cinco ferramentas de mutação nunca serão registradas. O agente não pode vê-las, então não pode ser convencido a chamá-las.
EDGEGAP_APP_ALLOWLIST	(vazio)	Nomes de aplicativos separados por vírgula. Quando definido, as quatro ferramentas baseadas em aplicativos se recusam a tocar em qualquer outra coisa. Não limita as cinco ferramentas baseadas em request_id — veja Escopo da lista de permissões.
EDGEGAP_MAX_DURATION_MINUTES	60	Teto sobre max_duration que o agente pode definir em uma versão. Limita custos descontrolados de um agente não supervisionado.
EDGEGAP_TIMEOUT_MS	30000	Tempo limite de HTTP por solicitação.

Ferramentas

Dez ferramentas, listadas na ordem em que aparecem ao longo do caminho dourado. As mesmas dez em ambos os modos.

Ferramenta	Mutação	Para que serve
edgegap_list_apps		Orientar antes de fazer qualquer coisa. Evita aplicativos duplicados.
edgegap_create_app	●	Criar o contêiner para versões.
edgegap_list_app_versions		Encontrar uma versão implantável, ou copiar configurações de uma que funciona.
edgegap_create_app_version	●	Registrar uma imagem de contêiner com CPU, memória e portas.
edgegap_deploy	●	Iniciar uma instância perto de jogadores especificados.
edgegap_get_deployment		Leitura de status única.
edgegap_wait_for_deployment		Consultar até ficar pronto com backoff, então retornar o endereço de conexão.
edgegap_list_deployments		Encontrar servidores órfãos de sessões anteriores.
edgegap_stop_deployment	●	SIGTERM gracioso, uma implantação por vez.
edgegap_get_deployment_logs		Saída do contêiner e código de saída de falha após uma falha.

Decisões de design

Curado, não gerado. A API da Edgegap tem aproximadamente sessenta operações. Gerar automaticamente uma ferramenta por operação coloca todas as sessenta descrições no contexto do agente a cada turno e degrada mensuravelmente a seleção de ferramentas. Estas dez cobrem o caminho que converte um novo desenvolvedor.

wait_for_deployment é uma ferramenta, não um loop. Deixado por conta própria, um agente chamará um endpoint de status em um loop apertado, queimará turnos e desistirá cedo. Dobrar a consulta e o backoff em uma única chamada remove a falha mais comum em implantações dirigidas por agentes.

Erros são escritos para autocorreção. Um 424 retorna dizendo que a imagem não pôde ser puxada e quais campos verificar. Um 422 diz para tentar coordenadas diferentes ou reduzir a solicitação de recursos. O agente pode agir sobre isso sem uma ida e volta ao humano.

Validação local antes do envio. A proporção memória-CPU e a localização ausente do jogador são capturadas aqui em vez de aparecerem como um 400 opaco.

Operações em massa estão deliberadamente ausentes. stop recebe um request_id. Não há ferramenta de parada em massa, porque um agente com uma expressão de filtro e um bug pode parar uma frota de produção.

Tanto um endpoint hospedado quanto um pacote local. O endpoint hospedado remove cada etapa entre encontrar este servidor e chamar uma ferramenta, que é onde a maioria dos desenvolvedores desiste. O pacote local é a única maneira de executar o servidor sem estender a custódia de um token sem escopo a terceiros, incluindo nós. Nenhum domina o outro, então ambos são enviados. Veja worker/DECISION.md para a versão mais longa.

Escopo

Não exposto, de propósito: matchmaking, relays, frotas privadas, frotas inteligentes, armazenamento de endpoints, entradas ACL/whitelist, tags de implantação, métricas, gerenciamento de registro de contêineres, configuração de DNS.

Estas são capacidades reais, mas pertencem a estúdios que já operam na plataforma, não a um desenvolvedor implantando seu primeiro servidor. Adicioná-las trocaria o caminho de conversão por área de superfície.

Limitação conhecida: pedir o token

Isso se aplica ao modo local, onde o token é coletado por elicitação em vez de lido da configuração.

A especificação MCP diz que servidores não devem usar elicitação para coletar dados sensíveis, e um token de API é sensível. Este servidor faz isso mesmo assim, porque exigir um token em um arquivo de configuração antes que qualquer coisa funcione é a maior queda no funil de integração, e o objetivo do servidor é remover o atrito de configuração.

Isso é uma troca deliberada, não um padrão a copiar. O que a torna defensável é o conjunto de mitigações em src/auth.ts — armazenamento somente em memória, divulgação em linguagem simples, confirmação obrigatória, redação de toda a saída e a variável de ambiente sempre vencendo quando presente. Remover qualquer uma delas quebra a troca.

A correção real está no lado da Edgegap e melhoraria ambos os modos: credenciais escopadas, revogáveis e somente de implantação, emitidas via OAuth em vez de coladas como um segredo. Até que existam, o prompt interativo é um workaround e é rotulado como tal no código.

Desenvolvimento

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

Nenhum destes faz chamadas de rede. elicit.mjs afirma que o prompt declara o escopo de toda a organização, que a confirmação é obrigatória, que o token nunca aparece na saída da ferramenta e que recusar produz uma mensagem de parar e relatar em vez de um loop de repetição.