> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/docs/mcp-integration.md).
# MCP Integration
Connect AI coding agents to Edgegap through our MCP server: tools to containerize, deploy, match and troubleshoot game servers, plus tested workflows for each engine and netcode.
Our MCP server gives your custom AI coding agent the tools it needs to get started with custom game server builds and helps validate each integration step with our verified test suite.
## 👉 Supported Features
{% hint style="success" %}
**New users - start with** [Unity](/unity.md)**,** [Unreal Engine](/unreal-engine.md)**, or** [Godot](/godot.md)**.** Using MCP server is recommended only after you have a working containerized game server uploaded to a container registry.
{% endhint %}
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](/learn/orchestration/deployments.md#orchestration) before deciding.
{% hint style="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.
{% endhint %}
{% hint style="info" %}
If you need help, [please reach out to us over Discord](https://discord.gg/MmJf8fWjnt). For live games support see our [ticketing system](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}
### Skills
List and fetch agent skills, including fully tested workflows, code templates, and guardrails against known pitfalls for engines, game backends, and netcodes:
* Unity, including Mirror, Netcode for GameObjects, FishNet, PurrNet, Photon Fusion 1 and 2.
* Unreal Engine - including EOS voice chat.
* Godot - ENET and netfox.
* Colyseus, Nakama, PlayFab, Three.js, and Manus AI.
Your agent loads the skill that matches your project before it acts, and `edgegap_update_skills` keeps copies you installed locally up to date. [Standalone skills are also available on GitHub.](https://github.com/edgegap/llm-agent-skills)
### Guardrails
Your API token can do anything in your organization, so the MCP server limits what an agent does with it:
* **Dry run** - every tool that changes something can show the exact request first, and send nothing.
* **No token in containers** - deployments and versions are refused if your API token appears in an environment variable, tag, or webhook URL.
* **No moving image tags** - `latest` and empty tags are refused, because Edgegap caches images by tag.
* **Deployment cap and auto-stop** - every deployment is tagged `edgegap-mcp` so it can be found and stopped, reports when Edgegap will stop it, and a looping agent can't start more than a few at once.
* **One at a time** - stopping deployments and deleting registry tags take one exact ID; there is no bulk delete.
### Example prompts
* *"Write a Dockerfile for my three.js 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."*
## 🚀 Installation
MCP server installation is very simple:
1. Install the MCP server for [MCP Integration](/docs/mcp-integration.md#popular-agents) or with [MCP Integration](/docs/mcp-integration.md#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](https://app.edgegap.com/user-settings?tab=tokens).
Add your secret token with each API request as an HTTP header (include the word `token`):
`Authorization: token xxxxxxxx-e458-4592-b607-c2c28afd8b62`
{% hint style="danger" %}
**Do not integrate Edgegap API endpoints in game client, as your API token provides unlimited access to your account. See** [Integration](/docs/api/integration.md) **for secure client-facing API endpoints and functions.**
{% endhint %}
{% hint style="success" %}
In case your secret tokens are compromised or leaked, delete and re-create them from dashboard.
{% endhint %}
### Popular Agents
Install Edgegap MCP server in your preferred agentic IDE: CursorVS Code
Then add your token to the `Authorization` header.
#### Claude Code
{% code collapsedlinecount="10" %}
```bash
claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp \
-H "Authorization: token xxxxxxxx-e458-4592-b607-c2c28afd8b62" --scope user
```
{% endcode %}
#### ChatGPT Codex
Codex reads the token from an environment variable. Add this to `~/.codex/config.toml`, then set `EDGEGAP_API_TOKEN` to your token in the environment Codex starts from:
{% code title="config.toml" collapsedlinecount="10" %}
```toml
[mcp_servers.edgegap]
url = "https://mcp.edgegap.dev/mcp"
bearer_token_env_var = "EDGEGAP_API_TOKEN"
```
{% endcode %}
#### Claude Desktop
Download [edgegap-mcp.mcpb](https://github.com/edgegap/llm-mcp-server/releases/latest/download/edgegap-mcp.mcpb) and open it. Claude Desktop installs the MCP server as an extension and asks for your API token, which it keeps in your operating system's secure storage.
{% hint style="info" %}
Custom connectors in claude.ai and Claude Desktop can't send an `Authorization` header yet, so they connect to `mcp.edgegap.dev` but every tool call fails. In Claude Desktop, use the one-click extension above instead.
{% endhint %}
#### mcp.json
Most agentic IDEs also support integration by pasting JSON configuration:
{% code title="mcp.json" collapsedlinecount="10" %}
```json
{
"mcpServers": {
"Edgegap": {
"type": "http",
"url": "https://mcp.edgegap.dev/mcp",
"headers": {
"Authorization": "EDGEGAP_API_TOKEN"
}
}
}
}
```
{% endcode %}
### Custom Integration
The official repository is the single source of truth for custom integration of our MCP server:
{% embed url="" %}
To keep your API token on your own machine, run the MCP server locally with Node 18+. Leave the token out and your agent asks you for it on first use:
{% code title="local server using npx" collapsedlinecount="10" %}
```json
{
"command": "npx",
"args": ["-y", "@edgegap/mcp"],
"env": { "EDGEGAP_API_TOKEN": "xxxxxxxx-e458-4592-b607-c2c28afd8b62" }
}
```
{% endcode %}
The local server can also be limited further, for example to read-only tools or to a list of applications. See the [repository](https://github.com/edgegap/llm-mcp-server#local-server) for the settings.
Or connect to the remote Edgegap MCP server from your agent's virtualized environment (never in your project!):
{% code title="node using npx package" collapsedlinecount="10" %}
```json
{
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.edgegap.dev/mcp", "--transport", "http-only"]
}
```
{% endcode %}
{% code title="python using uvx package" collapsedlinecount="10" %}
```json
{
"command": "uvx",
"args": ["mcp-proxy", "--transport", "streamablehttp", "https://mcp.edgegap.dev/mcp"]
}
```
{% endcode %}
## 🚨 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](/docs/mcp-integration.md#claude-desktop) for the alternative.
{% hint style="warning" %}
This is a known limitation which will be resolved in the near term, stay tuned for updates!
{% endhint %}
### 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. On relay tools, a 403 means your organization doesn't have access to relays.
### 424 Image Could Not Be Pulled
Please verify your repository, image name, and tag, and if 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
Retrieving credentials requires a special quick-start token. [Create one in dashboard under **Container Registry**](https://app.edgegap.com/registry-management/repositories/list), or push to another registry (e.g. Docker Hub, GitHub, AWS ECR, GCP, GitLab).
See [External Registries](https://docs.edgegap.com/docs/tools-and-integrations/docker/external-registries) for fully supported alternatives to Edgegap Container Registry.
### 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](/docs/api.md) for possible error responses for individual API endpoints.
{% hint style="info" %}
If you need help, [please reach out to us over Discord](https://discord.gg/MmJf8fWjnt). For live games support see our [ticketing system](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}