# Gency MCP

Gency MCP는 [Gency](https://gency.ai) AI 상품 이미지 생성 플랫폼을 Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code 같은 MCP 클라이언트에서 사용할 수 있게 해주는 공식 Model Context Protocol 서버입니다.

상품 이미지 업로드, 워크스페이스/템플릿 조회, AI 상품 이미지 생성, 크레딧 확인, 결과 이미지 다운로드를 AI 어시스턴트 대화 안에서 실행할 수 있습니다.

또한 외부 개발자가 Gency OpenAPI를 자신의 서비스에 통합하는 코드를 작성할 때 이 MCP를 보조 도구로 활용할 수 있습니다. MCP 자체는 OAuth로만 인증하며, 사용자가 직접 호출하는 REST API 통합 코드용 API Key는 [developers.gency.ai](https://developers.gency.ai)에서 별도로 발급·관리합니다.

## Overview

- 기본 실행 방식: MCP stdio server
- 패키지명: `@gency-ai/gency-mcp`
- **지원 프로토콜 리비전: `2026-07-28` 과 `2025-11-25` 동시 지원 (dual-era)**
- 인증 방식: **OAuth 2.0 only** — gency-mcp는 OAuth 토큰으로만 인증합니다. REST API 직접 호출용 API Key는 별도(`developers.gency.ai`)
- 기본 API URL: `https://openapi.gency.ai`
- 제공 기능: 21개 MCP tools (HTTP 모드는 18개), API reference resource, 상품 생성 prompt

### Node.js 보안 버전

Node 22.23.4 이상(22.x), 24.22.1 이상(24.x), 또는 26.12.1 이상(26.x)을 사용하세요.
이 최소 버전은 [2026년 10월 Node.js 보안 릴리스](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases)를 반영합니다. 지원 종료된 Node 20 및 홀수 메이저 버전은 지원하지 않습니다.

MCP 패키지를 업데이트해도 PC나 HTTP 서버에 설치된 Node.js는 바뀌지 않습니다. MCP를 실행하는 환경에서 `node -v`를 확인하고 Node.js를 별도로 업데이트한 뒤 MCP 클라이언트 또는 서버를 다시 시작하세요. `engines` 설정은 지원 범위를 알리며, 패키지 관리자가 경고만 출력할 수 있습니다.

HTTP 모드는 SDK server/client 2.3.1 이상을 기준으로 검증하며, 요청마다 새 서버 인스턴스를 생성합니다. 요청 본문은 1 MiB, 도구 인수의 배열 요소·객체 키는 합계 10,000개로 제한합니다. 큰 상품 배치는 나눠 호출하세요. 요소 제한은 SDK의 스키마 검증 전에 적용되며, 로컬 stdio 모드의 입력 동작은 유지합니다. 이는 SDK의 [HTTP 응답 혼선](https://github.com/advisories/GHSA-jm63-cq47-j5jp)과 [검증 중 메모리 고갈](https://github.com/advisories/GHSA-46jr-4wx8-v453) 대응을 포함합니다.

### 프로토콜 호환성

클라이언트가 negotiate 하는 리비전으로 서비스합니다. 별도 설정은 필요 없습니다.

| 클라이언트가 요구하는 것 | 동작 |
|---|---|
| `2025-11-25` 이하 (`initialize` 핸드셰이크) | 그대로 동작 |
| `2026-07-28` (`server/discover`) | 그대로 동작 |

2026-07-28 은 프로토콜 레벨 세션과 `initialize` 핸드셰이크를 제거했습니다
([SEP-2567](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567),
[SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)).
구버전 클라이언트는 새 리비전으로 올라갈 수단이 없기 때문에
([호환성 매트릭스](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning)에서
legacy 클라이언트 → modern 전용 서버는 "Fails"), gency-mcp 는 한쪽으로
전환하지 않고 양쪽을 서비스합니다.

## Use Cases

Gency MCP는 두 가지 사용 시나리오를 지원합니다.

### 1. AI 어시스턴트로 Gency 사용 (주 사용처)

Claude·Cursor·VS Code 같은 MCP 클라이언트 안에서 상품 이미지 업로드 → 템플릿 선택 → AI 상품 이미지 생성 → 결과 다운로드 흐름을 자연어 대화로 실행합니다. 일반 사용자, 마케팅·운영 팀이 주 대상입니다.

### 2. Gency OpenAPI 통합 구축 보조

외부 개발자가 Gency OpenAPI를 자신의 서비스/제품에 통합할 때, MCP에 탑재된 `search_docs` 툴과 `api-reference` 리소스를 통해 AI 어시스턴트가 엔드포인트·인증(OAuth 2.0 + PKCE, X-API-Key)·스키마·웹훅을 이해한 상태로 통합 코드 작성, 디버깅, 마이그레이션을 도와줍니다. 통합 코드가 호출할 REST API의 자격증명(API Key 또는 OAuth client)은 [developers.gency.ai](https://developers.gency.ai)에서 발급받아 **사용자가 자기 코드에 직접 넣어 사용**합니다. MCP가 그 자격증명을 대신 보관하거나 사용하지는 않습니다.

예시:

- "Gency `create_product` API 요청 본문 스키마 알려줘. TypeScript 타입으로 정의해줘."
- "Gency 웹훅 페이로드 구조 검색하고, Express 핸들러 예제 만들어줘."
- "OAuth 2.0 + PKCE 흐름 어떻게 되는지 docs 검색해서 우리 백엔드에 맞게 구현해줘."

## Quick Start

### 1. MCP 서버 등록

Claude Code 예시:

```bash
claude mcp add gency -- npx -y @gency-ai/gency-mcp
```

> 모든 MCP 클라이언트에서 공유하려면 `-s user`, 프로젝트 단위로만 쓰려면 `-s project` 등 scope 옵션을 추가하세요. 기본값(local) 그대로 두면 현재 작업 디렉터리에서만 동작합니다.

다른 MCP 클라이언트에서는 command를 `npx`, args를 `["-y", "@gency-ai/gency-mcp"]`로 등록합니다.

### 2. 로그인

터미널에서 OAuth 로그인을 실행합니다.

```bash
npx -y @gency-ai/gency-mcp login
```

브라우저에서 Gency 로그인을 완료하면 토큰이 `~/.gency/tokens.json`에 저장됩니다.

### 3. 사용 확인

MCP 클라이언트에서 Gency 서버가 연결된 뒤 아래처럼 요청해보세요.

- "Gency 인증 상태 확인해줘"
- "Gency 워크스페이스 목록 보여줘"
- "내 남은 Gency 크레딧 확인해줘"
- "이 상품 사진들을 업로드해서 상품 이미지 생성 준비해줘"

## Authentication

Gency MCP는 **OAuth 2.0 (Authorization Code + PKCE)** 만 사용합니다. API Key 기반 인증은 MCP 런타임에서 지원하지 않습니다.

로그인:

```bash
npx -y @gency-ai/gency-mcp login
```

브라우저에서 Gency 로그인을 완료하면 토큰이 `~/.gency/tokens.json`에 저장되고, 이후 모든 MCP 도구 호출이 `Authorization: Bearer …` 헤더로 자동 인증됩니다. 만료된 액세스 토큰은 다음 호출 시 refresh token으로 자동 갱신됩니다.

로그아웃 (저장된 OAuth 토큰 삭제):

```bash
npx -y @gency-ai/gency-mcp logout
```

MCP 대화 안에서도 `login`, `logout`, `auth_status` tools를 사용할 수 있습니다.

### Direct REST API 호출 (MCP 외부)

자신의 백엔드/서버 코드에서 Gency OpenAPI(`https://openapi.gency.ai/openapi/v1/…`)를 직접 호출하는 경우에는 API Key를 `X-API-Key` 헤더로 보낼 수 있습니다.

```bash
curl https://openapi.gency.ai/openapi/v1/teams/me \
  -H "X-API-Key: gency_key_…"
```

API Key는 [developers.gency.ai](https://developers.gency.ai) 의 App 상세 페이지에서 발급·활성화·재발급합니다. 이 키는 **사용자의 통합 코드에서 직접 사용**하는 것이며, gency-mcp에 등록하거나 환경변수로 주입할 수 없습니다.

## Client Setup

먼저 `npx -y @gency-ai/gency-mcp login`으로 인증을 완료한 뒤 클라이언트에 MCP 서버를 등록합니다.

<details>
<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add gency -- npx -y @gency-ai/gency-mcp
```

</details>

<details>
<summary><strong>Codex CLI</strong></summary>

`~/.codex/config.toml`에 추가합니다.

```toml
[mcp_servers.gency]
command = "npx"
args = ["-y", "@gency-ai/gency-mcp"]
```

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

`claude_desktop_config.json`에 추가합니다.

```json
{
  "mcpServers": {
    "gency": {
      "command": "npx",
      "args": ["-y", "@gency-ai/gency-mcp"]
    }
  }
}
```

</details>

<details>
<summary><strong>Cursor</strong></summary>

프로젝트의 `.cursor/mcp.json` 또는 전역 MCP 설정에 추가합니다.

```json
{
  "mcpServers": {
    "gency": {
      "command": "npx",
      "args": ["-y", "@gency-ai/gency-mcp"]
    }
  }
}
```

</details>

<details>
<summary><strong>VS Code MCP clients</strong></summary>

사용 중인 MCP 클라이언트 설정에 아래 값을 등록합니다.

| Field | Value |
|---|---|
| Command | `npx` |
| Args | `["-y", "@gency-ai/gency-mcp"]` |

</details>

## Example Prompts

- "Gency 인증 상태 확인하고 다음에 뭘 해야 하는지 알려줘."
- "내 Gency 워크스페이스와 팀 정보를 보여줘."
- "워크스페이스에서 사용 가능한 템플릿 목록을 보여줘."
- "이 로컬 이미지 파일들을 Gency에 업로드해줘."
- "크레딧 확인 후, 상품 이미지 생성을 진행할 수 있는지 확인해줘."
- "생성된 상품의 다운로드 이미지를 받아줘."

상품 생성은 크레딧을 소모하고 데이터를 생성하는 작업입니다. `create_product`, `create_workspace`, `update_workspace`, `update_product_status` 같은 변경 작업은 실행 전에 사용자 확인을 받아야 합니다.

## Available Tools

Gency MCP는 21개의 MCP tools를 제공합니다 (HTTP serve 모드는 `login`/`logout`/`auth_status` 를 제외한 18개 — [HTTP Serve Mode](#http-serve-mode) 참고).

| Category | Tools |
|---|---|
| Auth | `login`, `logout`, `auth_status` |
| Workspace | `list_workspaces`, `create_workspace`, `update_workspace` |
| Team / User | `get_team`, `get_me`, `list_users`, `get_user` |
| Templates | `list_templates` |
| Products | `list_products`, `get_product`, `create_product`, `update_product_status` |
| Images | `prepare_product_images`, `get_upload_url`, `upload_image`, `download_product_image` |
| Usage | `get_credits` |
| Docs | `search_docs` |

`prepare_product_images` 는 `get_upload_url` + `upload_image` 를 6장 이상 한 번에 처리해주는 편의 도구입니다. 일반 사용자 플로우는 이 도구를 사용하고, 저수준 제어가 필요할 때만 개별 도구를 사용하세요.

`get_upload_url` 은 `uploadUrl` 과 함께 `uploadHandle` 을 반환하고, `upload_image` 는 URL 대신 그 **handle** 을 받습니다. handle 은 대상 URL·만료·호출자 신원을 HMAC 으로 묶은 값이라 목적지가 서명 안에서 나옵니다 — 임의의 로컬 파일을 임의의 HTTPS URL 로 PUT 할 수 없고, 한 호출자의 handle 을 다른 호출자가 사용할 수 없습니다.

`download_product_image` 는 상품 상세페이지를 렌더해 이미지 파일로 저장합니다. 저장 위치는 `outputPath`(절대경로)로 지정할 수 있고, 생략하면 OS 임시 디렉터리에 `gency-<productId>.png` 로 저장됩니다. 렌더링은 수십 초가 걸릴 수 있어 이 도구만 최대 3분까지 기다립니다.

`create_product` 의 `category` 는 현재 Gency API가 `CLOTHING` 만 허용합니다. 다른 값은 `현재 CLOTHING 카테고리만 지원됩니다` 오류로 거부됩니다.

## CLI Reference

`gency-mcp`는 인자 없이 실행하면 MCP stdio server로 동작합니다.

| Command | Description |
|---|---|
| `gency-mcp` | MCP stdio server 실행 |
| `gency-mcp serve` | MCP stdio server 명시 실행 |
| `gency-mcp setup` | 첫 설정 OAuth 마법사 |
| `gency-mcp login [options]` | 브라우저 OAuth login 실행 후 token 저장 |
| `gency-mcp logout` | 저장된 OAuth token 삭제 (`~/.gency/tokens.json`) |
| `gency-mcp whoami` | 현재 OAuth token introspection 결과 출력 |
| `gency-mcp serve-http [options]` | HTTP MCP server 실행 |
| `gency-mcp help` | CLI help 출력 |

### Login Options

| Option | Description |
|---|---|
| `--client-id <id>` | OAuth client ID override |
| `--client-secret <secret>` | OAuth client secret override |
| `--api-base <url>` | OAuth provider base URL override |
| `--scope <scope>` | Space-separated OAuth scopes |
| `--port <number>` | Loopback callback port, default `53682` |
| `--no-browser` | 브라우저를 자동으로 열지 않고 authorize URL만 출력 |

### HTTP Serve Mode

`serve-http`는 일반 사용자용 기본 실행 모드가 아닙니다. 원격 MCP 클라이언트나 특수 통합 환경에서 사용합니다. RFC 9728 protected-resource metadata 를 다음 두 경로에 모두 서빙합니다 (2026-07-28 부터 MCP 서버 필수 사항):

- `/.well-known/oauth-protected-resource/mcp` — `WWW-Authenticate` challenge 가 가리키는 경로
- `/.well-known/oauth-protected-resource` — 스펙의 401 예시가 쓰는 path-less 형태

authorization server metadata (`/.well-known/oauth-authorization-server`) 는 **의도적으로 서빙하지 않습니다.** 문서의 `issuer` 는 Gency 인데 우리 origin 에서 나오면 RFC 8414 issuer/location 불일치이고, 클라이언트는 이제 PRM 으로 AS 를 찾아야 하므로 존재 이유가 없습니다.

```bash
npx -y @gency-ai/gency-mcp serve-http --port 53683 --host 127.0.0.1
```

| Option | Description |
|---|---|
| `--port <number>` | HTTP server port, default `53683` |
| `--host <addr>` | Listen host, default `127.0.0.1` |
| `--client-id <id>` | OAuth token introspection client ID |
| `--client-secret <secret>` | OAuth token introspection client secret |
| `--api-base <url>` | OAuth provider URL |
| `--public-url <url>` | Non-loopback binding 뒤에 사용할 public HTTPS base URL |
| `--allowed-hosts <csv>` | Non-loopback 요청에서 허용할 Host 값 목록 |
| `--allowed-origins <csv>` | Non-loopback 요청에서 허용할 browser Origin 목록 |

`127.0.0.1`, `localhost`, `::1` 이외의 주소에 바인딩할 때는 위 세 가지 보안 옵션이 모두 필요합니다.

**HTTP 모드는 stateless 입니다.** 매 요청이 자기 bearer 토큰으로 인증되고, 그 토큰으로 Gency API 를 호출합니다. 세션에 결합되지 않습니다 — 2026-07-28 이 프로토콜 세션을 제거했고 `Mcp-Session-Id` 는 무시됩니다. 세션 조작이었던 `GET /mcp` 와 `DELETE /mcp` 는 `405` 를 반환합니다. 게이트웨이나 로드밸런서를 앞에 둘 때 sticky routing 은 필요하지 않습니다.

HTTP 모드에서는 `login` / `logout` / `auth_status` 를 노출하지 않습니다 (18개 tools). 이 세 도구는 **서버 호스트**의 `~/.gency/tokens.json` 을 다루므로 원격 호출자에게는 의미가 없거나 위험합니다. stdio 모드는 기존처럼 로컬 로그인 정보를 사용합니다 (21개 tools).

여러 인스턴스로 수평 확장할 때는 `GENCY_MCP_UPLOAD_SECRET` 을 모든 인스턴스에 동일하게 설정해야 합니다 — 그러지 않으면 한 인스턴스가 발급한 `uploadHandle` 이 다른 인스턴스에서 검증되지 않습니다.

## Configuration

| Environment Variable | Description | Default |
|---|---|---|
| `GENCY_API_URL` | Gency API base URL | `https://openapi.gency.ai` |
| `GENCY_OAUTH_CLIENT_ID` | OAuth client ID override | built-in official client ID |
| `GENCY_OAUTH_CLIENT_SECRET` | OAuth client secret for confidential clients | unset |
| `GENCY_OAUTH_API_BASE` | OAuth provider base URL | `GENCY_API_URL` |
| `GENCY_OAUTH_SCOPE` | OAuth scopes | `product:read product:write team:read team:write user:read` |
| `GENCY_MCP_ALLOWED_CLIENT_IDS` | `serve-http` 에서 토큰을 수락할 OAuth client ID 목록 (공백/쉼표 구분). 비어 있으면 모든 client 를 수락 | unset |
| `GENCY_MCP_UPLOAD_SECRET` | `uploadHandle` 서명 키. 여러 인스턴스로 확장할 때만 필요 | 프로세스별 랜덤 |
| `GENCY_MCP_OAUTH_RESOURCE` | RFC 8707 resource indicator. 설정하면 authorize/token/refresh 에 `resource` 를 전송 | unset (미전송) |

`GENCY_MCP_ALLOWED_CLIENT_IDS` 는 기본값을 켤 수 없습니다. HTTP 모드에서 원격 MCP 호스트는 **자기 client_id** 로 Gency 에 OAuth 하므로, 우리 introspection client_id 로 allowlist 를 만들면 정당한 호출자를 전부 거부합니다. Gency 가 introspection 에 `aud` 를 반환하기 전까지는, 이 값을 명시적으로 설정하는 것이 다른 Gency 클라이언트에 발급된 토큰의 재사용을 막는 유일한 수단입니다. `aud` 가 오면 별도 설정 없이 자동으로 검증됩니다.

`GENCY_MCP_OAUTH_RESOURCE` 가 opt-in 인 이유: 2026-07-28 은 클라이언트가 `resource` 를 보내도록 요구하지만, Gency AS 가 이를 수락하는지 검증되지 않았고 알 수 없는 `resource` 값을 거부하는 AS 는 모든 사용자의 로그인을 깨뜨립니다.

Credentials are stored under `~/.gency/`.

| Path | Description |
|---|---|
| `~/.gency/tokens.json` | OAuth access/refresh token storage (mode 0600) |

## Troubleshooting

### MCP tool says there are no credentials

OAuth로 로그인합니다.

```bash
npx -y @gency-ai/gency-mcp login
```

그 후 MCP 클라이언트에서 `auth_status`를 실행하면 현재 상태를 확인할 수 있습니다. API Key는 MCP에서 인증에 사용되지 않으므로 등록할 필요가 없습니다.

### OAuth login does not open a browser

Use `--no-browser` and open the printed URL manually.

```bash
npx -y @gency-ai/gency-mcp login --no-browser
```

### OAuth callback port is already in use

Use a custom port only if that redirect URI is allowed by the OAuth client.

```bash
npx -y @gency-ai/gency-mcp login --port 53684
```

### `create_product` 가 "최소 6장 필요" 라고 함

상품당 이미지 최소 6장이 Gency API 요구사항입니다. `prepare_product_images` 도구로 한 번에 처리하면 6장 미만일 때 즉시 알려주고 업로드도 일괄 처리됩니다.

### `create_product` 가 "추측값 사용 금지" 라고 함

`colors`, `fabrics`, `features`, `laundryTips` 에 "면 100%", "30도 이하 찬물 세탁" 같은 일반 기본값이 포함되면 validation 단계에서 차단됩니다. 사용자에게 실제 값을 확인 후 재호출하세요.

### `templateId` 가 유효하지 않음

워크스페이스마다 사용 가능한 템플릿이 다릅니다. `list_templates` 를 다시 호출해 현재 워크스페이스의 템플릿 ID 목록을 확인하세요.

### Token refresh 실패

`auth_status` 결과 introspect 가 inactive 이고 refresh 도 실패하면 토큰이 만료됐거나 폐기된 상태입니다.

```bash
npx -y @gency-ai/gency-mcp logout
npx -y @gency-ai/gency-mcp login
```

### 업로드한 이미지가 사라짐

업로드된 이미지는 `create_product` 호출 없이 **24시간** 후 자동 삭제됩니다. 업로드 후에는 그 안에 `create_product` 를 호출해 imageId 를 사용해야 합니다.

### 클라이언트가 "unsupported protocol version" 또는 서버 시작 실패를 보고함

gency-mcp 는 `2025-11-25` 와 `2026-07-28` 을 모두 서비스하므로 리비전 불일치로 이 오류가 나지는 않습니다. 확인할 것:

1. `npx -y @gency-ai/gency-mcp` 가 최신 버전을 받았는지 (`npx --yes @gency-ai/gency-mcp@latest`)
2. 지원되는 보안 버전인지 (`node -v`): Node 22.23.4 이상(22.x), 24.22.1 이상(24.x), 또는 26.12.1 이상(26.x)
3. 클라이언트 설정이 `serve-http` 를 가리키는 경우, 그 URL 에 OAuth bearer 토큰을 붙이는지 — HTTP 모드는 인증 없는 요청을 `401` 로 거부합니다

`GET /mcp` 또는 `DELETE /mcp` 에서 `405` 를 받는 것은 정상입니다. 이들은 2026-07-28 이 제거한 세션 조작이며 오류가 아닙니다.

### Build fails with `tsc: command not found`

Install dependencies first.

```bash
pnpm install
pnpm run build
```

## Links

- [Gency](https://gency.ai)
- [Gency Developers](https://developers.gency.ai)
- [API Reference](https://studiolab-2.gitbook.io/gency-developers)
- [llms.txt](https://developers.gency.ai/llm/llms.txt)

## License

MIT License. © 2026 [STUDIOLAB](https://studiolab.ai). All rights reserved.