# AI 클라이언트 연결하기 — Unity · AI Game Developer Wiki

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

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

이 페이지에서는 AI 클라이언트가 Unity 에디터에 도달하는 방법, 어떤 엔드포인트와 로그인을 사용하는지, 그리고 AI Game Developer 창에서, `unity-mcp-cli`에서 또는 수동으로 각 지원 에이전트를 구성하는 방법을 설명합니다.

## 두 가지 연결 방법

AI 클라이언트는 Unity와 직접 통신하지 않습니다. 둘 다 MCP 서버에 연결되며, 서버는 SignalR 연결을 통해 도구 호출을 에디터로 라우팅합니다.

|  | 클라우드 (기본값) | 사용자 지정 (로컬) |
| --- | --- | --- |
| 서버 | 호스팅 엔드포인트 `https://ai-game.dev/mcp` | 플러그인이 다운로드하고 시작하는 `gamedev-mcp-server` |
| 에디터 연결 | 플러그인이 ai-game.dev에 연결 | 플러그인이 `http://localhost:<port>`에 연결 |
| 클라이언트 엔드포인트 | `https://ai-game.dev/mcp/p/<pin>` (고정) 또는 `https://ai-game.dev/mcp` | `http://localhost:<port>`, 또는 stdio를 통한 서버 바이너리 |
| 로그인 | ai-game.dev 계정 (OAuth 디바이스 플로우) | 없음, ai-game.dev OAuth 또는 공유 토큰 |
| 오프라인 사용 | 아니요 | 예, `none` 또는 `token` 인증 사용 시 |

AI Game Developer 창의 **Connection** 스위치(**Custom** / **Cloud**)로 모드를 선택하세요. 로컬 서버 설정은 [Configuration](https://ai-game.dev/ko/docs/wiki/unity/configuration#connection-modes)에서 다룹니다.

## 고정 URL

기본 엔드포인트 `https://ai-game.dev/mcp`는 폴백을 통해 연결된 에디터 중 하나로 라우팅됩니다. 프로젝트를 하나만 열어 두었다면 문제없지만, 여러 개라면 모호해집니다.

**고정된** URL인 `https://ai-game.dev/mcp/p/<pin>`은 항상 특정 프로젝트의 에디터로 라우팅됩니다. 핀은 프로젝트의 식별 정보에서 파생됩니다. 창의 **Configure** 버튼과 `unity-mcp-cli setup-mcp`는 기본적으로 고정 URL을 작성하며, `setup-mcp --no-pin`은 대신 기본 URL을 작성합니다. stdio 전송의 경우 핀은 `project=<pin>` 인수로 전달됩니다.

## 로그인

에디터, CLI, 데스크톱 앱은 `~/.ai-game-dev/credentials.json`에 있는 하나의 머신 전체 로그인을 공유합니다. 어느 것이든 한 번만 로그인하면 됩니다:

- 창에서: Cloud 모드 선택 후 **Authorize**, 그다음 브라우저에서 코드를 승인합니다.
- 터미널에서: `unity-mcp-cli login`.
- [AI Game Dev app](https://ai-game.dev/docs/app)에서: **Sign in**.

토큰은 백그라운드에서 갱신됩니다. 창의 **Revoke**는 해당 머신의 모든 AI Game Dev 도구(모든 엔진 플러그인, CLI, 데스크톱 앱)에서 로그아웃시키고 서버의 토큰을 폐기합니다.

AI 클라이언트 자체의 인증 방식은 작성된 구성에 따라 다릅니다:

- **Project key (로그인한 경우 Cloud HTTP의 기본값).** 구성에는 이 프로젝트에만 바인딩된, 만료되지 않고 폐기 가능한 키인 `Authorization: Bearer agd_pk_…`가 포함됩니다. 키는 `~/.ai-game-dev/project-keys.json`에 보관됩니다. 창의 **Regenerate key** 또는 `setup-mcp --regenerate-key`가 키를 교체하고 이전 키를 폐기합니다.
- **OAuth (URL만).** 파일에 자격 증명이 없으며, 클라이언트는 처음 연결할 때 브라우저 로그인을 엽니다. 로그인하지 않은 상태이거나 `setup-mcp --oauth`를 사용할 때 이 방식이 됩니다.
- **Personal Access Token.** CI 또는 브라우저 로그인을 할 수 없는 클라이언트의 경우, ai-game.dev 계정에서 토큰을 만들고([Authentication](https://ai-game.dev/docs/auth) 참고) `setup-mcp --token <token>`으로 전달하세요.

프로젝트 키와 토큰은 비밀번호처럼 다루세요. `.mcp.json` 같은 파일은 프로젝트 폴더에 있으므로 커밋하기 전에 `.gitignore`를 확인하세요. 계정 쪽 설명은 [Authentication](https://ai-game.dev/docs/auth)에 있습니다.

## 지원하는 AI 에이전트

창의 **AI agent** 드롭다운에 이러한 구성 도구들이 나열됩니다. **Configure**는 표시된 파일을 작성하고, **Remove**는 해당 항목을 다시 제거합니다.

| 에이전트 | 작성되는 구성 파일 | CLI id |
| --- | --- | --- |
| Claude Code | `.mcp.json` (프로젝트 루트) | `claude-code` |
| Claude Desktop | Claude의 앱 데이터 폴더에 있는 `claude_desktop_config.json` | `claude-desktop` |
| Cursor | `.cursor/mcp.json` | `cursor` |
| Visual Studio Code (Copilot) | `.vscode/mcp.json` | `vscode-copilot` |
| Visual Studio (Copilot) | `.vs/mcp.json` | `vs-copilot` |
| Rider (Junie) | `.junie/mcp/mcp.json` | `rider-junie` |
| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | `github-copilot-cli` |
| Gemini | `.gemini/settings.json` | `gemini` |
| Antigravity | `~/.gemini/config/mcp_config.json` 및 `~/.gemini/antigravity/mcp_config.json` | `antigravity` |
| Cline | VS Code의 전역 저장소에 있는 `cline_mcp_settings.json` | `cline` |
| Open Code | `opencode.json` | `open-code` |
| Codex | `.codex/config.toml` | `codex` |
| Kilo Code | `.kilocode/mcp.json` | 창에서만 |
| Zoo Code | `.roo/mcp.json` | 창에서만 |
| Unity AI | `UserSettings/mcp.json` | `unity-ai` |
| 기타 - 사용자 지정 | 복사할 JSON을 표시 | `custom` |

상대 경로는 Unity 프로젝트 내부를 기준으로 합니다. 서버 항목의 이름은 항상 `ai-game-developer`입니다. `unity-mcp-cli setup-mcp --list`를 실행하면 사용 중인 CLI 버전이 지원하는 id를 볼 수 있습니다.

**팁**

Claude Desktop과 Unity AI는 생성된 스킬을 사용하지 않으며, Custom 항목에서 스킬 폴더를 선택할 수 있습니다. 다른 에이전트의 경우에도 에이전트가 RQL을 학습하도록 **Skills > Auto-generate**를 켜거나 `setup-skills`를 실행하세요.

## unity-mcp-cli로 구성하기

`setup-mcp`는 Unity를 열지 않고도 창의 **Configure** 버튼과 동일한 출력을 작성합니다:

```bash
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-mcp cursor ./MyUnityProject --transport stdio
unity-mcp-cli setup-mcp claude-code ./MyUnityProject --no-pin
```

기본 전송 방식은 `http`입니다. `--transport stdio`를 사용하면 구성이 대신 로컬 서버 바이너리를 실행합니다. 모든 플래그는 [CLI reference](https://ai-game.dev/ko/docs/wiki/unity/cli#setup-mcp)에 있습니다.

## 수동으로 구성하기

HTTP를 지원하는 모든 MCP 클라이언트는 호스팅 엔드포인트를 사용할 수 있습니다. Claude Code 예시:

```bash
claude mcp add --transport http ai-game-developer https://ai-game.dev/mcp
```

일반적인 `mcpServers` JSON 구성:

```json
{
  "mcpServers": {
    "ai-game-developer": {
      "url": "https://ai-game.dev/mcp"
    }
  }
}
```

특정 프로젝트를 대상으로 하려면 URL을 프로젝트의 고정 URL(창의 수동 구성 단계에 표시됨)로 바꾸세요. [MCP endpoint page](https://ai-game.dev/ko/mcp-endpoint-info)에는 VS Code의 `servers` 형식과 PAT 헤더를 포함해 모든 클라이언트용 스니펫이 있습니다.

### HTTP를 통한 로컬 서버

HTTP 전송을 사용하는 Custom 모드에서는 클라이언트를 로컬 서버로 지정하세요. 포트는 창의 **Server URL**에 있는 포트입니다. 창에 표시된 에이전트용 수동 구성 단계에 프로젝트 핀을 포함한 정확한 URL이 있습니다:

```json
{
  "mcpServers": {
    "ai-game-developer": {
      "url": "http://localhost:<port>"
    }
  }
}
```

### stdio를 통한 로컬 서버

stdio 전송에서는 클라이언트가 서버 바이너리를 직접 실행합니다. Windows의 경우:

```bash
claude mcp add ai-game-developer "<project>/Library/mcp-server/win-x64/gamedev-mcp-server.exe" port=<port> plugin-timeout=10000 client-transport=stdio
```

다른 플랫폼에서는 `osx-arm64`, `osx-x64`, `linux-x64`, `linux-arm64`, `win-x86`, `win-arm64`를 사용하세요(Windows 외에는 `.exe` 없이). `<project>`는 전체 프로젝트 경로로, `<port>`는 창에 표시된 포트로 바꾸세요. stdio 서버는 한 번에 하나의 에이전트만 사용할 수 있으며, 에이전트가 프로세스를 소유하므로 창의 Start/Stop 버튼은 비활성화됩니다. 클라이언트가 HTTP를 지원하지 않는 경우가 아니라면 HTTP를 사용하는 것이 좋습니다.

## 구성 후

새 구성을 읽도록 AI 클라이언트를 다시 시작하거나 MCP 서버에 다시 연결하세요. 그런 다음 [Getting started](https://ai-game.dev/ko/docs/wiki/unity/getting-started#verify)를 따라 연결을 확인하세요. 클라이언트에 도구가 표시되지 않으면 [Troubleshooting](https://ai-game.dev/ko/docs/wiki/unity/troubleshooting#no-tools)을 참고하세요.

---

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

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