구성
AI Game Developer dock에서 Godot MCP를 구성하고, AI 에이전트가 볼 도구를 선택하며, GODOT_MCP_* 환경 변수로 설정을 재정의하세요.
대부분의 사용자는 설정을 변경할 필요가 없습니다. 애드온은 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에 연결하고, 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를 참고하세요.
환경 변수가 모드나 호스트를 강제하면 "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를 참고하세요.
푸터
도움말 및 문제 보고용 링크, 그리고 선택한 노드나 오브젝트가 AI를 위해 어떻게 직렬화되는지 보여주는 Serialization Check 창(버그 보고 시 유용)입니다.
설정이 저장되는 위치
dock은 설정을 user://godot-mcp-config.json에 저장하며, 이는 프로젝트의 Godot 사용자별 데이터 폴더(프로젝트 내부가 아님)에 있습니다. 이 파일에는 연결 모드, 커스텀 호스트, 인증 옵션, 로그 레벨, 선택한 에이전트, 도구 표시 여부, 사용한 토큰이 저장됩니다.
Cloud 로그인 자격 증명은 머신 저장소 ~/.ai-game-dev/credentials.json에 별도로 있으며, 다른 AI Game Developer 도구와 공유됩니다. 에이전트 구성용 프로젝트 키는 ~/.ai-game-dev/project-keys.json에 있습니다.
터미널에서 godot-cli configure를 실행하면 프로젝트 파일 .godot-mcp/features.json의 도구, 프롬프트, 리소스 표시 여부를 나열하고 변경합니다:
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 런타임도 연결할 수 있게 합니다. |
예: 로컬 서버를 대상으로 에디터를 시작합니다.
export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:8080
godot --editor --path ./MyGodotProjectgodot-cli open은 --mode, --url, --cloud-url, --token, --auth, --log-level을 사용해 이 값들을 대신 설정해 줍니다. godot-cli 레퍼런스를 참고하세요.
도구 형식
기본 Rql 형식에서는 도구가 RQL 값("Level/Player" 같은 노드 경로나 godot.find("Name"))을 인자로 받고, 토큰을 덜 소모하는 간결한 텍스트를 반환합니다. GODOT_MCP_TOOL_FORMAT=Json 또는 toolFormat 키로 설정하는 Json 형식은 전체 JSON 스키마와 구조화된 결과를 선호하는 클라이언트를 위해 이를 유지합니다. RQL에 대한 자세한 내용: Tools.