Llm 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 reviews the one you have) against best practices, pushes the image to our private container registry, and removes unused old image tags to reclaim registry capacity.
• Deploying a dedicated server - create and update app versions, review available locations, deploy close to your players, and get server IP with ports to test client connection.
• 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 and CPU/memory utilization, or reproduce a failed deployment.
• Running client-host and peer-to-peer games - create relay sessions providing NAT punchthrough and avoid connection blocking. Review Orchestration Models and Dedicated Servers or Relays? before deciding.

[!WARNING] Out of scope / not supported by MCP: building Linux server executable; creating, starting or stopping a matchmaker (upload the generated configuration 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.

[!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:

1. Install the MCP server for Popular Agents or with Custom Integration.
2. 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 reads the token from an environment variable and sends it as Authorization: Bearer <token>, which the hosted endpoint accepts. In ~/.codex/config.toml:

[mcp_servers.edgegap]
url = "https://mcp.edgegap.dev/mcp"
bearer_token_env_var = "EDGEGAP_API_TOKEN"

Then set EDGEGAP_API_TOKEN to your token in the environment Codex starts from.

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.

Cursor

The Cursor button at the top of this page installs it; to do it by hand, add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

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

VS Code (Copilot agent mode)

The VS Code button at the top of this page installs it; to do it by hand, add this to .vscode/mcp.json (VS Code uses servers, not mcpServers):

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

Windsurf

In ~/.codeium/windsurf/mcp_config.json, run the Local Server, which works in every client that starts MCP servers as commands:

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

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"]
}

One-Click Install (Claude Desktop)

Download edgegap-mcp.mcpb and open it: Claude Desktop installs the local server as an extension and asks for your API token, which it keeps in the operating system's secure storage. The extension's settings also hold read-only mode, the application allowlist, the max duration ceiling and the deployment cap (the variables below). Each release attaches the bundle, built from that release's code. Any other app that installs MCPB bundles works the same way.

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/mcp@0.13.3) 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:

📚 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.

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: deploy-game-server ("Deploy my game server to Edgegap") is the place to start: it finds the engine and netcode, loads the matching skill and walks the golden path, cleanup included. There is also one prompt per skill, named after it. In Claude Code they show up as slash commands, e.g. /mcp__edgegap__deploy-game-server.
• Resources: each skill's SKILL.md is listed, at edgegap-skill://<skill>/SKILL.md; every other file is read through the edgegap-skill://{skill}/{+path} template, 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. edgegap_list_skills also reads the latest pack version from GitHub (one version number, cached for an hour; EDGEGAP_SKILLS_CHECK=off turns it off) and says when a newer one is out, and edgegap_get_skill adds the same note under a skill's header.

Keeping installed skills current. If you also installed the skills in your agent (the Claude Code plugin edgegap@edgegap, npx skills add edgegap/llm-agent-skills, or folders copied into ~/.claude/skills), edgegap_update_skills compares each one with the latest on GitHub. On the local server it finds those installs itself; with apply: true it runs npx skills update (Edgegap skills only) or claude plugin update, and rewrites hand-copied skills from the files bundled in this release, keeping files you added and leaving symlinks and git checkouts alone. It never downloads skill text. The hosted server cannot see your disk: pass the versions you have loaded in installed_versions and it says which are behind and how to update them.

🧰 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.

Before Your First Deployment

Dedicated Servers (Recommended)

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?.

[!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."
• "My deployment failed. Read the logs and tell me why."
• "How much CPU and memory did my last match use? Size my version for it."
• "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.

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, its error code, the stage it failed at and the Edgegap API status, how long it took, whether it was a dry run, a few facts about the call (how a wait for a deployment ended, a validation result, which skill was loaded), which golden-path step was reached, plus the server version and Cloudflare's country code. On a failed call it also sends the error message, after removing your token, the values of the arguments you passed, and anything shaped like a credential, an IP address or an ID, cut to 300 characters. Deployment IDs are only sent as a keyed hash. Only named metadata properties are let through. It never sends your token, tool argument values (IP addresses, env vars, app or image names) or results, 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. The full list is in docs/analytics.md. 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.

Tool Call Failed

Your client is missing an Edgegap token. This happens with claude.ai and Claude Desktop custom connectors, which can't send an Authorization header. See Claude Desktop and claude.ai for the alternative.

[!WARNING] This is a known limitation which will be resolved in the near term, stay tuned for updates!

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.

"status": "empty" or "not_configured"

Not an error. A list with nothing in it (no applications yet, no deployments running, an image never pushed) or a feature this organization has not set up (relays, a registry this token cannot read) comes back as a normal result with status and a next_step. Your agent should do the next step instead of retrying.

No Token Yet

The skills (edgegap_list_skills, edgegap_get_skill), edgegap_context, edgegap_generate_dockerfile and edgegap_validate_server_config work without a token, so an agent can prepare the server build first. Create an account at app.edgegap.com and a token under User Settings → Tokens. edgegap_context with check_token: true says whether the session's token is present and accepted, and shows its last four characters so you can find it on that page.

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 for linux/amd64 and linux/arm64 are published to ghcr.io/edgegap/llm-mcp-server (and, for existing setups, the old name 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/llm-mcp-server:main

Development

See CONTRIBUTING.md for the checks a change has to pass, CHANGELOG.md for what each version changed, and SECURITY.md to report a vulnerability.

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 llm-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

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