How do I install Edgegap?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Edgegap need an API key?

The publisher lists these environment variables: EDGEGAP_API_TOKEN.

When was Edgegap last checked?

Last checked 2026-11-08. Deploy and operate multiplayer game servers on Edgegap's global edge network.

Edgegap MCP server

Edgegap MCP Server

Connect AI coding agents to Edgegap through our MCP server. Your agent can take a headless server build all the way to players connecting: write or check the Dockerfile, push the image to your private Edgegap registry, deploy an authoritative dedicated server close to players, and read logs when something breaks.

👉 Supported Features

[!TIP] Using Unity, Unreal Engine, or Godot? Our Unity, Unreal Engine, and Godot guides and plugins remain the fastest path for those engines. The MCP server works alongside them, and on its own for any engine.

Use our MCP server when:

Containerizing your game server - your agent writes a Dockerfile for your build (or checks the one you have) against Edgegap's requirements, then pushes the image to your private Edgegap container registry.
Deploying a dedicated server - create an application and version, deploy close to your players, and get the connection address.
Setting up matchmaking - generate a matchmaker configuration that points at your deployed version, ready to upload in the dashboard.
Running a host-client game - create a relay session if your game is built with one player as host. See Dedicated Servers or Relays? first.
Building a CI/CD pipeline - test your deployments and teardown from a build system.
Troubleshooting a game server issue - inspect app versions and deployment status, read container logs, or reproduce a failed deployment.

[!WARNING] Out of scope / not supported by MCP: creating or running a matchmaker (the MCP generates the configuration, you upload it in the dashboard); server browser; lobbies; managed clusters; private fleets; or billing.

[!NOTE] If you need help, please reach out to us over Discord. For live games support see our ticketing system.

⚖️ Dedicated Servers or Relays?

Edgegap can host your multiplayer game in two ways. We recommend dedicated servers, and so does our MCP server: your agent will default to a dedicated server and only use a relay when you've chosen a host-client setup.

	Dedicated server (recommended)	Relay
What Edgegap runs	Your headless server build, close to players	A traffic forwarder only, no game code
Who runs the game	The server	One player's game (the host)
Cheating	Much harder, the server has authority	The host can change anything
Fairness	Every player connects directly to the server	The host has no latency, everyone else goes through two hops
When the host leaves	The match continues	The match ends, unless your game supports host migration
Performance limited by	The server's allocated CPU and memory	The host's PC and home internet upload
You need	A server build in a container image	Netcode built as a listen server (host-client)

[!NOTE] No server image yet? That's not a reason to choose relays. Your agent can write the Dockerfile for your build with edgegap_generate_dockerfile. Learn more about relays in Distributed Relay.

🚀 Installation

MCP server installation is very simple:

Install the MCP server for Popular Agents or with Custom Integration.
Generate and attach an API token for your agent to use with our MCP server.

Generate (and view) your secret tokens for Edgegap API in Dashboard - User Settings / Tokens.

Add your secret token with each API request as an HTTP header (include the word token):

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

[!CAUTION] Do not integrate Edgegap API endpoints in game client, as your API token provides unlimited access to your account. See Integration for secure client-facing API endpoints and functions.

[!TIP] In case your secret tokens are compromised or leaked, delete and re-create them from dashboard.

The token is organization-wide and cannot be scoped to one application. Read DESIGN.md before giving it to an unattended agent.

Popular Agents

Install Edgegap MCP server in your preferred agentic IDE with the Cursor or VS Code buttons at the top of this page, then add your token to the Authorization header.

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 mcp add edgegap --url https://mcp.edgegap.dev/mcp

Claude Desktop and claude.ai

Custom connectors in claude.ai and Claude Desktop cannot send an Authorization header, so the hosted endpoint never receives your token from them: the connector shows as connected, but every tool call fails. Use the Local Server instead.

In Claude Desktop, open Settings → Developer → Edit Config and add the local server to claude_desktop_config.json:

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

Leave the token out and you're asked for it on first use. claude.ai in the browser can't run a local server, so it can't use Edgegap MCP until the hosted endpoint supports OAuth.

mcp.json

Most agentic IDEs also support integration by pasting JSON configuration:

{
    "mcpServers": {
        "Edgegap": {
            "type": "http",
            "url": "https://mcp.edgegap.dev/mcp",
            "headers": {
                "Authorization": "token xxxxxxxx-e458-4592-b607-c2c28afd8b62"
            }
        }
    }
}

Custom Integration

Install remote Edgegap MCP server in your agent's virtualized environment (never in your project!):

Node, using the mcp-remote npx package

{
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://mcp.edgegap.dev/mcp", "--transport", "http-only"]
}

Python, using the mcp-proxy uvx package

{
  "command": "uvx",
  "args": ["mcp-proxy", "--transport", "streamablehttp", "https://mcp.edgegap.dev/mcp"]
}

Local Server

To keep your API token on your own machine, run the server locally instead. Leave the token out and your agent asks you for it on first use, holding it in memory only for that session:

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

Needs Node 18+. Pin a version in production (@edgegap/[email protected]) rather than floating on latest. Registered in the official MCP registry as dev.edgegap/mcp.

The local server can also limit what an agent can do. These variables have no effect on the hosted endpoint at mcp.edgegap.dev:

Variable	Default	Purpose
`EDGEGAP_API_TOKEN`	(prompted)	API token. Optional: omit it and you're asked at first use. The `token` prefix is added for you. Never pass it as a command-line argument.
`EDGEGAP_READ_ONLY`	`0`	Set to `1` and the eight mutating tools are never registered, so the agent cannot be talked into calling them.
`EDGEGAP_APP_ALLOWLIST`	(empty)	Comma-separated application names. Limits what the agent can create and deploy into. Reading (listing apps and versions) is not limited, and neither is touching deployments once running. See DESIGN.md.
`EDGEGAP_MAX_DURATION_MINUTES`	`60`	Ceiling on `max_duration` the agent may set on a version.
`EDGEGAP_MAX_AGENT_DEPLOYMENTS`	`5`	`edgegap_deploy` refuses while this many deployments tagged `edgegap-mcp` are running. `0` turns the cap off.
`EDGEGAP_TIMEOUT_MS`	`30000`	Per-request HTTP timeout.

📚 Skills

The server includes the Edgegap agent skills: tested, step-by-step workflows for getting a multiplayer game online, with templates (Dockerfiles, matchmaker configs, Unity C# and Unreal C++ drop-ins) and known pitfalls. Any agent connected to Edgegap MCP gets them, with no separate install and no token needed, and is told to load the matching skill before working on a game project.

Skill	For
`edgegap`	Start here for any engine other than Unity or Unreal Engine, or platform questions. Routes to the rest.
`edgegap-unity`	Unity end to end: server build, matchmaker, client, end-to-end test.
`edgegap-ngo`	Unity with Netcode for GameObjects end to end: server start and self-stop, Find Match panel, Boss Room adapter, matchmaker.
`edgegap-fishnet`	Unity with FishNet end to end: headless server, Bayou/WebGL, matchmaker, end-to-end test.
`edgegap-purrnet`	Unity with PurrNet end to end: dedicated server, connect panel, matchmaker, end-to-end test.
`edgegap-fusion`	Unity with Photon Fusion 2 end to end: IL2CPP Linux server, server bound to 0.0.0.0, Edgegap deployment, BR200 kit.
`edgegap-manus`	Browser games built with Manus: backend matchmaking, Steam sign-in, signed join tokens, Node WebSocket server.
`edgegap-unreal`	Unreal Engine end to end: source engine, Linux server, matchmaker, end-to-end test.
`edgegap-eos-voice`	Voice chat for an Unreal game on Edgegap with EOS Voice: server-side room tokens, match and team rooms.
`edgegap-server-design`	Authoritative server design and the deployment lifecycle.
`edgegap-containerize`	The container contract, Dockerfiles, registries, app versions.
`edgegap-local-testing`	Parity tests on your machine, then one smoke-test deployment.
`edgegap-troubleshoot`	Pull errors, crash loops, out-of-memory, clients that can't connect.
`edgegap-deployments-api`	Backend code that deploys servers: webhooks, cleanup, Nakama, PlayFab, UGS, EOS.
`edgegap-launch`	Launch checklist, rollouts, caching, cost control.

They're served three ways, so every MCP client can reach them:

Tools: edgegap_list_skills and edgegap_get_skill, which loads a skill's SKILL.md, or one of its reference documents or templates with file.
Prompts: one per skill, named after it. In Claude Code they show up as slash commands, e.g. /mcp__edgegap__edgegap-unity.
Resources: one per file, at edgegap-skill://<skill>/<path>, e.g. edgegap-skill://edgegap-unity/references/deploy.md.

Each release bundles the skills at the commit pinned in scripts/skills-pin.txt; edgegap_context reports which pack is loaded. If you also installed the skills locally (the Claude Code plugin or npx skills add), they're the same pack.

🧰 Tools

Your agent picks the right tool from your request. You don't need to name them, but knowing what's available helps you ask. Tools marked ● change something in your account, accept dry_run, and are hidden when EDGEGAP_READ_ONLY=1.

Tool	What it does
`edgegap_context`	Shows which API this server talks to, its version, local or hosted, and the guardrails in force. No API call; never shows the token.

Before Your First Deployment

Tool	What it does
`edgegap_generate_dockerfile`	Writes a Dockerfile for your server build: your build folder, server binary or start script, ports, and launch arguments, with the right headless flags (Unity `-batchmode -nographics`, Godot `--headless`), a non-root user for Unreal, and matching ports. Lists anything it had to assume so your agent can confirm it. Works for Unity, Unreal Engine, Godot, and any other engine.
`edgegap_validate_server_config`	Checks an existing Dockerfile, ports, resources, and image tag before you build. Catches ARM or Windows images (Edgegap runs `linux/amd64`), Unreal servers running as root, missing Unity `-batchmode -nographics`, servers bound to `localhost`, ports that don't match your netcode transport, and the `latest` tag.
`edgegap_get_registry_credentials` ●	Returns push credentials for your private Edgegap container registry, with the exact `docker login`, build, and push commands. Edgegap only gives these to the Unity/Unreal plugins' quick-start token; with a regular API token, it tells your agent to ask you for the login from the dashboard's Container Registry page instead.
`edgegap_list_registry_tags`	Confirms your image push landed before you register it. Takes the image name only, e.g. `my-game-server`: the project comes from your token.

Dedicated Servers (Recommended)

Tool	What it does
`edgegap_list_apps`	Lists your applications.
`edgegap_create_app` ●	Creates an application.
`edgegap_list_app_versions`	Lists versions with their image, resources, ports (with TLS Upgrade), and whether a registry login is set.
`edgegap_create_app_version` ●	Registers a container image as a deployable version. Supports TLS Upgrade on WS and HTTP ports, which browser (WebGL) clients need for `wss://`.
`edgegap_deploy` ●	Deploys an authoritative dedicated server close to your players. Always tagged `edgegap-mcp`, and reports when Edgegap will stop it.
`edgegap_wait_for_deployment`	Waits until the server is ready and returns the connection address.
`edgegap_get_deployment`	Reads a deployment's status.
`edgegap_list_deployments`	Lists running deployments, filtered by application, version, status, tags and more, and sorted by age. Finds servers left running; `only_agent_deployments: true` lists every one an agent started. See Filter Deployments.
`edgegap_get_deployment_logs`	Reads container logs and crash details while the deployment runs. After it stops, logs are only kept if Endpoint Storage was set up.
`edgegap_stop_deployment` ●	Stops one deployment, by its exact request ID. No bulk stop.

Matchmaking

Tool	What it does
`edgegap_build_matchmaker_config`	Generates a matchmaker configuration (teams, team size, optional latency rules and expansions) and checks that the version it deploys exists. Set `allowed_cors_origins` for browser (WebGL) clients. Upload the result in the dashboard to create your matchmaker, which starts a dedicated server for each match.

Learn more about the configuration in Matchmaking.

Relays (Host-Client Games Only)

A relay is not a game server: it forwards traffic while one player's game hosts the match. See Dedicated Servers or Relays?.

Tool	What it does
`edgegap_create_relay_session` ●	Creates a relay session for your players and returns the relay address and each player's authorization token.
`edgegap_get_relay_session`	Reads a relay session.
`edgegap_authorize_relay_user` ●	Adds a player who joins later.
`edgegap_delete_relay_session` ●	Closes a relay session.

[!WARNING] Deployments and relay sessions are billed while they run. Ask your agent to stop test deployments and delete test relay sessions when it's done.

Example Prompts

"Write a Dockerfile for my Unity server build, then push it and deploy a server near me."
"Check my Dockerfile for Edgegap and fix any problems."
"Create a matchmaker config for 2v2 matches on my latest version."
"My deployment failed. Read the logs and tell me why."
"My game uses host-client networking. Set up an Edgegap relay for two players."

🛡️ Guardrails

Your API token can do anything in your organization, so the server adds its own limits around what an agent does with it. They apply in both the local server and the hosted endpoint.

Guardrail	What it does
Dry run	Every tool that changes something takes `dry_run: true`: it returns the exact method, host, path and body, with the token, registry tokens and env values masked, and sends nothing. Local checks still run.
No token in containers	A deploy or version is refused, with nothing sent, if your API token appears in an env var name or value, a tag, or a webhook URL. Env values are never echoed back.
Agent tag	Every deployment gets the `edgegap-mcp` tag, even when the agent passes its own tags. `edgegap_list_deployments` with `only_agent_deployments: true` finds them all.
Auto-stop	Every deploy reports when Edgegap will stop it: the version's `max_duration`, capped at `EDGEGAP_MAX_DURATION_MINUTES` (default 60) for versions the agent creates. Edgegap has no per-deployment time limit, so a version made elsewhere can run up to its own limit (1440 minutes by default); the result warns when it is over an hour or unlimited.
No moving image tags	`edgegap_create_app_version` refuses `latest` (any case), an empty tag, or a tag Docker would reject, with nothing sent: Edgegap caches images by tag, so a re-pushed tag can deploy a stale build. Deploying an existing version on `latest` is refused too, and so is asking for registry push commands for `latest`.
Image reference check	A `docker_image` that also holds a registry host, tag or digest (e.g. `registry.edgegap.com/proj/server:v2`) is refused, and the error gives the right `docker_repository` / `docker_image` / `docker_tag` split. `edgegap_validate_server_config` flags the same things.
Deployment cap	`edgegap_deploy` is refused while `EDGEGAP_MAX_AGENT_DEPLOYMENTS` (default 5) deployments tagged `edgegap-mcp` are already running, so a looping agent cannot pile up billing servers. The refusal says how to list and stop them.
Hidden secret env vars	Env vars whose names look like secrets (`TOKEN`, `SECRET`, `PASSWORD`, `API_KEY`, `CREDENTIAL`, `AUTH`…) are sent with , so the dashboard does not show their values in plain text.

The server identifies itself with User-Agent: edgegap-mcp/<version> (<MCP client name>) on every API call.

Usage analytics. The local server and the self-hosted Docker image send nothing beyond the API calls themselves. The hosted endpoint at mcp.edgegap.dev uses PostHog MCP Analytics (@posthog/mcp) and sends usage events to Edgegap's PostHog: which MCP client connected, which tool, prompt or skill resource was used, the names (not values) of the arguments passed, whether a call succeeded and its error category, how long it took, and whether it was a dry run, plus the server version and Cloudflare's country code. Only named metadata properties are let through. It never sends your token, tool argument values (IP addresses, env vars, app or image names), results or error text, and GeoIP is off. It adds no parameters to the tools. Events from one token are grouped under a keyed, non-reversible hash of it. To opt out, send the header X-Edgegap-Telemetry: off (or DNT: 1), or use the local server.

🚨 Troubleshooting

Review common error codes and learn how to unlock your integration.

401 Unauthorized

Your MCP integration is most likely not including the Authorization header correctly.

403 Forbidden

Your MCP integration is likely using the template token or a deleted token. Please validate that the token value used by your integration matches exactly the token displayed in dashboard.

424 Image Could Not Be Pulled

Edgegap could not pull your container image. Check the repository, image name, and tag, and that the tag was pushed (ask your agent to list registry tags). For images in the Edgegap registry, the image name must include your project, e.g. my-project/my-game-server.

Registry Credentials Unavailable

Edgegap only gives registry credentials to the quick-start token the Unity and Unreal plugins use, so with a regular API token your agent can't retrieve them and asks you instead. Copy the Project, Username and Token from the dashboard under Container Registry, or push to another registry Edgegap can pull from (Docker Hub, GitHub, AWS ECR, GCP, GitLab). See External Registries.

Server Starts Locally but Not on Edgegap

Ask your agent to validate your server configuration, or to generate a new Dockerfile. The most common causes are an image built on Apple Silicon without docker build --platform linux/amd64, a server listening on a different port than the version exposes, or a UDP transport configured as TCP.

Other API Errors

Please consult our API Reference for possible error responses for individual API endpoints.

[!NOTE] If you need help, please reach out to us over Discord. For live games support see our ticketing system.

🛠️ Self-Hosting

The hosted endpoint at mcp.edgegap.dev runs as a Cloudflare Worker (see worker/INSTALL.md). To run the same stateless HTTP server on your own infrastructure, use the Docker image:

docker build -t edgegap-mcp .
docker run --rm -p 8080:8080 edgegap-mcp

Clients connect to http://<host>:8080/mcp with their own Authorization header, the same way they connect to the hosted endpoint. The image holds no credential, and /health answers without one. PORT, HOST, EDGEGAP_READ_ONLY, EDGEGAP_APP_ALLOWLIST, EDGEGAP_MAX_DURATION_MINUTES and EDGEGAP_MAX_AGENT_DEPLOYMENTS apply. Read worker/DECISION.md before exposing it beyond a private network.

Prebuilt images are published to ghcr.io/edgegap/edgegap-mcp, tagged main and sha-<commit> on every push to main, plus the version on v* tags:

docker run --rm -p 8080:8080 ghcr.io/edgegap/edgegap-mcp:main

Development

npm ci
npm run build
npm test                  # mock-API tests; none reach Edgegap
npm run typecheck:worker

To update the bundled skills to the latest commit of edgegap-agent-skills, then release as usual:

npm run sync-skills -- --ref main
npm run check-skills      # exit 1 if src/skills.generated.ts differs from the pin

Test	Covers
`test/package.mjs`	Packaging: one `bin`, runtime dependencies, versions in step
`test/skills.mjs`	Skills over MCP: tools, prompts, resources, path safety, bundle matches the pin
`test/smoke.mjs`	Handshake, tool registration, read-only mode
`test/guards.mjs`	Local validation and allowlist enforcement
`test/elicit.mjs`	Token prompt: accept, refuse acknowledgement, decline, no support
`test/newtools.mjs`	Validator, Dockerfile generator, registry, deployments, relay and matchmaker tools against a local mock API
`test/http.mjs`	Self-hosted HTTP server: discovery without a token, per-request tokens, foreign credentials
`test/live-check.mjs`	Not in `npm test`. Runs against the real API with a token from a non-production organization

Design decisions, the security model, and what's deliberately out of scope are in DESIGN.md.

Edgegap

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions