메인 콘텐츠로 건너뛰기

​
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 키 또는 OAuthNode.js 설치 필요
전송 방식Streamable HTTPstdio (JSON-RPC)
인증API 키 또는 OAuth 2.0API 키만
업데이트항상 최신수동 npm update
오프라인불가가능
적합한 경우프로덕션, 대부분의 사용자에어갭, 자체 호스팅

​
인증

클라우드 MCP 서버는 두 가지 인증 방식을 지원합니다:
방식적합한 경우스코프
API 키 (sk_)빠른 설정, 전체 관리자 접근admin (모든 권한)
OAuth 2.0서드파티 앱, 세분화된 권한리소스별 설정 가능

​
API 키 발급

  1. Headless Commerce 대시보드에 로그인
  2. 설정 > API 키로 이동
  3. API 키 생성 클릭 후 Secret 타입 선택 (sk_ 접두사)
  4. 생성된 키를 복사 — 한 번만 표시됩니다
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 클라이언트는 자동으로 인증 설정을 검색합니다:
  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대시보드 분석 조회
: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/v1API 기본 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_customerID로 고객 조회

​
재고

도구설명
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에서 오류 메시지 확인