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 키 발급

Headless Commerce 대시보드에 로그인
설정 > API 키로 이동
API 키 생성 클릭 후 Secret 타입 선택 (sk_ 접두사)
생성된 키를 복사 — 한 번만 표시됩니다

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

설정

클라우드 (권장)

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

Claude Desktop

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

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

Claude Code

claude mcp add headless-commerce \
  --transport http \
  --url https://mcp.headlesscommerce.io/mcp \
  --header "Authorization: Bearer sk_live_your_api_key"

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

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

Cursor

.cursor/mcp.json에 추가:

{
  "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 클라이언트는 자동으로 인증 설정을 검색합니다:

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

인가 플로우:

클라이언트 등록    POST /oauth/register
사용자 인가       GET  /oauth/authorize?response_type=code&code_challenge=...&scope=...
코드 교환         POST /oauth/token  (grant_type=authorization_code)
토큰 사용         Authorization: Bearer <access_token>
토큰 갱신         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`	대시보드 분석 조회

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

토큰 수명:

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

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

로컬 (stdio)

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

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에 추가:

{
  "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에 추가:

{
  "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에 추가:

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

로컬 개발

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

{
  "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에서 오류 메시지 확인

​MCP 서버

​연결 방식

​인증

​API 키 발급

​설정

​클라우드 (권장)

​Claude Desktop

​Claude Code

​Cursor

​OAuth 2.0 (서드파티 앱용)

​로컬 (stdio)

​환경 변수

​Claude Desktop

​Claude Code

​Cursor

​로컬 개발

​사용 가능한 도구

​상품

​변형

​주문

​고객

​재고

​할인

​출고

​카테고리

​컬렉션

​장바구니 & 체크아웃

​결제

​반품

​환불

​리전

​배송 방법

​웹훅

​스토어

​대시보드

​리소스

​예시 프롬프트

​문제 해결

​클라우드 엔드포인트 사용 시 “Unauthorized” (401)

​OAuth 사용 시 “Insufficient scope”

​”HEADLESS_COMMERCE_API_KEY environment variable is required”

​”Invalid API key” 또는 “Secret key required for Admin API”

​도구가 빈 결과를 반환

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

MCP 서버

연결 방식

인증

API 키 발급

설정

클라우드 (권장)

Claude Desktop

Claude Code

Cursor

OAuth 2.0 (서드파티 앱용)

로컬 (stdio)

환경 변수

Claude Desktop

Claude Code

Cursor

로컬 개발

사용 가능한 도구

상품

변형

주문

고객

재고

할인

출고

카테고리

컬렉션

장바구니 & 체크아웃

결제

반품

환불

리전

배송 방법

웹훅

스토어

대시보드

리소스

예시 프롬프트

문제 해결

클라우드 엔드포인트 사용 시 “Unauthorized” (401)

OAuth 사용 시 “Insufficient scope”

”HEADLESS_COMMERCE_API_KEY environment variable is required”

”Invalid API key” 또는 “Secret key required for Admin API”

도구가 빈 결과를 반환

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