An MCP server that lets a coding agent take a developer from "I have a game server container" to "players are connected to it" without the developer reading the API reference.

Ten tools, hand-picked. Not generated from the OpenAPI spec — see Scope for why.

Install

One line in your MCP client config. Nothing to clone, nothing to build.

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

Works in Claude Code, Cursor, Codex, and VS Code. Pin a version in production (@edgegap/mcp@0.1.0) rather than floating on latest.

Node version: the server itself needs Node 18+. Deploying the optional Cloudflare Worker needs Node 22+, because wrangler requires it.

Your token never leaves your machine

There is no Edgegap-hosted component. This server runs as a process on your own computer, spawned by your editor. The first tool call asks you for a token, shows what it authorises, and requires an explicit acknowledgement before accepting it. Where that token then lives, exhaustively:

one variable in that process's memory, for the life of your editor session

That is the whole list. Not on disk. Not in a config file. Not in logs. Not on any Edgegap server — the only thing sent to Edgegap is the API call itself, exactly as if you had run curl. Closing your editor revokes this server's access completely.

Generate a token at https://app.edgegap.com/user-settings?tab=tokens.

Setting EDGEGAP_API_TOKEN still works and takes precedence, for CI and for clients that cannot show prompts. Do not pass a token as a command-line argument — arguments are visible to other processes via ps, and the server warns if it detects one.

Why this is not hosted. A hosted server would have to either store your token or receive it on every request. "We don't store it" and "we never see it" are different claims, and only a local process makes the second one. See worker/DECISION.md for the full reasoning and the conditions under which a hosted version becomes worth building.

Read this before connecting an agent

The Edgegap API token cannot be scoped. One token authorises every application, every version, every running deployment, and your usage across the whole organization. There is no deploy-only token and no per-application token.

Consequences worth being deliberate about:

An agent holding this token can stop production deployments, not just the test ones it created.
Prompt injection reaching the agent — from a repo file, an issue, a fetched page — reaches the token too.
Anything the agent logs, echoes, or sends to a model provider is a place the token could end up. This server does not log it, but it cannot control what the rest of the agent does.

Recommended setup, in decreasing order of caution:

Situation	Setup
Unattended or autonomous agent	Separate non-production organization, plus `EDGEGAP_READ_ONLY=1`
Supervised agent, live game in the org	`EDGEGAP_APP_ALLOWLIST` scoped to the app being worked on, plus `EDGEGAP_MAX_DURATION_MINUTES`
Solo developer, no production workload	Defaults are fine; revoke the token when finished

The allowlist and read-only flag are enforced in this server, which means they protect against an agent that makes a mistake, not against one that has been compromised into calling the API directly. They narrow the blast radius; they do not remove it.

Environment variables

Variable	Default	Purpose
`EDGEGAP_API_TOKEN`	(prompted)	API token. Optional — omit it and the developer is asked at first use. The `token` prefix is added for you.
`EDGEGAP_READ_ONLY`	`0`	Set to `1` and the five mutating tools are never registered. The agent cannot see them, so it cannot be talked into calling them.
`EDGEGAP_APP_ALLOWLIST`	(empty)	Comma-separated application names. When set, every tool refuses to touch anything else.
`EDGEGAP_MAX_DURATION_MINUTES`	`60`	Ceiling on `max_duration` the agent may set on a version. Caps runaway cost from an unattended agent.
`EDGEGAP_TIMEOUT_MS`	`30000`	Per-request HTTP timeout.

The ten tools

Ordered along the golden path.

#	Tool	Mutating	What it's for
1	`edgegap_list_apps`		Orient before doing anything. Prevents duplicate applications.
2	`edgegap_create_app`	●	Create the container for versions.
3	`edgegap_list_app_versions`		Find a deployable version, or copy settings from a working one.
4	`edgegap_create_app_version`	●	Register a container image with CPU, memory, and ports.
5	`edgegap_deploy`	●	Start one instance near specified players.
6	`edgegap_get_deployment`		Single status read.
7	`edgegap_wait_for_deployment`		Poll to ready with backoff, then return the connection address.
8	`edgegap_list_deployments`		Find orphaned servers from earlier sessions.
9	`edgegap_stop_deployment`	●	Graceful SIGTERM, one deployment at a time.
10	`edgegap_get_deployment_logs`		Container output and crash exit code after a failure.

Design decisions

Curated, not generated. The Edgegap API has roughly sixty operations. Auto-generating one tool per operation puts all sixty descriptions into the agent's context on every turn and measurably degrades tool selection. These ten cover the path that converts a new developer.

wait_for_deployment is a tool, not a loop. Left to itself an agent will call a status endpoint in a tight loop, burn turns, and give up early. Folding the polling and backoff into one call removes the most common failure in agent-driven deploys.

Errors are written for self-correction. A 424 comes back saying the image could not be pulled and which fields to check. A 422 says to try different coordinates or lower the resource request. The agent can act on these without a round trip to the human.

Local validation before the wire. The memory-to-CPU ratio and the missing player location are caught here rather than surfacing as an opaque 400.

Bulk operations are deliberately absent. stop takes one request_id. There is no bulk-stop tool, because an agent with a filter expression and a bug can stop a production fleet.

Scope

Not exposed, on purpose: matchmaking, relays, private fleets, smart fleets, endpoint storage, ACL/whitelist entries, deployment tags, metrics, container registry management, DNS configuration.

These are real capabilities, but they belong to studios already operating on the platform, not to a developer deploying their first server. Adding them would trade the conversion path for surface area.

Known limitation: asking for the token at all

The MCP specification says servers should not use elicitation to collect sensitive data, and an API token is sensitive. This server does it anyway, because requiring a token in a config file before anything works is the largest drop in the onboarding funnel, and the whole point of the server is to remove setup friction.

That is a deliberate trade rather than a pattern to copy. What makes it defensible is the set of mitigations in src/auth.ts — memory-only storage, plain-language disclosure, required acknowledgement, redaction from all output, and the environment variable always winning when present. Removing any of them breaks the trade.

The real fix is on Edgegap's side: scoped, revocable, deploy-only credentials, issued through OAuth rather than pasted as a secret. Until those exist, the interactive prompt is a workaround and is labelled as one in the code.

Development

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

None of these make network calls. elicit.mjs asserts that the prompt states the org-wide scope, that the acknowledgement is required, that the token never appears in tool output, and that declining produces a stop-and-report message rather than a retry loop.