카페24 MCP 서버 완전 분석
— 실측으로 확인한 프로토콜·도구·함정

카페24가 2026년 공개한 MCP(Model Context Protocol) 서버는 AI 에이전트가 쇼핑몰의 상품 검색·주문을 직접 다룰 수 있게 해주는 인터페이스입니다. 그런데 공식 문서만으로는 핸드셰이크 절차나 인증 방식이 명확하지 않습니다. 리더마인 AI 랩이 운영 중인 카페24 몰을 대상으로 직접 프로토콜을 호출해 검증한 내용을 정리합니다. 문서에 없는 도구, 실제 응답 스키마, 구현 시 함정까지 — 전부 실측 기준입니다.

서버 종류와 엔드포인트

통신은 JSON-RPC 2.0 + Streamable HTTP transport입니다. Accept: text/event-stream을 보내도 실제 응답은 일반 JSON으로 옵니다(SSE 파싱 불필요 — 실측 확인).

핸드셰이크: 세션이 전부다

세션 없이 tools/list를 호출하면 400 {"error":"Session ID required"}가 돌아옵니다. 반드시 initialize부터:

curl -sS -i -X POST "https://{mall_id}.cafe24api.com/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0", "id":1, "method":"initialize",
    "params":{
      "protocolVersion":"2025-06-18",
      "capabilities":{},
      "clientInfo":{"name":"my-client","version":"0.1"}
    }
  }'

응답 헤더에 세션이 실려 옵니다: mcp-session-id: (64자리 hex). 이후 모든 요청에 Mcp-Session-Id 헤더로 넣으면 됩니다.

사용 가능한 도구 — 문서에 없는 것까지

인증 불필요 (실측 확인)

• search-products — 상품 검색. product_name(필수), product_tag(상황·용도 태그), 가격 범위, 정렬, limit. 응답에 variants_simple[](옵션·재고 포함)이 이미 들어있어 단일 옵션 상품은 상세조회가 필요 없습니다.
• search-products-detail — 상품번호 단건 상세. 필드 구조는 검색 응답과 동일.
• create-checkout-url — 상품+옵션+수량으로 즉시결제 URL 생성. 카페24 주문서 페이지로 상품 정보가 쿼리스트링에 담겨 넘어갑니다. 에이전트 커머스(AI가 장바구니까지 만들어주는 쇼핑)의 핵심 조각.

문서에 없던 도구 (별도 액세스 토큰 필요)

• search-customer-orders — 고객 주문 내역 검색
• search-customer-order-detail — 주문 단건 상세
• cancel-unpaid-order — 입금 전 주문 취소 (destructiveHint: true 마킹)

이 도구들의 존재는 카페24가 "로그인한 고객 본인 컨텍스트에서 주문 조회·취소까지 하는 챗봇" 시나리오를 설계에 넣어뒀다는 뜻입니다. 에이전트 커머스의 다음 단계가 이미 준비돼 있는 셈입니다.

응답 파싱의 함정

{
  "jsonrpc": "2.0", "id": 3,
  "result": {
    "content": [{"type":"text","text":"(JSON을 문자열로 이중 인코딩)"}],
    "isError": false,
    "structuredContent": { "products": [ /* 이미 파싱된 JSON */ ] }
  }
}

• result.content[0].text는 이중 인코딩된 참고용 — 파싱하지 마세요. result.structuredContent를 바로 쓰면 됩니다.
• 실패 패턴이 둘입니다: 최상위 error 필드로 오거나, 200인데 result.isError: true로 오거나. 둘 다 체크해야 합니다.
• envelope 키는 camelCase, 그 안의 카페24 상품 데이터(product_no, list_image)는 snake_case — 레이어마다 네이밍이 달라서 하나의 직렬화 전략으로 한 번에 매핑하면 깨집니다. envelope 파싱과 도메인 파싱을 2단계로 분리하세요.

운영 시 알아둘 제약

• 세션 TTL 미공개 — 수 분 내 재사용은 문제없었지만 만료 정책이 문서화돼 있지 않습니다. 저빈도 호출이라면 매번 initialize로 재발급하는 게 안전합니다.
• tools/list 결과는 배포 버전에 따라 달라질 수 있습니다. 매번 조회하기보다 사용할 도구 이름을 코드에 명시하는 편이 안정적입니다.
• MCP와 카페24 Admin REST API(/api/v2/admin/*)는 완전히 다른 체계입니다. MCP는 세션 기반·공개 도구는 무인증, Admin API는 OAuth Bearer. 같은 몰이라도 섞어 쓰지 마세요.
• "추천"은 product_tag 키워드 매칭 수준 — 구매이력 기반 개인화는 없습니다. 개인화가 필요하면 RAG 등 자체 레이어를 얹어야 합니다.

정리 — 이걸로 뭘 만들 수 있나

카페24 MCP는 "AI가 쇼핑몰을 다루는 표준 창구"입니다. 검색 → 옵션 확인 → 결제 URL 생성까지 무인증 3개 도구만으로 대화형 쇼핑 에이전트의 뼈대가 나옵니다. 리더마인 AI 랩은 이 프로토콜 위에 RAG 검색과 운영 자동화를 얹는 프로토타입을 가동 중입니다.