# 구성 — Godot · AI Game Developer Wiki

AI Game Developer dock에서 Godot MCP를 구성하고, AI 에이전트가 볼 도구를 선택하며, GODOT_MCP_* 환경 변수로 설정을 재정의하세요.

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

대부분의 사용자는 설정을 변경할 필요가 없습니다. 애드온은 Cloud 모드로 시작하고, 로그인하면 연결되며, 모든 도구를 노출합니다. 이 페이지에서는 필요할 때 **AI Game Developer** dock, 저장된 설정, 그리고 CI 및 스크립트 실행용 환경 변수를 통해 무엇을 변경할 수 있는지 설명합니다.

## AI Game Developer dock

애드온은 Godot 에디터의 오른쪽 위 dock 영역에 **AI Game Developer**라는 이름의 dock을 추가합니다. 위에서 아래로 다음 섹션이 있습니다.

### 헤더

헤더에는 애드온 버전과 **Log Level** 선택기가 표시됩니다. 로그 레벨은 애드온과 연결이 Output 패널에 얼마나 많이 출력할지 제어합니다(`Trace`, `Debug`, `Info`, `Warning`, `Error`, `None`; 기본값 `Info`). 연결 문제를 진단할 때는 `Debug` 또는 `Trace`로 올리세요. `GODOT_MCP_LOG_LEVEL`이 설정되어 있으면 선택기가 비활성화되고 그 사실을 알리는 안내가 표시됩니다.

### 연결

- **Cloud / Custom**: 연결 모드입니다. Cloud는 [ai-game.dev](https://ai-game.dev)에 연결하고, Custom은 선택한 서버 URL에 연결합니다.
- **Connect / Stop**: MCP 서버 연결을 시작하거나 중지합니다. 애드온은 연결될 때까지 백그라운드에서 계속 재시도합니다.
- Cloud 모드에서: **Authorize**(브라우저 디바이스 로그인 시작) 및 **Sign out**과 함께 로그인 상태를 표시합니다.
- 세 개의 점, 즉 Godot, MCP server, AI agent로 이루어진 한 줄이 무엇이 연결되어 있는지 보여줍니다. AI agent 행에는 연결된 클라이언트 이름이 나열되며, 아직 연결된 클라이언트가 없으면 "(connects on demand)"라고 표시됩니다.

Custom 모드에서는 **MCP server** 카드가 다음을 추가합니다:

- **Server URL**: 연결할 서버로, 기본값은 `http://localhost:8080`입니다.
- **Authorization Token**: `none`, `oauth`(ai-game.dev 계정 토큰으로, localhost 서버에만 전송됨) 또는 `token`(베어러 토큰; **New**로 생성) 중 하나입니다.
- **Start Server / Stop Server**: 애드온에 고정된 서버 버전과 일치하는 로컬 서버를 다운로드, 시작 및 중지합니다. [Connecting AI clients](https://ai-game.dev/ko/docs/wiki/godot/connecting-ai-clients#custom-mode)를 참고하세요.

환경 변수가 모드나 호스트를 강제하면 "Overridden by environment (GODOT\_MCP\_\*)"라는 노란색 안내가 표시되고, dock에서 변경해도 적용되지 않습니다.

### AI agent

사용하는 AI 클라이언트를 선택하세요(기본값은 Claude Code). 그러면 이 섹션에 다음이 표시됩니다:

- **Skills**: 에이전트의 스킬 파일이 저장되는 위치, 애드온 로드 시 스킬 파일을 새로 고치는 **Auto-generate** 스위치, 그리고 **Generate** 버튼입니다. 스킬을 지원하지 않는 에이전트는 "Skills not supported by this agent"를 표시합니다.
- **Model Context Protocol (MCP)**: 에이전트의 MCP 구성이 설정되었는지 여부와 **Configure** / **Reconfigure** 및 **Remove** 버튼입니다. 에이전트를 구성한 뒤 서버 설정이 변경되면 **Reconfiguration Required** 알림이 나타납니다.

### MCP features

**Tools**, **Prompts**, **Resources**의 세 행이 있으며, 각 행에는 전체 항목 중 표시되는 항목 수(도구는 예상 토큰 비용도 표시)와 **Open** 버튼이 있습니다. 열리는 창에는 모든 항목이 **Visible** 스위치 및 필터 필드와 함께 나열됩니다.

**Visible**은 MCP 클라이언트가 도구 목록에서 해당 항목을 볼지 여부만 결정합니다. 필요 없는 도구를 숨기면 에이전트의 컨텍스트가 더 작아집니다. 이는 접근 제어가 아닙니다. 숨겨진 도구도 클라이언트가 이름으로 호출하면 여전히 실행됩니다.

### Extensions

**Install** 및 **Update** 버튼이 있는 선택적 Godot MCP 확장 목록입니다. 이 목록은 `.csproj`에 포함된 확장 카탈로그를 읽습니다. 목록이 비어 있으면 [Extensions](https://ai-game.dev/ko/docs/wiki/godot/extensions)를 참고하세요.

### 푸터

도움말 및 문제 보고용 링크, 그리고 선택한 노드나 오브젝트가 AI를 위해 어떻게 직렬화되는지 보여주는 **Serialization Check** 창(버그 보고 시 유용)입니다.

## 설정이 저장되는 위치

dock은 설정을 `user://godot-mcp-config.json`에 저장하며, 이는 프로젝트의 Godot 사용자별 데이터 폴더(프로젝트 내부가 아님)에 있습니다. 이 파일에는 연결 모드, 커스텀 호스트, 인증 옵션, 로그 레벨, 선택한 에이전트, 도구 표시 여부, 사용한 토큰이 저장됩니다.

**경고**

이 파일은 토큰을 평문 JSON으로 저장합니다. 커밋, 동기화 또는 공유하지 마세요. 토큰을 교체하려면 dock에서 로그아웃하거나 토큰을 지우거나(또는 파일을 삭제) 다시 연결하세요.

Cloud 로그인 자격 증명은 머신 저장소 `~/.ai-game-dev/credentials.json`에 별도로 있으며, 다른 AI Game Developer 도구와 공유됩니다. 에이전트 구성용 프로젝트 키는 `~/.ai-game-dev/project-keys.json`에 있습니다.

터미널에서 `godot-cli configure`를 실행하면 프로젝트 파일 `.godot-mcp/features.json`의 도구, 프롬프트, 리소스 표시 여부를 나열하고 변경합니다:

```bash
godot-cli configure ./MyGodotProject --list
godot-cli configure ./MyGodotProject --disable-tools script-delete,script-execute
godot-cli configure ./MyGodotProject --enable-all-tools
```

## 환경 변수

환경 변수는 파일을 편집하지 않고도 저장된 설정을 덮어쓸 수 있어 CI, 헤드리스 실행, 로컬 개발에 편리합니다. 애드온은 프로젝트의 `.env` 파일에서도 이 값을 읽으며, 프로세스 환경 변수가 `.env`보다 우선합니다.

| 변수 | 값 | 용도 |
| --- | --- | --- |
| `GODOT_MCP_CONNECTION_MODE` | `Cloud`, `Custom` | 연결 모드를 강제합니다. 기본값은 `Cloud`입니다. |
| `GODOT_MCP_CLOUD_URL` | URL | 클라우드 기본 URL을 재정의합니다. 기본값은 `https://ai-game.dev`입니다. |
| `GODOT_MCP_HOST` | URL | Custom 모드의 서버 URL입니다. 기본값은 `http://localhost:8080`입니다. |
| `GODOT_MCP_AUTH_OPTION` | `none`, `oauth`, `token` | Custom 모드 인증입니다. |
| `GODOT_MCP_TOKEN` | 문자열 | 활성 모드의 Bearer 토큰입니다. 저장된 토큰을 덮어쓰며 다시 기록되지 않습니다. |
| `GODOT_MCP_LOG_LEVEL` | `Trace` ~ `None` | 로그 상세 수준입니다. |
| `GODOT_MCP_CREDENTIALS_DIR` | 절대 경로 | 격리된 테스트를 위해 별도의 자격 증명 저장소를 사용합니다. |
| `GODOT_MCP_TOOL_FORMAT` | `Rql`, `Json` | 도구가 인자를 받고 결과를 반환하는 방식입니다. 기본값은 `Rql`(간결한 텍스트)이며, `Json`은 JSON 스키마와 결과를 유지합니다. |
| `GODOT_MCP_SERVER_PATH` | 절대 경로 | 에디터 전용: 고정된 릴리스를 다운로드하는 대신 이 기존 서버 바이너리를 시작합니다. |
| `GODOT_MCP_RUNTIME_FROM_EDITOR` | `1` | Play로 시작한 게임이 자체 인게임 MCP 런타임도 연결할 수 있게 합니다. |

예: 로컬 서버를 대상으로 에디터를 시작합니다.

```bash
export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:8080
godot --editor --path ./MyGodotProject
```

`godot-cli open`은 `--mode`, `--url`, `--cloud-url`, `--token`, `--auth`, `--log-level`을 사용해 이 값들을 대신 설정해 줍니다. [godot-cli 레퍼런스](https://ai-game.dev/ko/docs/wiki/godot/cli#open)를 참고하세요.

## 도구 형식

기본 `Rql` 형식에서는 도구가 RQL 값(`"Level/Player"` 같은 노드 경로나 `godot.find("Name")`)을 인자로 받고, 토큰을 덜 소모하는 간결한 텍스트를 반환합니다. `GODOT_MCP_TOOL_FORMAT=Json` 또는 `toolFormat` 키로 설정하는 `Json` 형식은 전체 JSON 스키마와 구조화된 결과를 선호하는 클라이언트를 위해 이를 유지합니다. RQL에 대한 자세한 내용: [Tools](https://ai-game.dev/ko/docs/wiki/godot/tools#rql).

---

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

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