> ## Documentation Index
> Fetch the complete documentation index at: https://docs.headlesscommerce.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 서버

> AI 에이전트로 Headless Commerce 스토어를 관리하세요

# MCP 서버

MCP (Model Context Protocol) 서버는 Claude, ChatGPT, Cursor 같은 AI 에이전트가 자연어로 스토어를 관리할 수 있게 합니다.

```
                    ┌── 클라우드 (HTTP) ──► https://mcp.headlesscommerce.io/mcp
AI 에이전트 ────────┤                                    │
(Claude, Cursor,    └── 로컬 (stdio) ───► npx @headless-commerce/mcp-server
 ChatGPT)                                                │
                                                   SDK ──► Headless Commerce API
```

MCP 서버는 **stateless**입니다 — 데이터를 저장하지 않고, AI 에이전트와 Headless Commerce API 사이의 다리 역할만 합니다.

## 연결 방식

| | 클라우드 (권장) | 로컬 (stdio) |
| - | - | - |
| **설정** | URL + API 키 또는 OAuth | Node.js 설치 필요 |
| **전송 방식** | Streamable HTTP | stdio (JSON-RPC) |
| **인증** | API 키 또는 OAuth 2.0 | API 키만 |
| **업데이트** | 항상 최신 | 수동 `npm update` |
| **오프라인** | 불가 | 가능 |
| **적합한 경우** | 프로덕션, 대부분의 사용자 | 에어갭, 자체 호스팅 |

## 인증

클라우드 MCP 서버는 두 가지 인증 방식을 지원합니다:

| 방식 | 적합한 경우 | 스코프 |
| - | - | - |
| **API 키** (`sk_`) | 빠른 설정, 전체 관리자 접근 | `admin` (모든 권한) |
| **OAuth 2.0** | 서드파티 앱, 세분화된 권한 | 리소스별 설정 가능 |

### API 키 발급

1. [Headless Commerce 대시보드](https://app.headlesscommerce.io)에 로그인
2. **설정 > API 키**로 이동
3. **API 키 생성** 클릭 후 **Secret** 타입 선택 (`sk_` 접두사)
4. 생성된 키를 복사 — 한 번만 표시됩니다

<Warning>
  MCP 서버는 **Secret Key** (`sk_`)가 필요합니다. Publishable Key (`pk_`)는 스토어프론트 전용이므로 Admin 엔드포인트에서 거부됩니다.
</Warning>

## 설정

***

### 클라우드 (권장)

<Info>설치가 필요 없습니다 — URL과 API 키만 추가하세요.</Info>

#### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json`에 추가:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "url": "https://mcp.headlesscommerce.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key"
      }
    }
  }
}
```

#### Claude Code

```bash theme={null}
claude mcp add headless-commerce \
  --transport http \
  --url https://mcp.headlesscommerce.io/mcp \
  --header "Authorization: Bearer sk_live_your_api_key"
```

또는 `.claude/settings.json`에 추가:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "url": "https://mcp.headlesscommerce.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key"
      }
    }
  }
}
```

#### Cursor

`.cursor/mcp.json`에 추가:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "url": "https://mcp.headlesscommerce.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key"
      }
    }
  }
}
```

#### OAuth 2.0 (서드파티 앱용)

전체 관리자 권한 대신 세분화된 스코프 기반 접근이 필요한 앱은 **OAuth 2.0 with PKCE**를 사용할 수 있습니다.

OAuth를 지원하는 MCP 클라이언트는 자동으로 인증 설정을 검색합니다:

1. `https://mcp.headlesscommerce.io/.well-known/mcp.json` — OAuth 메타데이터 URL 반환
2. `https://mcp.headlesscommerce.io/.well-known/oauth-protected-resource` — 지원 스코프 및 인증 서버 반환
3. `https://api.headlesscommerce.io/.well-known/oauth-authorization-server` — 인가 및 토큰 엔드포인트 반환

**인가 플로우:**

```
1. 클라이언트 등록    POST /oauth/register
2. 사용자 인가       GET  /oauth/authorize?response_type=code&code_challenge=...&scope=...
3. 코드 교환         POST /oauth/token  (grant_type=authorization_code)
4. 토큰 사용         Authorization: Bearer <access_token>
5. 토큰 갱신         POST /oauth/token  (grant_type=refresh_token)
```

**사용 가능한 스코프:**

| 스코프 | 설명 |
| - | - |
| `admin` | 모든 리소스에 대한 전체 접근 |
| `products:read` | 상품, 카테고리, 컬렉션 조회 |
| `products:write` | 상품 생성 및 수정 |
| `orders:read` | 주문 조회 |
| `orders:write` | 주문 관리 (확인, 취소) |
| `customers:read` | 고객 조회 |
| `customers:write` | 고객 관리 |
| `inventory:read` | 재고 수준 조회 |
| `inventory:write` | 재고 조정 |
| `discounts:read` | 할인 조회 |
| `discounts:write` | 할인 생성 및 관리 |
| `store:read` | 스토어 설정 조회 |
| `store:write` | 스토어 설정 수정 |
| `dashboard:read` | 대시보드 분석 조회 |

<Info>
  `:write` 스코프는 동일 리소스의 `:read` 접근을 자동으로 포함합니다. 예를 들어 `orders:write`는 `orders:read` 권한도 부여합니다.
</Info>

**토큰 수명:**

| 토큰 | 수명 |
| - | - |
| 인가 코드 | 10분 (일회용) |
| 액세스 토큰 | 1시간 |
| 리프레시 토큰 | 30일 (사용 시 자동 갱신) |

<Note>
  모든 OAuth 플로우에서 PKCE (`S256`)가 **필수**입니다. Plain `code_challenge_method`는 지원하지 않습니다.
</Note>

***

### 로컬 (stdio)

MCP 서버를 로컬에서 실행하려면 npm으로 설치하세요:

```bash theme={null}
npm install -g @headless-commerce/mcp-server
# 또는 바로 실행
npx @headless-commerce/mcp-server
```

#### 환경 변수

| 변수 | 필수 | 기본값 | 설명 |
| - | - | - | - |
| `HEADLESS_COMMERCE_API_KEY` | 예 | — | Admin API 키 (`sk_` 접두사) |
| `HEADLESS_COMMERCE_API_URL` | 아니오 | `https://api.headlesscommerce.io/v1` | API 기본 URL (로컬 개발 시 오버라이드) |

#### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json`에 추가:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "command": "npx",
      "args": ["-y", "@headless-commerce/mcp-server"],
      "env": {
        "HEADLESS_COMMERCE_API_KEY": "sk_live_your_api_key"
      }
    }
  }
}
```

#### Claude Code

`.claude/settings.json`에 추가:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "command": "npx",
      "args": ["-y", "@headless-commerce/mcp-server"],
      "env": {
        "HEADLESS_COMMERCE_API_KEY": "sk_live_your_api_key"
      }
    }
  }
}
```

#### Cursor

`.cursor/mcp.json`에 추가:

```json theme={null}
{
  "mcpServers": {
    "headless-commerce": {
      "command": "npx",
      "args": ["-y", "@headless-commerce/mcp-server"],
      "env": {
        "HEADLESS_COMMERCE_API_KEY": "sk_live_your_api_key"
      }
    }
  }
}
```

#### 로컬 개발

로컬 개발 시 API URL을 오버라이드하세요:

```json theme={null}
{
  "env": {
    "HEADLESS_COMMERCE_API_KEY": "sk_test_your_api_key",
    "HEADLESS_COMMERCE_API_URL": "http://localhost:3010/v1"
  }
}
```

## 사용 가능한 도구

### 상품

| 도구 | 설명 |
| - | - |
| `list_products` | 검색, 필터링, 페이지네이션으로 상품 목록 조회 |
| `get_product` | 변형, 이미지, 옵션 포함 상품 상세 조회 |
| `create_product` | 새 상품 생성 |
| `update_product` | 상품명, 설명, 상태, 태그 수정 |

### 변형

| 도구 | 설명 |
| - | - |
| `create_variant` | 가격 포함 변형 생성 (최소 통화 단위) |

### 주문

| 도구 | 설명 |
| - | - |
| `list_orders` | 상태/결제/출고 필터로 주문 목록 조회 |
| `get_order` | 라인 아이템, 결제, 출고 포함 주문 상세 조회 |
| `confirm_order` | 대기 중인 주문 확인 |
| `cancel_order` | 사유와 함께 주문 취소 |

### 고객

| 도구 | 설명 |
| - | - |
| `list_customers` | 이름 또는 이메일로 고객 검색 |
| `get_customer` | ID로 고객 조회 |

### 재고

| 도구 | 설명 |
| - | - |
| `list_inventory` | 전체 변형의 재고 수준 조회 |
| `adjust_inventory` | 사유와 함께 재고 수량 조정 (+/-) |

### 할인

| 도구 | 설명 |
| - | - |
| `list_discounts` | 전체 할인 코드/프로모션 조회 |
| `create_discount` | 할인 생성 (정액, 정률, 무료배송) |

### 출고

| 도구 | 설명 |
| - | - |
| `create_fulfillment` | 추적 정보 포함 주문 출고 생성 |
| `update_fulfillment` | 추적 정보 수정 |
| `ship_fulfillment` | 출고를 배송됨으로 표시 |
| `deliver_fulfillment` | 출고를 배달됨으로 표시 |

### 카테고리

| 도구 | 설명 |
| - | - |
| `list_categories` | 전체 카테고리 조회 |
| `create_category` | 새 카테고리 생성 |
| `update_category` | 카테고리 수정 |
| `delete_category` | 카테고리 삭제 |

### 컬렉션

| 도구 | 설명 |
| - | - |
| `list_collections` | 전체 컬렉션 조회 |
| `create_collection` | 컬렉션 생성 (수동 또는 자동) |
| `update_collection` | 컬렉션 수정 |
| `delete_collection` | 컬렉션 삭제 |

### 장바구니 & 체크아웃

| 도구 | 설명 |
| - | - |
| `create_cart` | 새 장바구니 생성 |
| `get_cart` | 아이템과 합계 포함 장바구니 조회 |
| `add_cart_item` | 장바구니에 상품 변형 추가 |
| `update_cart_item` | 장바구니 아이템 수량 수정 |
| `remove_cart_item` | 장바구니에서 아이템 제거 |
| `apply_cart_discount` | 장바구니에 할인 코드 적용 |
| `checkout_cart` | 장바구니를 체크아웃하여 주문 생성 |

### 결제

| 도구 | 설명 |
| - | - |
| `create_payment` | 주문에 수동 결제 기록 |
| `complete_payment` | 결제를 완료됨으로 표시 |

### 반품

| 도구 | 설명 |
| - | - |
| `list_returns` | 전체 반품 조회 |
| `get_return` | 반품 상세 조회 |
| `create_return` | 주문에 대한 반품 요청 생성 |
| `approve_return` | 반품 승인 |
| `reject_return` | 반품 거절 |
| `receive_return` | 반품 상품 수령 확인 |
| `complete_return` | 반품 완료 |

### 환불

| 도구 | 설명 |
| - | - |
| `create_refund` | 주문에 대한 환불 생성 |

### 리전

| 도구 | 설명 |
| - | - |
| `list_regions` | 전체 리전 조회 |
| `create_region` | 통화 및 세금 포함 리전 생성 |
| `update_region` | 리전 수정 |
| `delete_region` | 리전 삭제 |
| `upsert_region_price` | 변형에 리전별 가격 설정 |

### 배송 방법

| 도구 | 설명 |
| - | - |
| `list_shipping_methods` | 전체 배송 방법 조회 |
| `create_shipping_method` | 배송 방법 생성 |
| `update_shipping_method` | 배송 방법 수정 |

### 웹훅

| 도구 | 설명 |
| - | - |
| `list_webhooks` | 웹훅 구독 조회 |
| `create_webhook` | 웹훅 구독 생성 |
| `test_webhook` | 웹훅에 테스트 이벤트 전송 |

### 스토어

| 도구 | 설명 |
| - | - |
| `get_store` | 스토어 설정 및 구성 조회 |
| `update_store` | 스토어명, 통화, 메타데이터 수정 |

### 대시보드

| 도구 | 설명 |
| - | - |
| `get_dashboard_stats` | 매출, 주문, 고객, 최근 활동 조회 |

## 리소스

| 리소스 | URI | 설명 |
| - | - | - |
| API 레퍼런스 | `openapi://spec` | 내장 OpenAPI 스펙 — AI 에이전트가 자동으로 읽어 전체 API를 파악 |

## 예시 프롬프트

설정 후 AI 에이전트에게 이렇게 물어보세요:

* "오늘 주문 전부 보여줘"
* "'무선 이어폰' 상품 49,900원에 만들어줘"
* "베스트셀러 상품들 재고 얼마나 남았어?"
* "주문 ord\_abc123 취소해줘 — 고객이 환불 요청했어"
* "최근 30일 대시보드 요약 보여줘"
* "활성화된 할인 코드 전부 알려줘"

## 문제 해결

### 클라우드 엔드포인트 사용 시 "Unauthorized" (401)

* 헤더가 `Authorization: Bearer <토큰>` 형식인지 확인 (`Bearer` 접두사 포함)
* API 키의 경우: 키가 `sk_`로 시작하는지 확인 (`pk_`가 아님), 대시보드 > 설정 > API 키에서 활성 상태 확인
* OAuth 토큰의 경우: 액세스 토큰이 만료되지 않았는지 확인 (1시간 수명) — 리프레시 토큰으로 갱신

### OAuth 사용 시 "Insufficient scope"

* OAuth 토큰에 요청한 도구에 필요한 스코프가 없습니다
* 인가 시 부여된 스코프를 확인하세요
* 더 넓은 `scope` 파라미터로 재인가하여 추가 스코프를 요청하세요

### "HEADLESS\_COMMERCE\_API\_KEY environment variable is required"

로컬 (stdio) 서버에 해당합니다. API 키가 없으면 서버가 즉시 종료됩니다. MCP 설정의 `env` 블록에 키가 설정되어 있는지 확인하세요.

### "Invalid API key" 또는 "Secret key required for Admin API"

* 키가 `sk_`로 시작하는지 확인 (`pk_`가 아님)
* 대시보드 > 설정 > API 키에서 키가 활성 상태인지 확인

### 도구가 빈 결과를 반환

* API 서버가 설정된 URL에서 실행 중이고 접근 가능한지 확인
* 로컬 개발 시 `HEADLESS_COMMERCE_API_URL`이 `http://localhost:3010/v1`로 설정되어 있는지 확인
* 스토어에 데이터(상품, 주문 등)가 있는지 확인

### Claude Desktop에 서버가 표시되지 않음

* 설정 파일 수정 후 Claude Desktop을 재시작
* JSON이 유효한지 확인 (후행 쉼표, 올바른 중첩)
* `~/Library/Logs/Claude/mcp*.log`에서 오류 메시지 확인


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.