MCP 연결
AI 에이전트를 원격 MCP 서버로 쇼핑몰에 연결합니다.
업데이트됨 10.20 — 회원 목록의 개인정보 가림은 쇼핑몰 보안 설정의 마스킹을 따릅니다연결 주소
Mall Story 는 원격 MCP 서버(Streamable HTTP)를 엽니다. 커넥터에는 주소 한 줄만 넣습니다.
text
https://api.mallstory.kr/mcp- 어느 쇼핑몰인지는 연결할 때 동의 화면에서 정합니다 — 쇼핑몰 아이디와 소유자 계정으로 로그인한 그 쇼핑몰입니다.
- 쇼핑몰을 주소에 박아 두려면
https://api.mallstory.kr/mcp/{shop_id}도 됩니다. 이때 동의 화면의 쇼핑몰 아이디 칸은 그 아이디로 정해져 나오지 않습니다. - 쇼핑몰이 여러 개면 커넥터를 쇼핑몰마다 하나씩 추가합니다.
- HTTPS 만 받습니다. stdio 방식은 지원하지 않습니다.
AI 에이전트에 연결하기
- 1커넥터 추가AI 에이전트(MCP 클라이언트)의 원격 MCP 서버 · 커넥터 추가 설정에서
https://api.mallstory.kr/mcp을 붙여넣습니다. Client ID · 비밀 키는 넣지 않습니다 — 클라이언트가 동적 등록으로 스스로 만듭니다. - 2로그인연결을 누르면 로그인 화면이 열립니다. 쇼핑몰 아이디와 쇼핑몰 소유자 통합 계정 아이디 · 비밀번호를 넣습니다.
- 3승인에이전트가 요청한 권한을 보고 [승인] 합니다. 한 번 승인한 권한은 다시 묻지 않습니다.
- 4대화로 사용“쇼핑몰 정보 보여 줘”, “최근 가입한 회원 10명 보여 줘” 처럼 요청합니다.
연결을 끊으려면
쇼핑몰 관리자 > 설정 > 외부연동 설정 > 앱 관리 > 연결된 앱에 그 에이전트(클라이언트가 등록한 이름)가 보입니다. 거기서 해지하면 바로 끊깁니다.
인가 서버 찾기
커넥터는 다음 순서로 인가 서버를 찾습니다. 직접 MCP 클라이언트를 만든다면 같은 순서를 따르세요.
- 1MCP 요청 → 401응답의
WWW-Authenticate에서resource_metadata주소를 읽습니다. - 2보호 리소스 메타데이터
GET https://api.mallstory.kr/.well-known/oauth-protected-resource/mcp - 3인가 서버 메타데이터
GET https://api.mallstory.kr/.well-known/oauth-authorization-server - 4동적 등록 (RFC 7591)
POST https://api.mallstory.kr/api/oauth/register—client_name·redirect_uris·token_endpoint_auth_method(none이면 비밀 키 없이 PKCE). 쇼핑몰 관리 권한만 받습니다. - 5인가 → 토큰소유자 동의와 같습니다.
resource를https://api.mallstory.kr/mcp/{shop_id}로 보내면 그 쇼핑몰로 정해집니다.scope를 비우면 등록한 권한 전부를 요청한 것으로 봅니다.
등록만으로는 아무것도 열리지 않습니다
동적 등록은 누구나 할 수 있지만, 쇼핑몰 소유자가 로그인해 승인해야 토큰이 나옵니다. 한 IP 에서 한 시간에 20번까지 등록할 수 있습니다. 등록만 하고 7일 안에 한 번도 승인되지 않은 앱은 지워집니다 — 커넥터가 다시 연결할 때 새로 등록합니다.
도구
REST 관리자 API 와 같은 동작을 도구로 엽니다(같은 검사 · 같은 기록). 토큰에 없는 권한의 도구는 목록(tools/list)에 나타나지 않습니다. 되돌릴 수 없는 도구에는 destructiveHint 가 붙어 클라이언트가 실행 전에 확인을 받습니다. 필드는 REST 문서와 같은 이름(snake_case)입니다.
| 도구 | 스코프 | 성격 |
|---|---|---|
get_shop | shop:read | 조회 — 쇼핑몰 · 판매자 정보 |
update_shop | shop:write | 보낸 필드만 고침 — 같은 값으로 다시 불러도 안전 |
list_products · get_product | products:read | 조회 — 원가는 get_product 에만 |
create_product · update_product | products:write | update 는 보낸 필드만 · expected_updated 로 덮어쓰기 방지 |
copy_product | products:write | 상품 복사 — 부를 때마다 하나씩 생김(멱등하지 않음) |
delete_product | products:write | 되돌릴 수 없음 |
upload_images | products:write | 이미지 올리기 → file_id. 로컬 파일의 base64(images) 또는 공개 주소(image_urls), 합쳐 10장. 아이콘은 variant: "icon"(한 장 · SVG 도) |
bulk_products | products:write | 상품 일괄 처리 — 1,000개까지, action=delete 는 되돌릴 수 없음 |
list_categories | products:read | 조회 — 트리를 한 줄 목록으로 |
create_category · update_category · move_category | products:write | 바뀐 뒤의 전체 목록을 돌려줌 |
delete_category | products:write | 하위까지 지움 · 되돌릴 수 없음 |
list_badges · get_badge | products:read | 상품 배지 조회 |
create_badge · update_badge · delete_badge | products:write | update 는 보낸 필드만 · delete 는 상품의 badge_ids 에서도 뺌 |
list_icons · get_icon | products:read | 상품 아이콘 조회 |
create_icon · update_icon · delete_icon | products:write | update 는 보낸 필드만 · delete 는 상품의 icon_id 를 비움 |
list_templates · get_template | products:read | 템플릿 관리 — kind: common · delivery · colors · sizes · reviews |
create_template · update_template · delete_template | products:write | data 에 REST 본문 그대로 · update 는 보낸 필드만 |
list_surcharges · search_surcharge_base · search_surcharge_roads | products:read | 배송 할증지역 조회 · 등록할 도로 찾기 |
create_surcharge · update_surcharge · delete_surcharge · set_surcharge_base_excluded | products:write | 이 쇼핑몰 지역 더하기 · 고치기 · 지우기 · 기본 지역 빼기 |
list_members · get_member | customers:read | 조회 — 개인정보 열람 기록에 남음 |
update_member | customers:write | 보낸 필드만 고침 |
list_levels | customers:read | 회원 등급 조회 — member_count 포함 |
create_level · update_level · delete_level | customers:write | update 는 보낸 필드만(할인 · 적립은 안의 키까지) |
get_member_points | customers:read | 회원 적립금 잔액 · 내역 |
change_member_points | customers:write | 지급 · 차감 — 다시 부르면 또 처리됨 |
list_coupons · get_coupon · list_coupon_issues · list_coupon_serials | promotions:read | 쿠폰 조회 — 번호는 앞 200개만(전부는 REST) |
create_coupon · update_coupon · delete_coupon | promotions:write | update 는 보낸 필드만 · 고르는 값이 틀리면 거절 |
create_coupon_serials | promotions:write | 되돌릴 수 없음 — 만든 번호는 지우지 않음 |
list_orders · get_order · ship_order · create_cancel · create_refund준비 중 | orders:read · write | 주문 · 클레임 — 쇼핑몰 관리자에 주문 메뉴가 열리면 함께 엽니다 |
이미지 올리기 — Claude Code 에서 로컬 파일 그대로
upload_images 는 파일 바이트의 base64 를 받습니다. Claude Code · Claude Desktop(Code 모드)처럼 로컬 파일을 읽을 수 있는 에이전트에게 "./상품.png 를 올려서 상품 대표 이미지로 넣어 줘" 라고 하면 파일을 읽어 넣습니다 — 토큰을 꺼내거나 curl 로 올릴 필요가 없습니다(커넥터가 인증). 채팅에 끌어다 놓은 첨부는 바이트가 없어 거절되니 공개 주소(image_urls)를 쓰세요. 서버는 내부망 주소 · 80 · 443 밖의 포트를 열지 않고, 형식은 파일 앞 바이트로 판단합니다. 큰 파일(수 MB)은 이미지 업로드(REST)가 빠릅니다.에이전트 안전장치
목록은 기본 10건(최대 100)입니다. 적립금 지급 · 쿠폰번호 만들기처럼 다시 부르면 또 처리되는 도구는, 응답을 못 받았을 때 조회 도구로 먼저 확인하게 설명에 적어 두었습니다.