# MCP 서버 설정 가이드

GENCY MCP 서버를 설치하면 Claude, Cursor, VS Code 등 AI 어시스턴트에서 자연어로 GENCY API를 사용할 수 있습니다.

## 사전 준비

- Node.js 18 이상
- **자격증명 발급 불필요** — 공식 MCP 공용 OAuth 앱이 내장되어 있어 첫 사용 시 `gency-mcp login` 한 번 동의만 하면 됩니다.
- **gency-mcp 는 OAuth 인증만 사용합니다.** API Key는 MCP 에서 사용되지 않습니다. API Key는 자신의 코드(서버/스크립트)에서 GENCY REST API를 직접 호출할 때만 쓰며, 그 발급/관리는 [자격증명 발급 가이드](credentials.md) 참고.

## 1단계: 클라이언트에 등록

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 또는 `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

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

### Cursor

`.cursor/mcp.json`:

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

### VS Code (Copilot)

`.vscode/settings.json`:

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

### Claude Code

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

또는 `.mcp.json`:

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

## 2단계: 로그인 (최초 1회)

터미널에서:

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

브라우저가 열리며 GENCY 로그인 → 팀(master) 선택 → 동의. 토큰은 `~/.gency/tokens.json`(0600)에 저장되고 만료 시 자동 갱신됩니다.

```bash
npx -y @gency-ai/gency-mcp whoami     # 토큰 상태 확인
npx -y @gency-ai/gency-mcp logout     # 토큰 삭제
```

## 환경 변수 (선택)

기본값으로 충분하므로 보통 설정 불요. 자체 OAuth 앱을 사용할 때만 override:

| 변수                        | 필수 | 기본값                   | 설명                               |
| --------------------------- | ---- | ------------------------ | ---------------------------------- |
| `GENCY_API_URL`             | N    | https://openapi.gency.ai | API 기본 URL                       |
| `GENCY_OAUTH_CLIENT_ID`     | N    | (내장 공용 client_id)    | 자체 OAuth 앱 사용 시에만 override |
| `GENCY_OAUTH_CLIENT_SECRET` | N    | -                        | confidential client 일 때만 사용   |
| `GENCY_OAUTH_API_BASE`      | N    | `GENCY_API_URL`          | OAuth provider base URL            |
| `GENCY_OAUTH_SCOPE`         | N    | (전체 스코프)            | 요청 스코프 override               |

> `GENCY_API_KEY` 같은 API Key 환경변수는 gency-mcp 에서 더 이상 사용되지 않습니다. REST API 를 자신의 코드에서 직접 호출할 때 사용하는 별도의 자격증명입니다.

## 프롬프트 예시

설치 후 AI 어시스턴트에서 다음과 같이 사용할 수 있습니다:

- "GENCY 워크스페이스 목록 보여줘"
- "새 워크스페이스 '2026 FW 컬렉션' 만들어줘"
- "이 티셔츠 사진으로 AI 상품 이미지를 만들어줘"
- "크레딧 얼마나 남았어?"
- "이 상품 검수 완료로 상태 변경해줘"
- "GENCY Webhook 서명 검증 코드 짜줘"