# AI 클라이언트 연결 — Godot · AI Game Developer Wiki

Claude Code, Cursor, Copilot, Codex, Gemini 등 MCP 클라이언트를 ai-game.dev 클라우드 엔드포인트나 자체 로컬 서버를 통해 Godot MCP에 연결하세요.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/godot/connecting-ai-clients).

Godot MCP는 둘 다 MCP 서버에 연결되는 두 가지 측면을 가집니다. Godot 에디터 안의 애드온과, 여러분이 대화하는 AI 클라이언트입니다. 이 페이지에서는 두 가지 연결 모드, 로그인 방식, 그리고 `godot-cli setup-mcp` 또는 도크의 **Configure** 버튼으로 지원되는 각 에이전트의 MCP 설정을 작성하는 방법을 설명합니다.

## 클라우드 모드(기본값)

클라우드 모드에서 애드온은 `https://ai-game.dev`의 호스팅 백엔드에 연결되고, AI 클라이언트는 MCP 엔드포인트 `https://ai-game.dev/mcp`에 연결됩니다. 여러분의 머신에서 추가로 실행되는 것은 없으며 방화벽을 넘어서도 동작합니다. 이것이 기본 모드이며 대부분의 사용자에게 권장하는 모드입니다.

### 디바이스 플로우로 로그인

클라우드 인증은 OAuth 2.1 디바이스 인증 플로우를 사용합니다. 토큰을 직접 복사할 필요가 없습니다:

```bash
godot-cli login
```

CLI가 짧은 코드를 출력하고 브라우저를 열어 여러분이 승인할 때까지 기다립니다. 자격 증명(액세스 토큰, 순환하는 리프레시 토큰, 만료 시각)은 머신 저장소 `~/.ai-game-dev/credentials.json`에 저장됩니다(macOS와 Linux에서는 파일 모드 0600, Windows에서는 DPAPI로 보호됨). 에디터 애드온, 다른 엔진 CLI, AI Game Dev 앱 모두 이 자격 증명을 사용하며, 만료된 액세스 토큰은 자동으로 갱신됩니다. 도크에서 **Authorize**를 클릭하면 Godot 내부에서 동일한 플로우가 실행됩니다.

유용한 `login` 플래그: `--force`는 기존 자격 증명이 있어도 다시 로그인하고, `--project <path>`는 프로젝트별로 별도의 자격 증명을 유지하며, `--tools-only`는 CI 러너용으로 더 좁은 범위의 자격 증명을 생성합니다. [godot-cli 레퍼런스](https://ai-game.dev/ko/docs/wiki/godot/cli#login)와 [인증](https://ai-game.dev/docs/auth)을 참고하세요.

### 고정된 프로젝트 URL

일반 엔드포인트 `https://ai-game.dev/mcp`는 에이전트를 연결된 에디터 중 하나로 라우팅합니다. 여러 프로젝트가 열려 있으면 모호해지므로, `setup-mcp`는 기본적으로 고정 URL을 작성합니다: `https://ai-game.dev/mcp/p/<pin>`. 여기서 pin은 프로젝트에서 파생됩니다. 이 설정으로 시작된 에이전트는 항상 이 프로젝트의 에디터에 도달합니다. 일반 URL을 원하면 `--no-pin`을 전달하세요.

### 프로젝트 키

로그인한 상태라면 `setup-mcp`는 에이전트 설정에 `Authorization: Bearer agd_pk_…` 형태로 프로젝트 키를 넣습니다. 프로젝트 키는 만료되지 않으며 이 프로젝트의 pin에만 동작하므로 여러분의 계정에 있는 다른 프로젝트에는 접근할 수 없습니다. 프로젝트마다 한 번 생성되고 `~/.ai-game-dev/project-keys.json`에서 재사용됩니다.

- `--regenerate-key`는 새 키를 만들고 설정을 다시 작성하며 이전 키를 폐기합니다.
- `--oauth`는 대신 URL만 있는 설정을 작성합니다. 에이전트가 자체 OAuth 프롬프트로 로그인합니다.
- 머신 로그인이 없으면 설정 역시 URL만 포함합니다.

**경고**

프로젝트 키는 자격 증명입니다. 프로젝트 키가 들어 있는 설정 파일(예: `.mcp.json` 또는 `.cursor/mcp.json`)을 공개 저장소에 커밋하지 마세요.

## 커스텀 모드: 자체 서버

커스텀 모드에서 애드온은 여러분이 선택한 서버 URL(예: 자체 머신의 서버)에 연결합니다. 서버는 오픈 소스 [GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server)이며, Unity MCP와 Unreal MCP가 사용하는 것과 동일한 바이너리입니다.

가장 쉬운 방법은 애드온이 서버를 실행하도록 하는 것입니다:

1. 도크에서 모드를 **Custom**으로 전환합니다.
2. **Server URL**을 `http://localhost:8080`으로 두거나 다른 로컬 URL을 입력합니다.
3. **Start Server**를 클릭합니다. 애드온은 고정된 서버 버전에 맞는 서버 빌드를 GitHub(HTTPS, github.com만)에서 내려받아 `.godot/mcp-server/<platform>/`에 캐시하고, 실행한 뒤 연결합니다.

**Stop Server**는 서버를 중지하며, 에디터를 닫아도 중지됩니다. CI 환경에서는 다운로드가 건너뛰어집니다. 대신 서버를 직접 실행하려면 릴리스 바이너리나 `aigamedeveloper/mcp-server` Docker 이미지를 내려받으세요:

```bash
./gamedev-mcp-server --client-transport streamableHttp --port 8080
```

### 커스텀 서버의 인증

커스텀 모드에는 세 가지 값을 가진 **Authorization Token** 스위치가 있습니다:

| 값 | 의미 |
| --- | --- |
| `none` | 인증 없음. 자체 머신에서만 수신하는 서버에 적합합니다. |
| `oauth` | 로그인한 ai-game.dev 계정 토큰을 전송하지만, localhost 서버(`localhost`, `127.0.0.0/8`, `::1`)에만 전송합니다. |
| `token` | 베어러 토큰. **New**를 클릭해 생성하며, 마스킹된 형태로 저장됩니다. |

`oauth`를 사용하는 로컬이 아닌 호스트의 경우 애드온이 계정 토큰 전송을 거부하므로, 대신 `GODOT_MCP_TOKEN`을 설정하세요. 두 모드의 환경 변수는 [Configuration](https://ai-game.dev/ko/docs/wiki/godot/configuration#environment-variables)에 나열되어 있습니다.

에이전트를 로컬 서버로 향하게 하려면 URL을 `setup-mcp`에 전달하세요:

```bash
godot-cli setup-mcp claude-code ./MyGodotProject --url http://localhost:8080
```

로컬 서버 설정에는 프로젝트 키가 포함되지 않습니다.

## 지원되는 에이전트와 설정 파일

`godot-cli setup-mcp --list`를 실행하면 모든 에이전트 id를 확인할 수 있습니다. 다음은 현재 CLI가 알고 있는 id와 설정을 기록하는 위치입니다:

| 에이전트 | id | 설정 파일 |
| --- | --- | --- |
| Claude Code | `claude-code` | 프로젝트의 `.mcp.json` |
| Claude Desktop | `claude-desktop` | Claude 사용자 지정 커넥터 사용 (아래 참고) |
| Cursor | `cursor` | `.cursor/mcp.json` |
| Visual Studio Code (Copilot) | `vscode-copilot` | `.vscode/mcp.json` |
| Visual Studio (Copilot) | `vs-copilot` | `.vs/mcp.json` |
| Rider (Junie) | `rider-junie` | `.junie/mcp/mcp.json` |
| GitHub Copilot CLI | `github-copilot-cli` | `~/.copilot/mcp-config.json` |
| Gemini | `gemini` | `.gemini/settings.json` |
| Antigravity | `antigravity` | `~/.gemini/config/mcp_config.json` 및 `~/.gemini/antigravity/mcp_config.json` |
| Cline | `cline` | VS Code 전역 저장소의 `cline_mcp_settings.json` |
| Open Code | `open-code` | `opencode.json` |
| Codex | `codex` | `.codex/config.toml` |
| Kilo Code | `kilo-code` | `.kilocode/mcp.json` |
| 기타 다른 MCP 클라이언트 | `custom` | 프로젝트의 `mcp.json` |

예시:

```bash
godot-cli setup-mcp cursor ./MyGodotProject
godot-cli setup-mcp codex ./MyGodotProject
godot-cli setup-mcp vscode-copilot ./MyGodotProject --oauth
```

모든 설정은 HTTP 전송을 사용합니다 (`type: http`와 URL). Codex의 경우 키는 `http_headers`에 들어갑니다.

### Claude Desktop과 claude.ai

Claude Desktop은 `claude_desktop_config.json`에서 HTTP 서버 항목을 받지 않습니다. 대신 Claude Desktop과 claude.ai는 Claude 사용자 지정 커넥터로 클라우드 엔드포인트에 연결합니다: Claude 설정에서 사용자 지정 커넥터를 추가하고, 프로젝트의 고정된 클라우드 URL을 붙여넣은 뒤 ai-game.dev 계정으로 로그인하세요. Claude Desktop은 Custom 모드 서버를 사용할 수 없습니다. Godot MCP가 이를 위한 stdio 전송을 제공하지 않기 때문입니다. 로컬 서버를 사용하려면 Claude Code처럼 HTTP를 지원하는 표에 있는 에이전트를 사용하세요.

## 독에서 구성하기

독의 **AI agent** 섹션은 `setup-mcp`와 같은 작업을 수행합니다: 목록에서 에이전트를 선택한 다음 **Configure**(또는 **Reconfigure**)를 클릭하세요. 상태 줄은 해당 에이전트의 설정 파일이 구성되었는지 알려주며, 구성 후 서버 URL, 모드 또는 인증을 변경하면 **Reconfiguration Required** 알림이 나타납니다. **Remove**는 해당 에이전트의 설정에서 Godot MCP 항목을 삭제합니다.

## 에이전트를 위한 스킬

일부 에이전트는 도구 사용 방법을 알려주는 스킬 파일(`SKILL.md`)을 읽습니다. AI agent 섹션 안에 있는 독의 **Skills** 행에서 이를 생성할 수 있습니다(**Generate** 또는 **Auto-generate** 스위치). 터미널에서는:

```bash
godot-cli setup-skills claude-code ./MyGodotProject
```

이 명령은 실행 중인 에디터 없이 에이전트의 스킬 폴더(예: Claude Code의 `.claude/skills`)에 파일을 기록합니다. `setup-skills --list`는 어떤 에이전트가 스킬을 지원하는지 보여줍니다.

## 복사해서 붙여넣는 설정

사용하는 클라이언트가 목록에 없다면 HTTP 서버를 지원하는 모든 MCP 클라이언트를 사용할 수 있습니다: `https://ai-game.dev/mcp`(또는 고정된 URL)를 지정하고 OAuth로 로그인하게 하거나, bearer 헤더를 추가하세요. 여러 클라이언트를 위한 바로 사용할 수 있는 스니펫은 [MCP 엔드포인트 페이지](https://ai-game.dev/ko/mcp-endpoint-info)에 있습니다.

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/godot/connecting-ai-clients

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/godot/connecting-ai-clients