> 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/ko/docs/mcp.md).

# MCP 통합

MCP 서버를 통해 AI 코딩 에이전트를 Edgegap에 연결하세요: 게임 서버를 컨테이너화, 배포, 매칭하고 문제를 해결하는 도구와, 각 엔진 및 넷코드를 위한 검증된 워크플로를 제공합니다.

저희 MCP 서버는 여러분의 맞춤형 AI 코딩 에이전트가 맞춤 게임 서버 빌드를 시작하는 데 필요한 도구를 제공하고, 검증된 테스트 스위트로 각 통합 단계를 검증하는 데 도움을 줍니다.

## 👉 지원 기능

{% hint style="success" %}
**새 사용자 - 다음부터 시작하세요** [Unity](https://docs.edgegap.com/ko/unity.md)**,** [Unreal Engine](https://docs.edgegap.com/ko/unreal-engine.md)**, 또는** [Godot](https://docs.edgegap.com/ko/godot.md)**.** MCP 서버는 작동하는 컨테이너화된 게임 서버를 컨테이너 레지스트리에 업로드한 후에만 사용하는 것을 권장합니다.
{% endhint %}

다음과 같은 경우 저희 MCP 서버를 사용하세요:

* **게임 서버를 컨테이너화할 때** - 에이전트가 빌드를 위한 Dockerfile을 작성하거나(혹은 이미 가진 Dockerfile을 검토하고) 모범 사례에 맞는지 확인한 뒤, 이미지를 저희 비공개 컨테이너 레지스트리에 푸시하고, 사용하지 않는 오래된 이미지 태그를 삭제해 레지스트리 용량을 확보합니다.
* **전용 서버를 배포할 때** - 앱 버전을 생성하고 업데이트하며, 사용 가능한 위치를 확인하고, 플레이어와 가까운 곳에 배포하고, 클라이언트 연결 테스트를 위한 서버 IP와 포트를 받습니다.
* **CI/CD 파이프라인을 구축할 때** - 빌드 시스템에서 배포와 종료를 테스트합니다.
* **게임 서버 문제를 해결할 때** - 앱 버전과 배포 상태를 확인하고, 컨테이너 로그와 CPU/메모리 사용량을 읽거나, 실패한 배포를 재현합니다.
* **클라이언트-호스트 및 P2P 게임을 운영할 때** - NAT 펀치스루를 제공하는 릴레이 세션을 생성하여 연결 차단을 방지합니다. 검토 [오케스트레이션 모델](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#orchestration) 결정하기 전에.

{% hint style="warning" %}
MCP 범위를 벗어나며 지원하지 않는 항목: Linux 서버 실행 파일 빌드, 매치메이커 생성/시작/중지(생성된 설정은 대시보드에 업로드), 서버 브라우저, 로비, 관리형 클러스터, 프라이빗 플릿, 과금.
{% endhint %}

{% hint style="info" %}
도움이 필요하시면 [디스코드를 통해 문의해 주세요](https://discord.gg/MmJf8fWjnt). 실시간 게임 지원은 저희의 [티켓 시스템](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### 기술

엔진, 게임 백엔드, 넷코드에 대한 완전 테스트된 워크플로, 코드 템플릿, 알려진 함정에 대한 가드레일을 포함한 에이전트 기술을 나열하고 가져옵니다:

* Mirror, Netcode for GameObjects, FishNet, PurrNet, Photon Fusion 1 및 2를 포함한 Unity.
* Unreal Engine - EOS 음성 채팅 포함.
* Godot - ENET 및 netfox.
* Colyseus, Nakama, PlayFab, Three.js, 그리고 Manus AI.

에이전트는 행동하기 전에 프로젝트에 맞는 기술을 불러오며, `edgegap_update_skills`  로컬에 설치한 사본을 최신 상태로 유지합니다. [독립형 기술도 GitHub에서 사용할 수 있습니다.](https://github.com/edgegap/llm-agent-skills)

### 가드레일

API 토큰은 조직 내에서 모든 작업을 수행할 수 있으므로, MCP 서버는 에이전트가 이를 통해 할 수 있는 작업을 제한합니다:

* **드라이 런** - 무언가를 변경하는 모든 도구는 먼저 정확한 요청을 보여주고 아무것도 보내지 않을 수 있습니다.
* **컨테이너에 토큰 없음** - API 토큰이 환경 변수, 태그 또는 웹훅 URL에 표시되면 배포와 버전이 거부됩니다.
* **이동하는 이미지 태그 없음** - `latest`  그리고 빈 태그도 거부됩니다. Edgegap은 태그별로 이미지를 캐시하기 때문입니다.
* **배포 제한 및 자동 중지** - 모든 배포에는 태그가 지정됩니다 `edgegap-mcp`  그래서 찾고 중지할 수 있으며, Edgegap이 언제 중지할지 알려주고, 루프하는 에이전트가 한 번에 몇 개 이상 시작하지 못하게 합니다.
* **한 번에 하나씩** - 배포 중지와 레지스트리 태그 삭제에는 정확한 ID 하나가 필요하며, 일괄 삭제는 없습니다.

### 예시 프롬프트

* *"내 three.js 서버 빌드를 위한 Dockerfile을 작성한 다음, 이를 푸시하고 내 근처에 서버를 배포해 주세요."*
* *"Edgegap용 내 Dockerfile을 확인하고 문제를 수정해 주세요."*
* *"내 배포가 실패했습니다. 로그를 읽고 이유를 알려 주세요."*
* *"내 마지막 매치가 CPU와 메모리를 얼마나 사용했나요? 그에 맞게 내 버전 크기를 조정해 주세요."*
* *"내 게임은 호스트-클라이언트 네트워킹을 사용합니다. 두 플레이어를 위한 Edgegap 릴레이를 설정해 주세요."*

## 🚀 설치

MCP 서버 설치는 매우 간단합니다:

1. 다음용 MCP 서버를 설치하세요 [MCP 통합](https://docs.edgegap.com/ko/docs/mcp.md#popular-agents) 또는 다음으로 [MCP 통합](https://docs.edgegap.com/ko/docs/mcp.md#custom-integration).
2. 에이전트가 저희 MCP 서버와 함께 사용할 API 토큰을 생성하고 연결하세요:

Edgegap API용 비밀 토큰 생성 위치: [대시보드 - 사용자 설정 / 토큰](https://app.edgegap.com/user-settings?tab=tokens).

각 API 요청의 HTTP 헤더에 비밀 토큰을 추가하세요(다음 단어를 포함해야 함:  `token`):

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

{% hint style="danger" %}
**API 토큰을 사용하면 계정에 제한 없이 접근할 수 있으므로 게임 클라이언트에 Edgegap API 엔드포인트를 통합하지 마세요. 안전한 클라이언트용 API 엔드포인트와 함수는**  [통합](https://docs.edgegap.com/ko/docs/api/integration.md) **을 참조하세요.**
{% endhint %}

{% hint style="success" %}
비밀 토큰이 유출되거나 노출된 경우 대시보드에서 삭제한 후 새로 만드세요.
{% endhint %}

### 인기 있는 에이전트

선호하는 에이전틱 IDE에 Edgegap MCP 서버를 설치하세요: <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=Edgegap&#x26;config=eyJ1cmwiOiJodHRwczovL21jcC5lZGdlZ2FwLmRldi9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiIifX0%3D" class="button secondary" data-icon="cursor">Cursor</a><a href="vscode:mcp/install?%7B%22name%22%3A%22Edgegap%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.edgegap.dev%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22%22%7D%7D" class="button secondary" data-icon="vscode">VS Code</a>

그런 다음 토큰을 다음에 추가하세요 `Authorization` 헤더.

#### 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는 환경 변수에서 토큰을 읽습니다. 다음을 추가하세요 `~/.codex/config.toml`, 그런 다음 다음을 설정하세요 `EDGEGAP_API_TOKEN` Codex가 시작되는 환경에서 토큰으로 설정합니다:

{% 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

다운로드 [edgegap-mcp.mcpb](https://github.com/edgegap/llm-mcp-server/releases/latest/download/edgegap-mcp.mcpb) 그리고 여세요. Claude Desktop은 MCP 서버를 확장으로 설치하고 API 토큰을 요청하며, 이를 운영 체제의 보안 저장소에 보관합니다.

{% hint style="info" %}
claude.ai와 Claude Desktop의 사용자 정의 커넥터는 다음을 보낼 수 없습니다 `Authorization` 헤더를 아직 지원하지 않으므로, 대신 다음에 연결합니다 `mcp.edgegap.dev` 하지만 모든 도구 호출이 실패합니다. Claude Desktop에서는 대신 위의 원클릭 확장을 사용하세요.
{% endhint %}

#### mcp.json

대부분의 에이전틱 IDE는 JSON 구성을 붙여 넣어 통합하는 것도 지원합니다:

{% code title="mcp.json" collapsedlinecount="10" %}

```json
{
    "mcpServers": {
        "Edgegap": {
            "type": "http",
            "url": "https://mcp.edgegap.dev/mcp",
            "headers": {
                "Authorization": "EDGEGAP_API_TOKEN"
            }
        }
    }
}
```

{% endcode %}

### 사용자 정의 통합

공식 저장소는 저희 MCP 서버의 사용자 정의 통합을 위한 단일 진실 소스입니다:

{% embed url="<https://github.com/edgegap/llm-mcp-server>" %}

API 토큰을 자신의 컴퓨터에 보관하려면 Node 18+로 MCP 서버를 로컬에서 실행하세요. 토큰을 빼 두면 에이전트가 처음 사용할 때 요청합니다:

{% code title="npx를 사용하는 로컬 서버" collapsedlinecount="10" %}

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

{% endcode %}

로컬 서버는 예를 들어 읽기 전용 도구나 애플리케이션 목록으로 더 제한할 수도 있습니다. 다음을 참조하세요 [저장소](https://github.com/edgegap/llm-mcp-server#local-server) 에서 설정을 확인하세요.

또는 에이전트의 가상화된 환경에서 원격 Edgegap MCP 서버에 연결하세요(절대 프로젝트 내에서는 하지 마세요!):

{% code title="npx 패키지를 사용하는 node" collapsedlinecount="10" %}

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

{% endcode %}

{% code title="uvx 패키지를 사용하는 python" collapsedlinecount="10" %}

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

{% endcode %}

## 🚨 문제 해결

일반적인 오류 코드를 검토하고 통합을 해결하는 방법을 알아보세요.

### 401 인증되지 않음

MCP 통합에서 Authorization 헤더를 올바르게 포함하지 않았을 가능성이 큽니다.

### 도구 호출 실패

클라이언트에 Edgegap 토큰이 없습니다. 이는 claude.ai 및 Claude Desktop 사용자 정의 커넥터에서 발생하며, 이들은 다음을 보낼 수 없습니다 `Authorization` 헤더. 다음을 참조하세요 [Claude Desktop](https://docs.edgegap.com/ko/docs/mcp.md#claude-desktop) 대안은

{% hint style="warning" %}
이는 알려진 제한 사항이며 가까운 시일 내에 해결될 예정입니다. 업데이트를 기대해 주세요!
{% endhint %}

### 403 금지됨

MCP 통합이 템플릿 토큰이나 삭제된 토큰을 사용하고 있을 가능성이 큽니다. 통합에서 사용하는 토큰 값이 대시보드에 표시된 토큰과 정확히 일치하는지 확인하세요. 릴레이 도구에서 403은 조직에 릴레이 접근 권한이 없음을 의미합니다.

### 424 이미지를 가져올 수 없음

저장소, 이미지 이름, 태그를 확인하고, 태그가 푸시되었는지도 확인하세요(에이전트에게 레지스트리 태그 목록을 요청하세요). Edgegap 레지스트리의 이미지는 이미지 이름에 프로젝트가 포함되어야 합니다. 예: `my-project/my-game-server`.

### 레지스트리 자격 증명을 사용할 수 없음

자격 증명을 가져오려면 특수 빠른 시작 토큰이 필요합니다. [대시보드에서 다음 아래에 하나를 만드세요 **컨테이너 레지스트리**](https://app.edgegap.com/registry-management/repositories/list), 또는 다른 레지스트리로 푸시하세요(예: Docker Hub, GitHub, AWS ECR, GCP, GitLab).

다음을 참조하세요 [외부 레지스트리](https://docs.edgegap.com/docs/tools-and-integrations/docker/external-registries) 에서 Edgegap Container Registry를 완전히 지원하는 대안을 확인하세요.

### 로컬에서는 시작되지만 Edgegap에서는 시작되지 않음

에이전트에게 서버 구성을 검증하거나 새 Dockerfile을 생성하도록 요청하세요. 가장 흔한 원인은 다음 없이 Apple Silicon에서 빌드된 이미지입니다 `docker build --platform linux/amd64`, 버전이 노출하는 것과 다른 포트에서 수신하는 서버, 또는 UDP 전송이 TCP로 구성된 경우입니다.

### 기타 API 오류

다음을 참고하세요 [API 참조](https://docs.edgegap.com/ko/docs/api.md) 개별 API 엔드포인트의 가능한 오류 응답에 대해

{% hint style="info" %}
도움이 필요하시면 [디스코드를 통해 문의해 주세요](https://discord.gg/MmJf8fWjnt). 실시간 게임 지원은 저희의 [티켓 시스템](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}
