AI 클라이언트 연결

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 디바이스 인증 플로우를 사용합니다. 토큰을 직접 복사할 필요가 없습니다:

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 레퍼런스와 인증을 참고하세요.

고정된 프로젝트 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만 포함합니다.

커스텀 모드: 자체 서버#

커스텀 모드에서 애드온은 여러분이 선택한 서버 URL(예: 자체 머신의 서버)에 연결합니다. 서버는 오픈 소스 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 이미지를 내려받으세요:

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

커스텀 서버의 인증#

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

oauth를 사용하는 로컬이 아닌 호스트의 경우 애드온이 계정 토큰 전송을 거부하므로, 대신 GODOT_MCP_TOKEN을 설정하세요. 두 모드의 환경 변수는 Configuration에 나열되어 있습니다.

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

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

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

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

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

예시:

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 스위치). 터미널에서는:

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 엔드포인트 페이지에 있습니다.