> For the complete documentation index, see [llms.txt](https://clunk.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://clunk.gitbook.io/docs/undefined-2/clients.md). # AI 도구 연결(MCP) Claude Code·Codex·Cursor·Copilot·Claude Desktop·VS Code에 Clunk를 연결하는 개발자 안내 개발 자동화가 필요할 때는 [에이전트 연결 화면](https://clunk.games/agents#connect)에서 연결 키를 만든 뒤, 사용하는 클라이언트의 설정을 복사합니다. 연결 주소는 Clunk가 운영하는 `/api/mcp`이고, 현재 서비스의 전체 주소는 `https://clunk.games/api/mcp`입니다. `https://clunk.games/connect`와 `https://clunk.games/mcp`는 이 연결 화면으로 보내는 별칭입니다. 둘을 별도 MCP 서버나 별도 페이지로 설정하지 마세요. {% hint style="warning" %} 연결 키는 발급한 화면에서 한 번만 표시됩니다. 설정에 넣은 뒤 키를 다른 사람과 공유하지 마세요. 유출되었다면 [에이전트 연결 화면](https://clunk.games/agents#connect)에서 폐기하고 새 키를 만드세요. {% endhint %} ## 어떤 연결을 고를까요? | 연결 | 쓰는 파일 | 내 컴퓨터 파일을 직접 읽나? | | --------------------------- | ------------------------------------- | ----------------------------------- | | **웹으로 바로 쓰는 도구(HTTP)** | Clunk `/api/mcp`와 내 계정 전용 키 | 아니요. 파일은 base64 또는 bundle로 보내야 합니다. | | **내 컴퓨터에서 쓰는 도구(로컬 stdio)** | Clunk 저장소의 `npm.cmd run --silent mcp` | 예. 로컬 경로를 직접 읽고, 로컬 결과를 쓸 수 있습니다. | 웹 연결은 마켓 검색과 업로드한 파일 검사를 자동화할 때 편리합니다. 파일이 내 컴퓨터에만 있고 업로드하지 않으려면 로컬 stdio를 사용하세요. ## 웹으로 바로 쓰는 도구(HTTP) 로그인 → **Clunk 연결 키 만들기** → 클라이언트 설정 복사 → **연결 확인** 순서입니다. `initialize`와 `tools/list`가 모두 응답하면 연결이 된 것입니다. ```http POST https://clunk.games/api/mcp Authorization: Bearer clunk_live_<발급받은-키> Content-Type: application/json {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}} ``` 현재 HTTP `tools/list`에는 다음 9개가 있습니다. `clunk_connection_check`, `clunk_search_assets`, `clunk_asset_facts`, `clunk_asset_inspect`, `clunk_asset_validate`, `clunk_asset_inspection_evidence`, `clunk_collaboration_append`, `clunk_scene_review`, `clunk_sprite_sheet_review` `clunk_asset_inspect`와 `clunk_asset_validate`는 로컬 경로를 읽지 않습니다. 한 파일은 `fileName` + `bytesBase64`, 여러 파일은 `entryFileName` + `files[]`로 보내야 합니다. `targetProfileId`만 보내면 검사할 바이트가 없어 거절됩니다. ## 클라이언트별 설정 연결 키를 직접 문서에 적지 말고, `/agents#connect`에서 생성된 값을 복사하세요. 아래는 화면이 만드는 설정의 모양입니다. {% tabs %} {% tab title="Claude Code" %} ```powershell $env:CLUNK_API_KEY = "clunk_live_REPLACE_WITH_KEY" claude mcp add clunk --scope user --transport http "https://clunk.games/api/mcp" --header "Authorization: Bearer $env:CLUNK_API_KEY" claude mcp list ``` {% endtab %} {% tab title="Codex" %} ```powershell $env:CLUNK_API_KEY = "clunk_live_REPLACE_WITH_KEY" codex mcp add clunk --url "https://clunk.games/api/mcp" --bearer-token-env-var CLUNK_API_KEY codex mcp get clunk --json ``` {% endtab %} {% tab title="Cursor / Claude Desktop" %} ```json { "mcpServers": { "clunk": { "type": "http", "url": "https://clunk.games/api/mcp", "headers": { "Authorization": "Bearer clunk_live_REPLACE_WITH_KEY" } } } } ``` `Cursor`는 프로젝트의 `.cursor/mcp.json`, `Claude Desktop`은 `claude_desktop_config.json`에 넣습니다. `clunk_live_REPLACE_WITH_KEY`를 에이전트 연결 화면에서 발급한 키로 바꿉니다. {% endtab %} {% tab title="VS Code" %} ```json { "servers": { "clunk": { "type": "http", "url": "https://clunk.games/api/mcp", "headers": { "Authorization": "Bearer clunk_live_REPLACE_WITH_KEY" } } } } ``` `.vscode/mcp.json`에 저장한 뒤 `MCP: List Servers`에서 확인합니다. {% endtab %} {% tab title="GitHub Copilot" %} ```powershell $env:CLUNK_API_KEY = "clunk_live_REPLACE_WITH_KEY" copilot mcp add --transport http --header "Authorization: Bearer $env:CLUNK_API_KEY" clunk "https://clunk.games/api/mcp" copilot mcp list ``` {% endtab %} {% endtabs %} 화면의 설정 다운로드에는 평문 키가 들어가지 않습니다. `clunk_live_REPLACE_WITH_KEY` 자리를 발급한 키로 바꾼 뒤 안전한 환경변수나 클라이언트의 비밀 저장소에 넣으세요. ## 로컬 stdio 내 컴퓨터 파일을 직접 읽는 로컬 MCP를 등록할 때만 아래 설정을 사용합니다. ``는 Clunk 저장소의 실제 절대 경로로 바꾸세요. ```json { "mcpServers": { "clunk": { "command": "cmd.exe", "args": ["/d", "/s", "/c", "call", "npm.cmd", "run", "--silent", "mcp"], "cwd": "" } } } ``` 로컬 서버는 JSON-RPC `initialize`, `ping`, `tools/list`, `tools/call`을 지원합니다. 로컬 `tools/list`에는 10개 도구가 있고, `clunk_optimize`와 `clunk_passport`, `clunk_asset_author`처럼 로컬 파일을 읽거나 새 파일을 쓰는 작업이 포함됩니다. 전체 입력·출력은 [계약과 상태](/docs/undefined-2/contracts.md)와 [CLI와 CI](/docs/undefined-2/cli-ci.md)를 보세요. ## 실패할 때 * `targetProfileId`에 `pc`, `web`, `mobile`을 넣지 마세요. 이 값은 로컬 `clunk_inspect`의 정책 프로파일이고, HTTP나 로컬 `clunk_asset_inspect`는 `web-three-mobile`, `unity`, `godot-4` 같은 엔진 프로파일을 사용합니다. * HTTP는 내 컴퓨터의 `C:\...` 경로를 해석하지 않습니다. 파일 바이트를 base64로 보내거나 로컬 stdio로 바꾸세요. * 연결 키를 잃어버리면 기존 키를 다시 볼 수 없으므로 새 키를 발급합니다. 파일 검사 통과가 게임 화면 승인을 뜻하지 않는 경계는 [계약과 상태](/docs/undefined-2/contracts.md)에 따로 적었습니다. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://clunk.gitbook.io/docs/undefined-2/clients.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.