스토어프론트 만들기 (MCP)

sayren MCP를 코딩 도구에 붙이면, 프롬프트 한 번으로 내 스토어에 연결된 쇼핑몰 화면을 만들 수 있어요. 같은 연결로 "등록된 상품 몇 개야?"처럼 대화로 스토어를 조회하고 운영할 수도 있어요. 만들어지는 앱은 React Router 기반이고 서버에서 먼저 그려요(SSR). 홈, 목록·검색, 상세, 장바구니, 주문서·결제, 주문 내역까지 구매 흐름 전체가 들어 있어요.

왜 MCP인가

에이전트가 API 문서만 읽고 코드를 새로 지으면 매번 결과가 다르고, 결제처럼 규칙이 많은 곳에서 조용히 깨져요. MCP는 다르게 동작해요.

• 검증된 템플릿을 그대로 내려줘요. 이 템플릿은 우리 저장소에 있는 실제로 도는 앱이고, CI가 매번 빌드·테스트해요. API가 바뀌면 템플릿이 먼저 깨지고, 깨진 코드가 나가지 않아요.
• 스토어의 사실을 알려줘요. 카테고리와 상품을 지어내지 않고 실제 값으로 화면을 맞춰요.
• 만든 결과를 검사해요. 결제가 조용히 실패하는 실수를 규칙으로 잡아요.

1. 토큰 발급

셀러 콘솔 개발자 › API 토큰에서 토큰을 발급해요. 쇼핑몰 화면을 만들고 스토어를 조회하는 데는 읽기 스코프(store:r, product:r, category:r, order:r 등)면 충분해요. 방문 분석을 물어보려면 analytics:r을 더해요. 대화로 상품을 고치는 것처럼 데이터를 바꾸게 하려면 해당 리소스의 쓰기 스코프(예: product:rw)를 더해요. 에이전트는 토큰에 있는 스코프 안에서만 움직이므로, 필요한 만큼만 주는 편이 안전해요. 토큰은 발급 직후 한 번만 보이니 바로 복사해요.

토큰은 스토어 정보를 읽을 수 있어요. 설정 파일을 저장소에 올리지 말고, 쓰지 않게 되면 API 토큰 화면에서 폐기해주세요.

2. MCP 연결

셀러 콘솔 개발자 › 스토어프론트 만들기에서 설정을 복사하거나, 아래 내용을 쓰는 도구의 설정 파일에 넣어요.

Claude Code·Cursor 같은 도구는 JSON을 써요.

{
  "mcpServers": {
    "sayren": {
      "command": "npx",
      "args": ["-y", "@sayren/mcp"],
      "env": {
        "SAYREN_TOKEN": "발급한 API 토큰",
        "SAYREN_API_ORIGIN": "https://api.sayren.app"
      }
    }
  }
}

Codex는 TOML을 써요.

[mcp_servers.sayren]
command = "npx"
args = ["-y", "@sayren/mcp"]
env = { SAYREN_TOKEN = "발급한 API 토큰", SAYREN_API_ORIGIN = "https://api.sayren.app" }

설정을 저장하고 도구를 다시 시작하면 sayren 서버가 붙어요.

3. 프롬프트 실행

터미널이 있다면 템플릿은 한 줄로도 받을 수 있어요. SAYREN_TOKEN을 함께 주면 .env까지 채워요.

SAYREN_TOKEN=발급한_API_토큰 npx -y @sayren/mcp create my-shop

코딩 도구에서 만들 때는 아래 프롬프트를 쓰면 돼요.

sayren MCP로 내 쇼핑몰 화면(스토어프론트)을 만들어줘.

1. get_store_context로 내 스토어 정보를 확인해줘.
2. get_scaffold_plan으로 만드는 순서와 규칙을 받아줘.
3. list_template_files와 get_template_file로 템플릿 파일을 받아서 그대로 프로젝트에 써줘.
   코드를 새로 짓지 말고 받은 내용을 그대로 써줘.
4. 계획이 알려 준 환경변수로 .env를 만들고 개발 서버를 띄워서 홈에 상품이 보이는지 확인해줘.
5. verify_storefront로 규칙 위반이 없는지 검사하고, 나오면 고쳐줘.

디자인은 확장 지점(브랜드 색·서체, 헤더, 상품 카드)에서만 바꿔줘. 결제 관련 파일은 그대로 둬.

디자인 방향이 있으면 마지막 줄에 덧붙여요. 예를 들어 "브랜드 색은 남색이고 서체는 고딕으로 해줘"처럼요.

대화로 스토어 운영하기

연결한 도구에 평소처럼 물어보면 돼요.

등록된 상품 몇 개야?
오늘 들어온 주문 중 아직 발송 안 한 것 보여줘.
어제 올린 티셔츠 할인율을 20%로 바꿔줘.

에이전트는 관리 API 목록(list_operations)에서 알맞은 API를 찾고, 파라미터와 응답 형태를 확인한 뒤 (describe_operation) 호출해요. 관리 API 전체가 이 네 도구로 열리므로 API가 늘어도 설정을 바꿀 필요가 없어요.

• 조회(call_api_read)와 변경(call_api_write)은 도구가 나뉘어 있어요. 코딩 도구에서 조회만 자동 허용하고 변경은 매번 확인받도록 설정할 수 있어요.
• 환불로 이어지는 작업(셀러 직권취소, 클레임 승인)은 되돌릴 수 없어서 MCP로는 할 수 없어요. 셀러 콘솔에서 처리해요.
• 결제 설정, API 토큰·앱 관리, API 로그처럼 셀러 콘솔 로그인이 필요한 API는 목록에 나오지 않아요.
• 변경 요청은 재시도해도 한 번만 적용되도록 멱등키를 함께 보내요.

방문 분석 물어보기

스토어프런트에 방문 분석을 연결했다면 방문·유입·전환도 대화로 물어볼 수 있어요. 토큰에 analytics:r 스코프가 있어야 해요. 콘솔 로그인에서는 OWNER·ADMIN이 이 스코프를 가지고, API 토큰을 발급할 때 권한 표에서 방문 분석 읽기를 골라요.

이번 주 방문자랑 구매 전환율 알려줘. 지난주보다 늘었어?
지난 30일 동안 어디서 들어온 손님이 가장 많이 샀어?
조회는 많은데 장바구니에 잘 안 담기는 상품 찾아줘.
인스타그램 광고 캠페인 성과 어때?

에이전트는 개요(/analytics/overview), 상품(/analytics/products), 유입(/analytics/sources) 조회를 골라 불러요.

• 숫자는 10분마다 집계돼요. 응답의 lastComputedAt이 마지막 집계 시각이에요.
• 한 번에 최대 92일까지 조회해요. 날짜는 한국 시간 기준이에요.
• 테스트 결제(샌드박스)로 만든 구매는 기본으로 빠져요. "테스트 결제도 포함해서"라고 말하면 포함해요.
• 토큰에 스코프가 없으면 403 INSUFFICIENT_ROLE이 나요. 에이전트가 스코프가 부족하다고 알려 줘요.

도구

만들어지는 앱

환경변수는 두 개예요.

만든 뒤에는 이렇게 띄워요.

pnpm install
pnpm dev

바꿔도 되는 곳, 두는 곳

디자인은 확장 지점에서 바꿔요.

결제와 연결에 관한 파일은 그대로 두는 편이 좋아요. 아래 규칙을 하나라도 어기면 결제가 조용히 실패해요. verify_storefront가 검사하는 것도 이 규칙들이에요.

만든 뒤 확인

1. 개발 서버를 띄워 홈에 상품이 보이는지 봐요. 서버에서 먼저 그리므로 자바스크립트를 꺼도 상품이 보여야 해요.
2. 상품을 장바구니에 담고 주문서까지 가봐요.
3. 테스트 결제로 주문을 한 번 만들어 봐요. 결제 설정이 샌드박스면 실제로 돈이 오가지 않아요.
4. 셀러 콘솔 분석 › 결제 내역에서 그 결제가 보이는지 확인해요.

잘 안될 때

다음 단계