Bootpay MCP Server

Korea's payment integration, now accessible to AI. 한국 결제 연동을 AI가 직접 수행할 수 있도록 하는 MCP 서버입니다.

🛍️ 개발자가 아니라 판매자라면 — 코드 없이 사진과 설명만으로 상품을 등록하는 방법은 사진과 설명으로 상품 올리기를 보세요.

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

"이 레포 참조해서 부트페이 결제 연동해줘" 라는 요청을 받고 이 문서를 읽고 있다면:

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

MCP가 "연결됨"이라도 전송 방식에 따라 사용 가능한 도구가 다릅니다:

전송 방식	Docs (8개)	Admin (67개)	Commerce (13개)	키 자동 조회	다음 단계
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	O	→ 아래 "stdio 모드" 참고
HTTP (`bootpay-docs-mcp.rupy1014.workers.dev/mcp`)	O	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)
MCP 없음 (저장소 참조만)	—	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)

확인 방법:

# Codex
codex mcp list # bootpay 서버가 보이는지 확인# Claude Code
claude mcp list # bootpay 서버가 보이는지 확인# Gemini CLI
gemini mcp list # bootpay 서버가 보이는지 확인

서버가 있다면 버전도 확인하세요 — 옛 버전은 낡은 답을 냅니다:

npx -y @bootpay/mcp@latest --version # 지금 실행되는 버전
npm view @bootpay/mcp version # npm 의 최신 버전

두 값이 다르면 사용자에게 최신 버전으로 다시 설치하도록 안내하세요 → Quick Start / 0단계: 설치

stdio로 연결된 경우: browser_login → list_keychains(또는 create_keychain)으로 키를 자동 조회하세요. 사용자에게 키를 직접 물어보지 마세요. HTTP 또는 MCP 없음: 사용자에게 키를 요청해야 합니다. 아래 "MCP 없이 이 저장소만 참조하는 경우" 섹션의 정확한 키 이름을 사용하세요. 서버가 목록에 없으면? MCP 설정 후 반드시 새 세션을 시작하세요. 설정만으로는 현재 세션에 반영되지 않습니다. 설정할 때는 반드시 @latest 를 붙이세요 — npx -y @bootpay/mcp@latest. 버전을 생략하면 npx 캐시에 남은 옛 사본이 실행됩니다. HTTP로 연결했는데 Admin 도구를 쓰고 싶다면? stdio(npx -y @bootpay/mcp@latest)로 재설정 후 새 세션을 시작하세요.

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

중요: 문서(search_docs)를 먼저 읽지 마세요. Admin 도구로 실제 프로젝트 컨텍스트를 먼저 수집하세요.

1. get_integration_context() → 인증/프로젝트/결제설정/위젯/키체인 한 번에 확인 ⭐
→ readiness.ready = true이면 Step 5로 이동
→ readiness.blockers가 있으면 아래 순서로 해결:
2. browser_login → Bootpay 로그인 (미인증 시)
3. browser_select_project → 프로젝트 선택 (미선택 시)
4. create_keychain(targets=["core"]) → 결제용 API 키 발급 (키체인 없을 때)
→ client_key, secret_key 반환 → .env에 즉시 저장
5. get_sdk_versions → 최신 SDK 버전 확인
6. search_docs → get_doc → 관련 문서 조회 (보완 참조)
7. 코드 작성 → .env 환경변수 참조 (키를 코드에 하드코딩 금지)

서버 인증: client_key/secret_key 기반 Basic Auth. getAccessToken() 불필요.

MCP 없이 이 저장소만 참조하는 경우

🚫 API 키를 추측하거나 임의로 생성하지 마세요.692e4c6da0ba315535c9dedf 같은 랜덤 문자열을 .env에 넣으면 100% 실패합니다. Bootpay API 키는 Bootpay 서버가 발급한 값만 유효합니다.

아래 파일을 순서대로 읽고 코드를 작성하세요:

순서	파일	내용
1	`AGENTS.md`	AI 에이전트용 지시 — 금지 행위, 금액 규칙, 통합결제창 판단
2	`SETUP_GUIDE.md`	MCP 최신 설치 · Admin CLI로 키 조회 또는 수동 설정
3	`SDK_VERSIONS.md`	최신 SDK 버전 (v2 5.x) — 3.x/4.x는 deprecated
4	`llms.txt`	핵심 규칙, API 도메인, SDK 패키지, 결제 흐름
5	`examples/`	플랫폼별 전체 코드 예제 (12개)

⚠️MCP 없이는 API 키를 AI가 자동 조회할 수 없습니다. 사용자에게 반드시 아래 안내를 하세요:
admin.bootpay.co.kr → 프로젝트 → 개발자 설정 → API 연동키(결제) 탭에서 아래 3개 키를 확인하여 .env에 입력
또는 stdio 모드로 MCP를 연결하면 list_keychains로 자동 조회 가능
이 안내 없이 키를 추측하거나, 빈 값/.env 없이 코드를 생성하면 실패합니다.

사용자에게 요청할 키 2개 (정확한 이름)

Admin UI(admin.bootpay.co.kr)에서 보이는 라벨과 .env 변수명이 다릅니다. 반드시 아래 매핑을 사용하세요:

Admin UI 라벨	.env 변수명	용도
Client Key (= REST API Key)	`BOOTPAY_CLIENT_KEY`	프론트엔드 SDK 결제창 호출 + 서버 Basic Auth 공통
Secret Key (= Private Key)	`BOOTPAY_SECRET_KEY`	서버 Basic Auth 인증 (비밀)

프론트엔드 빌드 도구에 따라 BOOTPAY_CLIENT_KEY 앞에 접두사를 붙입니다:
Vite → VITE_BOOTPAY_CLIENT_KEY
Next.js → NEXT_PUBLIC_BOOTPAY_CLIENT_KEY
Create React App → REACT_APP_BOOTPAY_CLIENT_KEY

# .env 예시 — create_keychain 또는 Admin UI에서 확인한 값을 입력
BOOTPAY_CLIENT_KEY= # Client Key (프론트엔드 SDK + 서버 Basic Auth 공통)
BOOTPAY_SECRET_KEY= # Secret Key (서버 전용, 프론트엔드 노출 금지)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

잘못된 이름	올바른 이름	비고
`BOOTPAY_REST_APP_ID`	`BOOTPAY_CLIENT_KEY`	"REST API Key"는 Admin UI 라벨일 뿐, 변수명이 아님
`BOOTPAY_PRIVATE_KEY`	`BOOTPAY_SECRET_KEY`	Bootpay에서는 "Secret Key"로 통일
`BOOTPAY_API_KEY`	`BOOTPAY_CLIENT_KEY`	존재하지 않는 변수명
`getAccessToken()`	Basic Auth	v2에서는 토큰 발급 불필요. client_key:secret_key로 직접 인증

핵심 규칙

SDK v2 (5.x) only — bootpay-3.x.x.min.js, bootpay-4.x.x.min.js는 v1(deprecated)이며 동작하지 않음
결제는 프론트엔드에서 시작 — 국내 PG 규정. 백엔드에서 결제를 시작하는 코드 금지
서버승인(분리승인)이 기본 — Bootpay.requestPayment 호출 시 extra.separately_confirmed: true 설정. confirm 시점에 receipt_id를 서버로 전달하면 서버가 confirmPayment()로 최종 승인하고 리턴값으로 금액을 확인 (별도 결제검증 조회 불필요). done 이벤트만 처리하는 클라이언트 승인 코드는 유실 위험이 있어 비권장
웹훅 보완 필수 — 클라이언트 결과 처리는 브라우저 이탈로 유실될 수 있음. 웹훅 엔드포인트를 함께 구현 (부트페이 발신 IP 223.130.82.0/24만 허용 + receiptPayment 재검증 + 멱등 처리)
API 키는 Admin CLI로 발급 → .env에 기록 — placeholder·추측값·랜덤 문자열 금지. create_keychain 또는 list_keychains 반환값만 사용
서버 인증은 Basic Auth — client_key/secret_key 기반. getAccessToken() 불필요
Secret Key는 서버 전용 — 절대 프론트엔드에 노출하지 않을 것

오프라인 · MCP 없이 사용하기

방법 1 — 최신 패키지를 파일로 받아서 설치 (사내망 등 npx 를 못 쓰는 환경)

npm pack @bootpay/mcp@latest # 최신 버전 .tgz 가 현재 폴더에 떨어집니다
npm install -g ./bootpay-mcp-*.tgz # 받은 파일로 전역 설치
bootpay-mcp --version # 설치된 버전 확인

GitHub Releases 의 고정 버전 파일을 받지 마세요. 최신 버전은 항상 npm 에 있습니다. 버전을 고정해야 한다면 npm view @bootpay/mcp versions 로 목록을 보고 @bootpay/mcp@2.1.0 처럼 명시하세요.

방법 2 — 문서만 AI 에게 전달 (npm/git 불필요, MCP 도구는 못 씀)

main.tar.gz 다운로드
AI 도구에 파일 첨부
"부트페이 결제 연동해줘"라고 요청

방법 3 — git clone (문서 참조용)

git clone https://github.com/bootpay/bootpay-mcp.git
# AGENTS.md, llms.txt, SDK_VERSIONS.md, SETUP_GUIDE.md 를 AI에게 전달

방법 2·3 은 문서만 전달합니다. Admin 도구(로그인·키 발급·코드 생성)는 stdio 로 MCP 를 붙여야 씁니다. 이 경우 AI 는 API 키를 자동 조회할 수 없으니, 아래 "MCP 없이 이 저장소만 참조하는 경우" 절을 따르세요.

About This Project

AI 코딩 도구(Claude, Cursor, Windsurf, Cline, GitHub Copilot 등)에서 Bootpay 결제·커머스를 연동할 수 있는 통합 Model Context Protocol (MCP) 서버입니다.

Docs (문서 검색·SDK 버전·트러블슈팅) + Admin (관리자 설정·PG·위젯·코드 생성) + Commerce (스토어·상품·회원) — 하나의 MCP 서버로 제공합니다.

stdio 로 붙으면 기본 75개(Docs 8 + Admin 67), Commerce 를 켜면 88개 도구가 노출됩니다. HTTP 로 붙으면 Docs 8개만 노출됩니다.

Supported PG & Payment Methods

Bootpay는 국내 주요 PG사와 간편결제를 통합 지원합니다:

PG사	코드	지원 결제
나이스페이 (NICE)	`nicepay`	카드, 계좌이체, 가상계좌, 휴대폰
토스페이먼츠 (Toss Payments)	`tosspayments`	카드, 계좌이체, 가상계좌, 휴대폰
KG이니시스 (KG Inicis)	`inicis`	카드, 계좌이체, 가상계좌, 휴대폰
NHN KCP	`kcp`	카드, 계좌이체, 가상계좌, 휴대폰
카카오페이 (Kakao Pay)	`kakao`	간편결제
네이버페이 (Naver Pay)	`naverpay`	간편결제
페이코 (PAYCO)	`payco`	간편결제
토스페이 (Toss Pay)	`tosspay`	간편결제
다날 (Danal)	`danal`	휴대폰 소액결제

결제 유형: 일반결제 (카드/계좌이체/가상계좌/휴대폰) · 정기결제 (빌링키) · 본인인증 · 에스크로 · 현금영수증

Quick Start

두 가지 연결 방식을 지원합니다:

방식	특징	추천 환경
HTTP (Streamable HTTP)	설치 불필요, 원격 서버	Cursor, Windsurf, Cline, 웹 기반
npm (stdio)	로컬 실행, Admin·Commerce 도구 사용 가능	Claude Desktop, Claude Code, Codex, Gemini CLI

0단계: 설치 — 반드시 최신 버전으로

stdio 설정에는 항상 @latest 를 붙이세요.

npx -y @bootpay/mcp@latest

⚠️@latest 를 빼면 예전에 받아둔 사본이 계속 실행됩니다.npx @bootpay/mcp 처럼 버전을 생략하면 npx 는 캐시(~/.npm/_npx/)에 남아 있는 사본을 먼저 씁니다. 한 번 받아둔 사람은 새 버전이 나와도 옛 버전을 계속 실행하게 되고, 그 사이에 고쳐진 것들이 전달되지 않습니다. 실제로 최근 릴리스에서 문서 검색이 조용히 빈 결과를 내던 문제 · 낡은 SDK 버전표 · 일부 도구가 인자를 거절하던 문제가 고쳐졌습니다. 옛 버전을 쓰면 AI 가 그 낡은 정보로 코드를 만듭니다.

지금 무엇이 실행되는지 확인하세요:

npm view @bootpay/mcp version # npm 에 올라온 최신 버전
npx -y @bootpay/mcp@latest --version # 실행될 서버의 버전 (v2.1.1 이상)

--version 은 v2.1.1부터 지원합니다. 그보다 낮은 버전이면 이 명령이 서버를 띄운 채 멈춥니다. 그럴 때는 Ctrl+C 로 끄고 — 그것 자체가 옛 버전이라는 신호이므로 — 아래 캐시 비우기를 바로 실행하세요.

두 값이 같으면 최신입니다. 다르면 캐시를 비우고 다시 받으세요:

npx clear-npx-cache # npx 캐시 비우기
rm -rf ~/.npm/_npx # 위 명령이 안 되면 (macOS/Linux)

Windows PowerShell:

Remove-Item-Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

항상 같은 버전을 고정해서 쓰고 싶다면 전역 설치도 됩니다. 대신 업데이트는 직접 해야 합니다:

npm install -g @bootpay/mcp@latest # 설치 · 업데이트 모두 이 명령
bootpay-mcp --version # 설치된 버전 확인

이 경우 MCP 설정의 command 는 npx 대신 bootpay-mcp 를 쓰고 args 는 비웁니다.

전제조건 — Node.js 18 이상

node -v # v18.0.0 이상이어야 합니다

node 명령이 없다면 https://nodejs.org 에서 LTS 를 먼저 설치하고, 터미널을 새로 여세요 (PATH 반영). Windows 는 설치 후 PowerShell 을 새로 열어야 node 가 잡힙니다.

설정을 저장한 뒤에는 AI 클라이언트를 완전히 종료하고 다시 켜세요. 설정 파일만 고치면 현재 세션에는 반영되지 않습니다. 도구 목록에 부트페이 도구가 안 보이면 대부분 이것 때문입니다. 확인: claude mcp list / codex mcp list / gemini mcp list

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows):

npm (stdio) — 추천:

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP (원격):

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["mcp-remote", "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"]
}
}
}

Claude Code (CLI)

# npm (stdio)
claude mcp add bootpay-docs -- npx -y @bootpay/mcp@latest
# HTTP
claude mcp add bootpay-docs --transport http https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

Cursor

Settings → MCP Servers → Add:

{
"bootpay-docs": {
"url": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}

Codex (OpenAI)

~/.codex/config.toml:

stdio (권장, 전체 도구):

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]

HTTP (Docs 도구만, 설치 불필요):

[mcp_servers.bootpay]
url = "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"

Commerce 도구 활성화:

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]
[mcp_servers.bootpay.env]
BOOTPAY_COMMERCE_CLIENT_KEY = "YOUR_CLIENT_KEY"BOOTPAY_COMMERCE_SECRET_KEY = "YOUR_SECRET_KEY"

또는 CLI로 추가:

codex mcp add bootpay -- npx -y @bootpay/mcp@latest

설정 후 반드시 확인:
현재 Codex 세션을 종료하고 새 세션을 시작하세요
codex mcp list로 bootpay 서버가 보이는지 확인
보이지 않으면 ~/.codex/config.toml의 [mcp_servers.bootpay] 섹션을 재확인

Gemini CLI

~/.gemini/settings.json:

stdio (권장, 전체 도구):

{
"mcpServers": {
"bootpay": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP Streaming:

{
"mcpServers": {
"bootpay": {
"httpUrl": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}
}

또는 CLI로 추가:

gemini mcp add bootpay npx -y @bootpay/mcp@latest

주의: Gemini CLI는 서버 이름에 언더스코어(_)를 사용하면 보안 정책 파싱 오류가 발생합니다. bootpay-docs ✅ / bootpay_docs ❌

Windsurf / Cline / Other MCP Clients

Streamable HTTP endpoint:

https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

What AI Can Do with This MCP

MCP를 연결하면 AI가 다음을 직접 수행합니다:

사용자: "React에서 부트페이 카드결제 연동해줘"
AI 내부 동작:
1. get_sdk_versions → 최신 SDK 버전 확인 (v2 5.x)
2. get_setup_checklist → Client Key + 환경 설정 안내
3. search_docs → get_doc → payment/request 문서 조회
4. 코드 작성 → 문서 기반, 정확한 버전 사용

Docs Tools — 8개 (HTTP + stdio)

Tool	Description
`detect_project_stack`	프로젝트 스택 판정 — 클라이언트 플랫폼·웹 프레임워크·서버 언어·실행 환경(상시/서버리스). 모노레포면 앱마다 판정하고 "서버 1회 + 클라이언트 N회" 호출 계획을 반환
`get_sdk_versions`	모든 SDK 최신 버전 조회 (Web, Android, iOS, Flutter, React Native, 서버 7개 언어)
`search_docs`	120+ 개발자 문서 검색 (12 카테고리)
`get_doc`	특정 문서 전체 마크다운 조회
`list_docs`	카테고리별 문서 목록
`get_setup_checklist`	연동 환경 설정 체크리스트 (API 키, SDK 설치, .env)
`get_troubleshooting`	문제 해결 가이드 (onboarding, sandbox, webhook, billing, subscription, error, cancel, cors, csp, open-type, mobile, widget, unified, certification)
`get_csp_allowlist`	CSP(frame-src) 허용 PG 도메인 목록 + 프레임워크별 설정 스니펫 생성
`get_cs_guide`	고객응대(CS) 매뉴얼 검색

Prompt	Description
`integration-action-plan`	결제유형 × 플랫폼별 6단계 연동 액션 플랜

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Bootpay가 처음이라면 관리자 화면 대신 AI에게 전부 맡기세요. stdio 방식(npx -y @bootpay/mcp@latest)으로 연결하면 Admin 도구 67개가 활성화됩니다.

사용자: "부트페이 결제 연동하고 싶어. 처음이야"
AI 내부 동작:
1. browser_login → 브라우저 팝업으로 로그인
2. create_seller → 셀러(가맹점) 생성 + 기본 프로젝트 자동 생성
3. browser_select_project → 프로젝트 선택
4. activate_payment_method → 나이스페이 카드결제 활성화
5. set_sandbox_mode → 테스트 모드 설정
6. create_keychain(targets=["core"]) → 결제용 API 키 발급 (client_key, secret_key)
7. search_docs + get_doc → 최신 연동 문서 참조
8. 코드 생성 → 발급한 키를 .env에 설정, 코드에서 환경변수 참조

⚠️ 키를 코드에 직접 삽입하지 마세요. 발급한 키는 반드시 .env 파일에 저장하고, 코드에서는 환경변수로 참조합니다. Secret Key는 서버 .env에만 저장하세요. secret_key는 발급 시 1회만 평문으로 표시됩니다.

HTTP 방식에서는 Admin 도구를 사용할 수 없습니다. 프로젝트 설정이 필요하면 반드시 stdio(npx @bootpay/mcp@latest)를 사용하세요.

Admin Tools — 67개 (stdio 전용)

관리자(admin.bootpay.co.kr)의 설정을 AI가 직접 조회·변경할 수 있는 도구입니다. npx -y @bootpay/mcp@latest로 실행하면 자동 활성화됩니다.

카테고리	Tools	Description
코드생성	`generate_payment_code`, `generate_commerce_code`	프리플라이트(인증·키체인·결제수단·SDK 확인) + 클라이언트/서버 코드 원스톱 생성. `payment_type`: `payment`(일반) / `billing`(빌링키) / `subscription`(구독 — 회차·배치·무료체험·해지) / `widget` / `auth`, `scheduler`: `cron` / `http_trigger`(서버리스)
컨텍스트	`get_integration_context`, `get_commerce_context`	인증·프로젝트·결제설정·위젯·키체인을 한 번에 조회 (`readiness.blockers` 반환)
인증	`login`, `browser_login`, `logout`, `list_projects`, `switch_project`, `browser_select_project`, `set_token`, `get_auth_status`	로그인, 프로젝트 전환, 토큰 설정·상태 확인
셀러	`create_seller`, `search_sellers`, `get_seller`, `update_seller`	셀러(가맹점) CRUD
상세설명 블록	`list_content_templates`, `create_content_template`, `delete_content_template`, `list_content_blocks`, `create_content_block`, `update_content_block`, `delete_content_block`, `list_content_block_products`	상세설명을 블록으로 구성. 시작 템플릿(서버 저장분 + MCP 내장 스타터)과 여러 상품이 공유하는 공용 블록 관리. `content_type=4`일 때만 블록이 저장되며, HTML(`content`)은 서버가 컴파일해 채웁니다
디지털 코드풀	`list_digital_codes`, `register_digital_codes`, `disable_digital_code`	시리얼·라이센스 번호 일괄 등록/조회/폐기. `code_distribution_mode="pool"` 상품에서 구매자마다 다른 코드를 발급할 때 사용 (한 번에 최대 5,000개)
이미지	`upload_product_images`	로컬 경로·URL·base64 → Bootpay CDN 업로드 (최대 10장, 장당 10MB)
카테고리	`list_categories`, `create_category`, `update_category`, `delete_category`, `reorder_categories`	카테고리 CRUD. `path="상의 > 티셔츠 > 반팔"`로 계층 일괄 생성, 삭제는 `confirm` 확인 게이트
부속설정	`list_subscription_settings`, `list_delivery_shippings`, `create_subscription_setting`, `create_delivery_shipping`, `list_delivery_shipping_bundles`, `get_product_form_setting`, `get_product_info_notice_forms`	상품에 연결할 구독 설정·배송정책 ID 확보. 정책이 하나도 없는 프로젝트에서는 생성까지 가능 — 배송비·주기 같은 값이 빠지면 저장 대신 `need_answer` 로 무엇을 물어야 하는지 돌려줍니다(금액을 추측해 저장하지 않습니다). 폼 설정 조회로 판매자가 끈 섹션을 건너뛰고, 상품 주요정보(상품정보제공고시)의 상품군(1~40)과 군별 입력 항목도 조회
프로젝트	`create_project`	프로젝트 생성
키체인	`list_api_scopes`, `list_keychains`, `create_keychain`, `delete_keychain`, `get_commerce_keys`	API 키 발급/조회 (source 파라미터로 커머스/결제 구분)
상품	`list_products`, `get_product`, `create_product`, `update_product`, `delete_product`, `create_test_products`	상품 CRUD. `image_paths`로 로컬 사진 경로를 주면 업로드까지 처리, 구독(`subscription_setting_id`)·배송정책(`delivery_shipping_id`) 연결, 상세설명 블록(`content_blocks`), 디지털 지급(`digital_provisioning_type`), 환불정책 노출(`refund_policy_expose_type`) 지원
결제설정	`get_payment_settings`, `activate_payment_method`, `set_sandbox_mode`, `update_payment_resource`, `set_payment_mode`, `browser_select_payment_method`	PG·결제수단 설정
위젯	`list_widgets`, `get_widget`, `create_widget`, `get_widget_default_styles`, `configure_widget`, `update_widget`, `delete_widget`	결제위젯 CRUD
쇼핑몰설정	`get_mall_setting`, `update_mall_setting`	커머스 몰 기본 설정 조회·변경

상품·상세설명 블록·디지털 코드풀·카테고리·이미지 도구는 원격(OAuth) 프로파일에도 포함됩니다. 결제설정·키체인·자격증명 도구는 원격에서 제외됩니다 — 근거와 현재 상태는 원격 커넥터 문서를 보세요.

Commerce Tools — 13개 (stdio 전용, opt-in)

AI 에이전트가 커머스 API를 호출하여 쇼핑몰 기능을 구현할 수 있는 도구입니다. 활성화: 환경변수 BOOTPAY_COMMERCE_ENABLED=true 설정 후 실행.

카테고리	Tools	Description
인증	`set_commerce_credentials`	clientKey/secretKey 설정·검증
스토어	`commerce_get_store`, `commerce_get_store_detail`	가맹점 정보 조회
상품	`commerce_get_products`, `commerce_get_product`, `commerce_create_product`, `commerce_update_product`	상품 CRUD
회원	`commerce_login`, `commerce_get_session`, `commerce_logout`	회원 로그인·세션 관리
리뷰	`commerce_get_reviews`, `commerce_get_review_stats`	리뷰 조회·통계
상태	`commerce_status`	Commerce API 상태 확인

Supported Platforms & SDKs

Client SDKs

Platform	Package
Web (NPM)	`@bootpay/client-js`
Web (CDN)	`bootpay-{version}.min.js`
Android (Kotlin/Java)	`kr.co.bootpay:android`
iOS (Swift/ObjC)	`pod 'Bootpay'`
Flutter	`bootpay_flutter`
React Native	`react-native-bootpay-api`

Server SDKs

Language	Package
Node.js	`@bootpay/backend-js`
Python	`bootpay-backend`
Java / Kotlin	`kr.co.bootpay:backend`
Ruby	`bootpay`
Go	`github.com/bootpay/backend-go/v2`
.NET (C#)	`Bootpay`
PHP	`bootpay/backend-php`

Documentation Categories

Category	Content
`payment`	일반결제 — SDK 설치, 결제창, 서버 검증, 취소/환불
`billing`	정기결제 — 빌링키 발급, 자동결제, 예약결제, 해지
`subscription`	구독관리 — 플랜 생성, 갱신, 해지, 과금
`order`	주문관리 — 주문 생성, 취소, 반품
`customer`	고객관리 — 고객 등록, 그룹, 조회
`product`	상품관리 — 상품 CRUD, 옵션, 카테고리
`webhook`	웹훅 — 설정, 이벤트, 처리, 재시도 정책
`guide`	시작하기 — 키 발급, 환경설정, 개요
`integration`	연동 — 에러코드, 마이그레이션, 호환성
`invoice`	링크페이 — 결제 링크 생성, 알림
`recipes`	레시피 — 업종별 연동 시나리오
`architecture`	아키텍처 — 결제 플로우, 데이터 모델

Ask AI

MCP를 연결한 후 AI에게 이렇게 물어보세요:

부트페이 결제 연동 어떻게 해?
React에서 카드결제 연동하는 전체 코드 알려줘
Flutter에서 정기결제(빌링키) 발급 방법 알려줘
기존 프로젝트에 월 구독결제 붙여줘 (매일 배치로 결제, 같은 달 두 번 결제 방지, 성공 시에만 다음 달 이용 개방)
Next.js에서 결제 검증 서버 코드 작성해줘
웹훅 설정은 어떻게 하는거야?
결제위젯으로 카카오페이, 네이버페이 연동해줘
토스페이먼츠 PG로 가상계좌 결제 구현해줘

Architecture

두 가지 전송 방식을 지원하며, 도구 범위가 다릅니다:

 ┌─────────────────────┐
│ AI Coding Tool │
│ (Claude, Cursor, │
│ Windsurf, Cline, │
│ Codex, Gemini) │
└──────────┬──────────┘
│
┌─────────┴─────────┐
▼ ▼
[HTTP] [stdio]
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────────────┐
│ Cloudflare │ │ npx -y @bootpay/mcp@latest │
│ Workers │ │ │
│ bootpay-docs-mcp │ │ ┌─ Docs ( 8 tools) │
│ .workers.dev/mcp │ │ ├─ Admin (67 tools) │
│ │ │ └─ Commerce (13 tools)* │
│ Docs only │ │ │
│ (8 tools) │ │ * opt-in │
└────────┬─────────┘ └────────────────────────────┘
│
┌────────┴─────────┐
│ KV │
│ 120+ docs │
└──────────────────┘

전송	Docs (8)	Admin (67)	Commerce (13)	노출 도구 수
HTTP (Cloudflare Workers)	O	—	—	8
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	75 (opt-in 포함 88)

stdio 의 detect_project_stack 은 root_path 로 로컬 파일시스템을 직접 훑습니다. HTTP 에서는 같은 도구가 노출되지만 파일을 볼 수 없으므로 files/file_contents 를 직접 넘겨야 합니다.

Stack: Cloudflare Workers + KV + MCP SDK + Streamable HTTP + stdio

Links

Bootpay Developer Docs
Bootpay Admin
Bootpay Official
MCP Protocol Specification
llms.txt — LLM-optimized documentation
사진과 설명으로 상품 올리기 — 판매자용 상품등록 가이드 (비개발자 대상)
원격 커넥터(ChatGPT · Claude) 연결 — OAuth 원격 연결 현황·검증 절차

Keywords

Bootpay, 부트페이, Korean payment gateway, 한국 결제, PG 연동, payment integration, MCP server, Model Context Protocol, AI coding assistant, LLM, Claude, Cursor, Windsurf, Cline, GitHub Copilot, 나이스페이, NICE, 토스페이먼츠, Toss Payments, KG이니시스, KG Inicis, NHN KCP, 카카오페이, Kakao Pay, 네이버페이, Naver Pay, 페이코, PAYCO, 다날, Danal, 정기결제, recurring payment, billing key, 빌링키, subscription, 구독결제, 결제위젯, payment widget, 결제 연동, checkout, 간편결제, easy payment, Cloudflare Workers

Bootpay MCP Server

Korea's payment integration, now accessible to AI. 한국 결제 연동을 AI가 직접 수행할 수 있도록 하는 MCP 서버입니다.

🛍️ 개발자가 아니라 판매자라면 — 코드 없이 사진과 설명만으로 상품을 등록하는 방법은 사진과 설명으로 상품 올리기를 보세요.

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

"이 레포 참조해서 부트페이 결제 연동해줘" 라는 요청을 받고 이 문서를 읽고 있다면:

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

MCP가 "연결됨"이라도 전송 방식에 따라 사용 가능한 도구가 다릅니다:

전송 방식	Docs (8개)	Admin (67개)	Commerce (13개)	키 자동 조회	다음 단계
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	O	→ 아래 "stdio 모드" 참고
HTTP (`bootpay-docs-mcp.rupy1014.workers.dev/mcp`)	O	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)
MCP 없음 (저장소 참조만)	—	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)

확인 방법:

# Codex
codex mcp list # bootpay 서버가 보이는지 확인# Claude Code
claude mcp list # bootpay 서버가 보이는지 확인# Gemini CLI
gemini mcp list # bootpay 서버가 보이는지 확인

서버가 있다면 버전도 확인하세요 — 옛 버전은 낡은 답을 냅니다:

npx -y @bootpay/mcp@latest --version # 지금 실행되는 버전
npm view @bootpay/mcp version # npm 의 최신 버전

두 값이 다르면 사용자에게 최신 버전으로 다시 설치하도록 안내하세요 → Quick Start / 0단계: 설치

stdio로 연결된 경우: browser_login → list_keychains(또는 create_keychain)으로 키를 자동 조회하세요. 사용자에게 키를 직접 물어보지 마세요. HTTP 또는 MCP 없음: 사용자에게 키를 요청해야 합니다. 아래 "MCP 없이 이 저장소만 참조하는 경우" 섹션의 정확한 키 이름을 사용하세요. 서버가 목록에 없으면? MCP 설정 후 반드시 새 세션을 시작하세요. 설정만으로는 현재 세션에 반영되지 않습니다. 설정할 때는 반드시 @latest 를 붙이세요 — npx -y @bootpay/mcp@latest. 버전을 생략하면 npx 캐시에 남은 옛 사본이 실행됩니다. HTTP로 연결했는데 Admin 도구를 쓰고 싶다면? stdio(npx -y @bootpay/mcp@latest)로 재설정 후 새 세션을 시작하세요.

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

중요: 문서(search_docs)를 먼저 읽지 마세요. Admin 도구로 실제 프로젝트 컨텍스트를 먼저 수집하세요.

1. get_integration_context() → 인증/프로젝트/결제설정/위젯/키체인 한 번에 확인 ⭐
→ readiness.ready = true이면 Step 5로 이동
→ readiness.blockers가 있으면 아래 순서로 해결:
2. browser_login → Bootpay 로그인 (미인증 시)
3. browser_select_project → 프로젝트 선택 (미선택 시)
4. create_keychain(targets=["core"]) → 결제용 API 키 발급 (키체인 없을 때)
→ client_key, secret_key 반환 → .env에 즉시 저장
5. get_sdk_versions → 최신 SDK 버전 확인
6. search_docs → get_doc → 관련 문서 조회 (보완 참조)
7. 코드 작성 → .env 환경변수 참조 (키를 코드에 하드코딩 금지)

서버 인증: client_key/secret_key 기반 Basic Auth. getAccessToken() 불필요.

MCP 없이 이 저장소만 참조하는 경우

🚫 API 키를 추측하거나 임의로 생성하지 마세요.692e4c6da0ba315535c9dedf 같은 랜덤 문자열을 .env에 넣으면 100% 실패합니다. Bootpay API 키는 Bootpay 서버가 발급한 값만 유효합니다.

아래 파일을 순서대로 읽고 코드를 작성하세요:

순서	파일	내용
1	`AGENTS.md`	AI 에이전트용 지시 — 금지 행위, 금액 규칙, 통합결제창 판단
2	`SETUP_GUIDE.md`	MCP 최신 설치 · Admin CLI로 키 조회 또는 수동 설정
3	`SDK_VERSIONS.md`	최신 SDK 버전 (v2 5.x) — 3.x/4.x는 deprecated
4	`llms.txt`	핵심 규칙, API 도메인, SDK 패키지, 결제 흐름
5	`examples/`	플랫폼별 전체 코드 예제 (12개)

⚠️MCP 없이는 API 키를 AI가 자동 조회할 수 없습니다. 사용자에게 반드시 아래 안내를 하세요:
admin.bootpay.co.kr → 프로젝트 → 개발자 설정 → API 연동키(결제) 탭에서 아래 3개 키를 확인하여 .env에 입력
또는 stdio 모드로 MCP를 연결하면 list_keychains로 자동 조회 가능
이 안내 없이 키를 추측하거나, 빈 값/.env 없이 코드를 생성하면 실패합니다.

사용자에게 요청할 키 2개 (정확한 이름)

Admin UI(admin.bootpay.co.kr)에서 보이는 라벨과 .env 변수명이 다릅니다. 반드시 아래 매핑을 사용하세요:

Admin UI 라벨	.env 변수명	용도
Client Key (= REST API Key)	`BOOTPAY_CLIENT_KEY`	프론트엔드 SDK 결제창 호출 + 서버 Basic Auth 공통
Secret Key (= Private Key)	`BOOTPAY_SECRET_KEY`	서버 Basic Auth 인증 (비밀)

프론트엔드 빌드 도구에 따라 BOOTPAY_CLIENT_KEY 앞에 접두사를 붙입니다:
Vite → VITE_BOOTPAY_CLIENT_KEY
Next.js → NEXT_PUBLIC_BOOTPAY_CLIENT_KEY
Create React App → REACT_APP_BOOTPAY_CLIENT_KEY

# .env 예시 — create_keychain 또는 Admin UI에서 확인한 값을 입력
BOOTPAY_CLIENT_KEY= # Client Key (프론트엔드 SDK + 서버 Basic Auth 공통)
BOOTPAY_SECRET_KEY= # Secret Key (서버 전용, 프론트엔드 노출 금지)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

잘못된 이름	올바른 이름	비고
`BOOTPAY_REST_APP_ID`	`BOOTPAY_CLIENT_KEY`	"REST API Key"는 Admin UI 라벨일 뿐, 변수명이 아님
`BOOTPAY_PRIVATE_KEY`	`BOOTPAY_SECRET_KEY`	Bootpay에서는 "Secret Key"로 통일
`BOOTPAY_API_KEY`	`BOOTPAY_CLIENT_KEY`	존재하지 않는 변수명
`getAccessToken()`	Basic Auth	v2에서는 토큰 발급 불필요. client_key:secret_key로 직접 인증

핵심 규칙

SDK v2 (5.x) only — bootpay-3.x.x.min.js, bootpay-4.x.x.min.js는 v1(deprecated)이며 동작하지 않음
결제는 프론트엔드에서 시작 — 국내 PG 규정. 백엔드에서 결제를 시작하는 코드 금지
서버승인(분리승인)이 기본 — Bootpay.requestPayment 호출 시 extra.separately_confirmed: true 설정. confirm 시점에 receipt_id를 서버로 전달하면 서버가 confirmPayment()로 최종 승인하고 리턴값으로 금액을 확인 (별도 결제검증 조회 불필요). done 이벤트만 처리하는 클라이언트 승인 코드는 유실 위험이 있어 비권장
웹훅 보완 필수 — 클라이언트 결과 처리는 브라우저 이탈로 유실될 수 있음. 웹훅 엔드포인트를 함께 구현 (부트페이 발신 IP 223.130.82.0/24만 허용 + receiptPayment 재검증 + 멱등 처리)
API 키는 Admin CLI로 발급 → .env에 기록 — placeholder·추측값·랜덤 문자열 금지. create_keychain 또는 list_keychains 반환값만 사용
서버 인증은 Basic Auth — client_key/secret_key 기반. getAccessToken() 불필요
Secret Key는 서버 전용 — 절대 프론트엔드에 노출하지 않을 것

오프라인 · MCP 없이 사용하기

방법 1 — 최신 패키지를 파일로 받아서 설치 (사내망 등 npx 를 못 쓰는 환경)

npm pack @bootpay/mcp@latest # 최신 버전 .tgz 가 현재 폴더에 떨어집니다
npm install -g ./bootpay-mcp-*.tgz # 받은 파일로 전역 설치
bootpay-mcp --version # 설치된 버전 확인

GitHub Releases 의 고정 버전 파일을 받지 마세요. 최신 버전은 항상 npm 에 있습니다. 버전을 고정해야 한다면 npm view @bootpay/mcp versions 로 목록을 보고 @bootpay/mcp@2.1.0 처럼 명시하세요.

방법 2 — 문서만 AI 에게 전달 (npm/git 불필요, MCP 도구는 못 씀)

main.tar.gz 다운로드
AI 도구에 파일 첨부
"부트페이 결제 연동해줘"라고 요청

방법 3 — git clone (문서 참조용)

git clone https://github.com/bootpay/bootpay-mcp.git
# AGENTS.md, llms.txt, SDK_VERSIONS.md, SETUP_GUIDE.md 를 AI에게 전달

방법 2·3 은 문서만 전달합니다. Admin 도구(로그인·키 발급·코드 생성)는 stdio 로 MCP 를 붙여야 씁니다. 이 경우 AI 는 API 키를 자동 조회할 수 없으니, 아래 "MCP 없이 이 저장소만 참조하는 경우" 절을 따르세요.

About This Project

AI 코딩 도구(Claude, Cursor, Windsurf, Cline, GitHub Copilot 등)에서 Bootpay 결제·커머스를 연동할 수 있는 통합 Model Context Protocol (MCP) 서버입니다.

Docs (문서 검색·SDK 버전·트러블슈팅) + Admin (관리자 설정·PG·위젯·코드 생성) + Commerce (스토어·상품·회원) — 하나의 MCP 서버로 제공합니다.

stdio 로 붙으면 기본 75개(Docs 8 + Admin 67), Commerce 를 켜면 88개 도구가 노출됩니다. HTTP 로 붙으면 Docs 8개만 노출됩니다.

Supported PG & Payment Methods

Bootpay는 국내 주요 PG사와 간편결제를 통합 지원합니다:

PG사	코드	지원 결제
나이스페이 (NICE)	`nicepay`	카드, 계좌이체, 가상계좌, 휴대폰
토스페이먼츠 (Toss Payments)	`tosspayments`	카드, 계좌이체, 가상계좌, 휴대폰
KG이니시스 (KG Inicis)	`inicis`	카드, 계좌이체, 가상계좌, 휴대폰
NHN KCP	`kcp`	카드, 계좌이체, 가상계좌, 휴대폰
카카오페이 (Kakao Pay)	`kakao`	간편결제
네이버페이 (Naver Pay)	`naverpay`	간편결제
페이코 (PAYCO)	`payco`	간편결제
토스페이 (Toss Pay)	`tosspay`	간편결제
다날 (Danal)	`danal`	휴대폰 소액결제

결제 유형: 일반결제 (카드/계좌이체/가상계좌/휴대폰) · 정기결제 (빌링키) · 본인인증 · 에스크로 · 현금영수증

Quick Start

두 가지 연결 방식을 지원합니다:

방식	특징	추천 환경
HTTP (Streamable HTTP)	설치 불필요, 원격 서버	Cursor, Windsurf, Cline, 웹 기반
npm (stdio)	로컬 실행, Admin·Commerce 도구 사용 가능	Claude Desktop, Claude Code, Codex, Gemini CLI

0단계: 설치 — 반드시 최신 버전으로

stdio 설정에는 항상 @latest 를 붙이세요.

npx -y @bootpay/mcp@latest

⚠️@latest 를 빼면 예전에 받아둔 사본이 계속 실행됩니다.npx @bootpay/mcp 처럼 버전을 생략하면 npx 는 캐시(~/.npm/_npx/)에 남아 있는 사본을 먼저 씁니다. 한 번 받아둔 사람은 새 버전이 나와도 옛 버전을 계속 실행하게 되고, 그 사이에 고쳐진 것들이 전달되지 않습니다. 실제로 최근 릴리스에서 문서 검색이 조용히 빈 결과를 내던 문제 · 낡은 SDK 버전표 · 일부 도구가 인자를 거절하던 문제가 고쳐졌습니다. 옛 버전을 쓰면 AI 가 그 낡은 정보로 코드를 만듭니다.

지금 무엇이 실행되는지 확인하세요:

npm view @bootpay/mcp version # npm 에 올라온 최신 버전
npx -y @bootpay/mcp@latest --version # 실행될 서버의 버전 (v2.1.1 이상)

--version 은 v2.1.1부터 지원합니다. 그보다 낮은 버전이면 이 명령이 서버를 띄운 채 멈춥니다. 그럴 때는 Ctrl+C 로 끄고 — 그것 자체가 옛 버전이라는 신호이므로 — 아래 캐시 비우기를 바로 실행하세요.

두 값이 같으면 최신입니다. 다르면 캐시를 비우고 다시 받으세요:

npx clear-npx-cache # npx 캐시 비우기
rm -rf ~/.npm/_npx # 위 명령이 안 되면 (macOS/Linux)

Windows PowerShell:

Remove-Item-Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

항상 같은 버전을 고정해서 쓰고 싶다면 전역 설치도 됩니다. 대신 업데이트는 직접 해야 합니다:

npm install -g @bootpay/mcp@latest # 설치 · 업데이트 모두 이 명령
bootpay-mcp --version # 설치된 버전 확인

이 경우 MCP 설정의 command 는 npx 대신 bootpay-mcp 를 쓰고 args 는 비웁니다.

전제조건 — Node.js 18 이상

node -v # v18.0.0 이상이어야 합니다

node 명령이 없다면 https://nodejs.org 에서 LTS 를 먼저 설치하고, 터미널을 새로 여세요 (PATH 반영). Windows 는 설치 후 PowerShell 을 새로 열어야 node 가 잡힙니다.

설정을 저장한 뒤에는 AI 클라이언트를 완전히 종료하고 다시 켜세요. 설정 파일만 고치면 현재 세션에는 반영되지 않습니다. 도구 목록에 부트페이 도구가 안 보이면 대부분 이것 때문입니다. 확인: claude mcp list / codex mcp list / gemini mcp list

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows):

npm (stdio) — 추천:

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP (원격):

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["mcp-remote", "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"]
}
}
}

Claude Code (CLI)

# npm (stdio)
claude mcp add bootpay-docs -- npx -y @bootpay/mcp@latest
# HTTP
claude mcp add bootpay-docs --transport http https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

Cursor

Settings → MCP Servers → Add:

{
"bootpay-docs": {
"url": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}

Codex (OpenAI)

~/.codex/config.toml:

stdio (권장, 전체 도구):

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]

HTTP (Docs 도구만, 설치 불필요):

[mcp_servers.bootpay]
url = "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"

Commerce 도구 활성화:

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]
[mcp_servers.bootpay.env]
BOOTPAY_COMMERCE_CLIENT_KEY = "YOUR_CLIENT_KEY"BOOTPAY_COMMERCE_SECRET_KEY = "YOUR_SECRET_KEY"

또는 CLI로 추가:

codex mcp add bootpay -- npx -y @bootpay/mcp@latest

설정 후 반드시 확인:
현재 Codex 세션을 종료하고 새 세션을 시작하세요
codex mcp list로 bootpay 서버가 보이는지 확인
보이지 않으면 ~/.codex/config.toml의 [mcp_servers.bootpay] 섹션을 재확인

Gemini CLI

~/.gemini/settings.json:

stdio (권장, 전체 도구):

{
"mcpServers": {
"bootpay": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP Streaming:

{
"mcpServers": {
"bootpay": {
"httpUrl": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}
}

또는 CLI로 추가:

gemini mcp add bootpay npx -y @bootpay/mcp@latest

주의: Gemini CLI는 서버 이름에 언더스코어(_)를 사용하면 보안 정책 파싱 오류가 발생합니다. bootpay-docs ✅ / bootpay_docs ❌

Windsurf / Cline / Other MCP Clients

Streamable HTTP endpoint:

https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

What AI Can Do with This MCP

MCP를 연결하면 AI가 다음을 직접 수행합니다:

사용자: "React에서 부트페이 카드결제 연동해줘"
AI 내부 동작:
1. get_sdk_versions → 최신 SDK 버전 확인 (v2 5.x)
2. get_setup_checklist → Client Key + 환경 설정 안내
3. search_docs → get_doc → payment/request 문서 조회
4. 코드 작성 → 문서 기반, 정확한 버전 사용

Docs Tools — 8개 (HTTP + stdio)

Tool	Description
`detect_project_stack`	프로젝트 스택 판정 — 클라이언트 플랫폼·웹 프레임워크·서버 언어·실행 환경(상시/서버리스). 모노레포면 앱마다 판정하고 "서버 1회 + 클라이언트 N회" 호출 계획을 반환
`get_sdk_versions`	모든 SDK 최신 버전 조회 (Web, Android, iOS, Flutter, React Native, 서버 7개 언어)
`search_docs`	120+ 개발자 문서 검색 (12 카테고리)
`get_doc`	특정 문서 전체 마크다운 조회
`list_docs`	카테고리별 문서 목록
`get_setup_checklist`	연동 환경 설정 체크리스트 (API 키, SDK 설치, .env)
`get_troubleshooting`	문제 해결 가이드 (onboarding, sandbox, webhook, billing, subscription, error, cancel, cors, csp, open-type, mobile, widget, unified, certification)
`get_csp_allowlist`	CSP(frame-src) 허용 PG 도메인 목록 + 프레임워크별 설정 스니펫 생성
`get_cs_guide`	고객응대(CS) 매뉴얼 검색

Prompt	Description
`integration-action-plan`	결제유형 × 플랫폼별 6단계 연동 액션 플랜

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Bootpay가 처음이라면 관리자 화면 대신 AI에게 전부 맡기세요. stdio 방식(npx -y @bootpay/mcp@latest)으로 연결하면 Admin 도구 67개가 활성화됩니다.

사용자: "부트페이 결제 연동하고 싶어. 처음이야"
AI 내부 동작:
1. browser_login → 브라우저 팝업으로 로그인
2. create_seller → 셀러(가맹점) 생성 + 기본 프로젝트 자동 생성
3. browser_select_project → 프로젝트 선택
4. activate_payment_method → 나이스페이 카드결제 활성화
5. set_sandbox_mode → 테스트 모드 설정
6. create_keychain(targets=["core"]) → 결제용 API 키 발급 (client_key, secret_key)
7. search_docs + get_doc → 최신 연동 문서 참조
8. 코드 생성 → 발급한 키를 .env에 설정, 코드에서 환경변수 참조

⚠️ 키를 코드에 직접 삽입하지 마세요. 발급한 키는 반드시 .env 파일에 저장하고, 코드에서는 환경변수로 참조합니다. Secret Key는 서버 .env에만 저장하세요. secret_key는 발급 시 1회만 평문으로 표시됩니다.

HTTP 방식에서는 Admin 도구를 사용할 수 없습니다. 프로젝트 설정이 필요하면 반드시 stdio(npx @bootpay/mcp@latest)를 사용하세요.

Admin Tools — 67개 (stdio 전용)

관리자(admin.bootpay.co.kr)의 설정을 AI가 직접 조회·변경할 수 있는 도구입니다. npx -y @bootpay/mcp@latest로 실행하면 자동 활성화됩니다.

카테고리	Tools	Description
코드생성	`generate_payment_code`, `generate_commerce_code`	프리플라이트(인증·키체인·결제수단·SDK 확인) + 클라이언트/서버 코드 원스톱 생성. `payment_type`: `payment`(일반) / `billing`(빌링키) / `subscription`(구독 — 회차·배치·무료체험·해지) / `widget` / `auth`, `scheduler`: `cron` / `http_trigger`(서버리스)
컨텍스트	`get_integration_context`, `get_commerce_context`	인증·프로젝트·결제설정·위젯·키체인을 한 번에 조회 (`readiness.blockers` 반환)
인증	`login`, `browser_login`, `logout`, `list_projects`, `switch_project`, `browser_select_project`, `set_token`, `get_auth_status`	로그인, 프로젝트 전환, 토큰 설정·상태 확인
셀러	`create_seller`, `search_sellers`, `get_seller`, `update_seller`	셀러(가맹점) CRUD
상세설명 블록	`list_content_templates`, `create_content_template`, `delete_content_template`, `list_content_blocks`, `create_content_block`, `update_content_block`, `delete_content_block`, `list_content_block_products`	상세설명을 블록으로 구성. 시작 템플릿(서버 저장분 + MCP 내장 스타터)과 여러 상품이 공유하는 공용 블록 관리. `content_type=4`일 때만 블록이 저장되며, HTML(`content`)은 서버가 컴파일해 채웁니다
디지털 코드풀	`list_digital_codes`, `register_digital_codes`, `disable_digital_code`	시리얼·라이센스 번호 일괄 등록/조회/폐기. `code_distribution_mode="pool"` 상품에서 구매자마다 다른 코드를 발급할 때 사용 (한 번에 최대 5,000개)
이미지	`upload_product_images`	로컬 경로·URL·base64 → Bootpay CDN 업로드 (최대 10장, 장당 10MB)
카테고리	`list_categories`, `create_category`, `update_category`, `delete_category`, `reorder_categories`	카테고리 CRUD. `path="상의 > 티셔츠 > 반팔"`로 계층 일괄 생성, 삭제는 `confirm` 확인 게이트
부속설정	`list_subscription_settings`, `list_delivery_shippings`, `create_subscription_setting`, `create_delivery_shipping`, `list_delivery_shipping_bundles`, `get_product_form_setting`, `get_product_info_notice_forms`	상품에 연결할 구독 설정·배송정책 ID 확보. 정책이 하나도 없는 프로젝트에서는 생성까지 가능 — 배송비·주기 같은 값이 빠지면 저장 대신 `need_answer` 로 무엇을 물어야 하는지 돌려줍니다(금액을 추측해 저장하지 않습니다). 폼 설정 조회로 판매자가 끈 섹션을 건너뛰고, 상품 주요정보(상품정보제공고시)의 상품군(1~40)과 군별 입력 항목도 조회
프로젝트	`create_project`	프로젝트 생성
키체인	`list_api_scopes`, `list_keychains`, `create_keychain`, `delete_keychain`, `get_commerce_keys`	API 키 발급/조회 (source 파라미터로 커머스/결제 구분)
상품	`list_products`, `get_product`, `create_product`, `update_product`, `delete_product`, `create_test_products`	상품 CRUD. `image_paths`로 로컬 사진 경로를 주면 업로드까지 처리, 구독(`subscription_setting_id`)·배송정책(`delivery_shipping_id`) 연결, 상세설명 블록(`content_blocks`), 디지털 지급(`digital_provisioning_type`), 환불정책 노출(`refund_policy_expose_type`) 지원
결제설정	`get_payment_settings`, `activate_payment_method`, `set_sandbox_mode`, `update_payment_resource`, `set_payment_mode`, `browser_select_payment_method`	PG·결제수단 설정
위젯	`list_widgets`, `get_widget`, `create_widget`, `get_widget_default_styles`, `configure_widget`, `update_widget`, `delete_widget`	결제위젯 CRUD
쇼핑몰설정	`get_mall_setting`, `update_mall_setting`	커머스 몰 기본 설정 조회·변경

상품·상세설명 블록·디지털 코드풀·카테고리·이미지 도구는 원격(OAuth) 프로파일에도 포함됩니다. 결제설정·키체인·자격증명 도구는 원격에서 제외됩니다 — 근거와 현재 상태는 원격 커넥터 문서를 보세요.

Commerce Tools — 13개 (stdio 전용, opt-in)

AI 에이전트가 커머스 API를 호출하여 쇼핑몰 기능을 구현할 수 있는 도구입니다. 활성화: 환경변수 BOOTPAY_COMMERCE_ENABLED=true 설정 후 실행.

카테고리	Tools	Description
인증	`set_commerce_credentials`	clientKey/secretKey 설정·검증
스토어	`commerce_get_store`, `commerce_get_store_detail`	가맹점 정보 조회
상품	`commerce_get_products`, `commerce_get_product`, `commerce_create_product`, `commerce_update_product`	상품 CRUD
회원	`commerce_login`, `commerce_get_session`, `commerce_logout`	회원 로그인·세션 관리
리뷰	`commerce_get_reviews`, `commerce_get_review_stats`	리뷰 조회·통계
상태	`commerce_status`	Commerce API 상태 확인

Supported Platforms & SDKs

Client SDKs

Platform	Package
Web (NPM)	`@bootpay/client-js`
Web (CDN)	`bootpay-{version}.min.js`
Android (Kotlin/Java)	`kr.co.bootpay:android`
iOS (Swift/ObjC)	`pod 'Bootpay'`
Flutter	`bootpay_flutter`
React Native	`react-native-bootpay-api`

Server SDKs

Language	Package
Node.js	`@bootpay/backend-js`
Python	`bootpay-backend`
Java / Kotlin	`kr.co.bootpay:backend`
Ruby	`bootpay`
Go	`github.com/bootpay/backend-go/v2`
.NET (C#)	`Bootpay`
PHP	`bootpay/backend-php`

Documentation Categories

Category	Content
`payment`	일반결제 — SDK 설치, 결제창, 서버 검증, 취소/환불
`billing`	정기결제 — 빌링키 발급, 자동결제, 예약결제, 해지
`subscription`	구독관리 — 플랜 생성, 갱신, 해지, 과금
`order`	주문관리 — 주문 생성, 취소, 반품
`customer`	고객관리 — 고객 등록, 그룹, 조회
`product`	상품관리 — 상품 CRUD, 옵션, 카테고리
`webhook`	웹훅 — 설정, 이벤트, 처리, 재시도 정책
`guide`	시작하기 — 키 발급, 환경설정, 개요
`integration`	연동 — 에러코드, 마이그레이션, 호환성
`invoice`	링크페이 — 결제 링크 생성, 알림
`recipes`	레시피 — 업종별 연동 시나리오
`architecture`	아키텍처 — 결제 플로우, 데이터 모델

Ask AI

MCP를 연결한 후 AI에게 이렇게 물어보세요:

부트페이 결제 연동 어떻게 해?
React에서 카드결제 연동하는 전체 코드 알려줘
Flutter에서 정기결제(빌링키) 발급 방법 알려줘
기존 프로젝트에 월 구독결제 붙여줘 (매일 배치로 결제, 같은 달 두 번 결제 방지, 성공 시에만 다음 달 이용 개방)
Next.js에서 결제 검증 서버 코드 작성해줘
웹훅 설정은 어떻게 하는거야?
결제위젯으로 카카오페이, 네이버페이 연동해줘
토스페이먼츠 PG로 가상계좌 결제 구현해줘

Architecture

두 가지 전송 방식을 지원하며, 도구 범위가 다릅니다:

 ┌─────────────────────┐
│ AI Coding Tool │
│ (Claude, Cursor, │
│ Windsurf, Cline, │
│ Codex, Gemini) │
└──────────┬──────────┘
│
┌─────────┴─────────┐
▼ ▼
[HTTP] [stdio]
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────────────┐
│ Cloudflare │ │ npx -y @bootpay/mcp@latest │
│ Workers │ │ │
│ bootpay-docs-mcp │ │ ┌─ Docs ( 8 tools) │
│ .workers.dev/mcp │ │ ├─ Admin (67 tools) │
│ │ │ └─ Commerce (13 tools)* │
│ Docs only │ │ │
│ (8 tools) │ │ * opt-in │
└────────┬─────────┘ └────────────────────────────┘
│
┌────────┴─────────┐
│ KV │
│ 120+ docs │
└──────────────────┘

전송	Docs (8)	Admin (67)	Commerce (13)	노출 도구 수
HTTP (Cloudflare Workers)	O	—	—	8
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	75 (opt-in 포함 88)

stdio 의 detect_project_stack 은 root_path 로 로컬 파일시스템을 직접 훑습니다. HTTP 에서는 같은 도구가 노출되지만 파일을 볼 수 없으므로 files/file_contents 를 직접 넘겨야 합니다.

Stack: Cloudflare Workers + KV + MCP SDK + Streamable HTTP + stdio

Links

Bootpay Developer Docs
Bootpay Admin
Bootpay Official
MCP Protocol Specification
llms.txt — LLM-optimized documentation
사진과 설명으로 상품 올리기 — 판매자용 상품등록 가이드 (비개발자 대상)
원격 커넥터(ChatGPT · Claude) 연결 — OAuth 원격 연결 현황·검증 절차

Keywords

Bootpay, 부트페이, Korean payment gateway, 한국 결제, PG 연동, payment integration, MCP server, Model Context Protocol, AI coding assistant, LLM, Claude, Cursor, Windsurf, Cline, GitHub Copilot, 나이스페이, NICE, 토스페이먼츠, Toss Payments, KG이니시스, KG Inicis, NHN KCP, 카카오페이, Kakao Pay, 네이버페이, Naver Pay, 페이코, PAYCO, 다날, Danal, 정기결제, recurring payment, billing key, 빌링키, subscription, 구독결제, 결제위젯, payment widget, 결제 연동, checkout, 간편결제, easy payment, Cloudflare Workers

Bootpay MCP Server

Korea's payment integration, now accessible to AI. 한국 결제 연동을 AI가 직접 수행할 수 있도록 하는 MCP 서버입니다.

🛍️ 개발자가 아니라 판매자라면 — 코드 없이 사진과 설명만으로 상품을 등록하는 방법은 사진과 설명으로 상품 올리기를 보세요.

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

"이 레포 참조해서 부트페이 결제 연동해줘" 라는 요청을 받고 이 문서를 읽고 있다면:

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

MCP가 "연결됨"이라도 전송 방식에 따라 사용 가능한 도구가 다릅니다:

전송 방식	Docs (8개)	Admin (67개)	Commerce (13개)	키 자동 조회	다음 단계
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	O	→ 아래 "stdio 모드" 참고
HTTP (`bootpay-docs-mcp.rupy1014.workers.dev/mcp`)	O	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)
MCP 없음 (저장소 참조만)	—	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)

확인 방법:

# Codex
codex mcp list # bootpay 서버가 보이는지 확인# Claude Code
claude mcp list # bootpay 서버가 보이는지 확인# Gemini CLI
gemini mcp list # bootpay 서버가 보이는지 확인

서버가 있다면 버전도 확인하세요 — 옛 버전은 낡은 답을 냅니다:

npx -y @bootpay/mcp@latest --version # 지금 실행되는 버전
npm view @bootpay/mcp version # npm 의 최신 버전

두 값이 다르면 사용자에게 최신 버전으로 다시 설치하도록 안내하세요 → Quick Start / 0단계: 설치

stdio로 연결된 경우: browser_login → list_keychains(또는 create_keychain)으로 키를 자동 조회하세요. 사용자에게 키를 직접 물어보지 마세요. HTTP 또는 MCP 없음: 사용자에게 키를 요청해야 합니다. 아래 "MCP 없이 이 저장소만 참조하는 경우" 섹션의 정확한 키 이름을 사용하세요. 서버가 목록에 없으면? MCP 설정 후 반드시 새 세션을 시작하세요. 설정만으로는 현재 세션에 반영되지 않습니다. 설정할 때는 반드시 @latest 를 붙이세요 — npx -y @bootpay/mcp@latest. 버전을 생략하면 npx 캐시에 남은 옛 사본이 실행됩니다. HTTP로 연결했는데 Admin 도구를 쓰고 싶다면? stdio(npx -y @bootpay/mcp@latest)로 재설정 후 새 세션을 시작하세요.

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

중요: 문서(search_docs)를 먼저 읽지 마세요. Admin 도구로 실제 프로젝트 컨텍스트를 먼저 수집하세요.

1. get_integration_context() → 인증/프로젝트/결제설정/위젯/키체인 한 번에 확인 ⭐
→ readiness.ready = true이면 Step 5로 이동
→ readiness.blockers가 있으면 아래 순서로 해결:
2. browser_login → Bootpay 로그인 (미인증 시)
3. browser_select_project → 프로젝트 선택 (미선택 시)
4. create_keychain(targets=["core"]) → 결제용 API 키 발급 (키체인 없을 때)
→ client_key, secret_key 반환 → .env에 즉시 저장
5. get_sdk_versions → 최신 SDK 버전 확인
6. search_docs → get_doc → 관련 문서 조회 (보완 참조)
7. 코드 작성 → .env 환경변수 참조 (키를 코드에 하드코딩 금지)

서버 인증: client_key/secret_key 기반 Basic Auth. getAccessToken() 불필요.

MCP 없이 이 저장소만 참조하는 경우

🚫 API 키를 추측하거나 임의로 생성하지 마세요.692e4c6da0ba315535c9dedf 같은 랜덤 문자열을 .env에 넣으면 100% 실패합니다. Bootpay API 키는 Bootpay 서버가 발급한 값만 유효합니다.

아래 파일을 순서대로 읽고 코드를 작성하세요:

순서	파일	내용
1	`AGENTS.md`	AI 에이전트용 지시 — 금지 행위, 금액 규칙, 통합결제창 판단
2	`SETUP_GUIDE.md`	MCP 최신 설치 · Admin CLI로 키 조회 또는 수동 설정
3	`SDK_VERSIONS.md`	최신 SDK 버전 (v2 5.x) — 3.x/4.x는 deprecated
4	`llms.txt`	핵심 규칙, API 도메인, SDK 패키지, 결제 흐름
5	`examples/`	플랫폼별 전체 코드 예제 (12개)

⚠️MCP 없이는 API 키를 AI가 자동 조회할 수 없습니다. 사용자에게 반드시 아래 안내를 하세요:
admin.bootpay.co.kr → 프로젝트 → 개발자 설정 → API 연동키(결제) 탭에서 아래 3개 키를 확인하여 .env에 입력
또는 stdio 모드로 MCP를 연결하면 list_keychains로 자동 조회 가능
이 안내 없이 키를 추측하거나, 빈 값/.env 없이 코드를 생성하면 실패합니다.

사용자에게 요청할 키 2개 (정확한 이름)

Admin UI(admin.bootpay.co.kr)에서 보이는 라벨과 .env 변수명이 다릅니다. 반드시 아래 매핑을 사용하세요:

Admin UI 라벨	.env 변수명	용도
Client Key (= REST API Key)	`BOOTPAY_CLIENT_KEY`	프론트엔드 SDK 결제창 호출 + 서버 Basic Auth 공통
Secret Key (= Private Key)	`BOOTPAY_SECRET_KEY`	서버 Basic Auth 인증 (비밀)

프론트엔드 빌드 도구에 따라 BOOTPAY_CLIENT_KEY 앞에 접두사를 붙입니다:
Vite → VITE_BOOTPAY_CLIENT_KEY
Next.js → NEXT_PUBLIC_BOOTPAY_CLIENT_KEY
Create React App → REACT_APP_BOOTPAY_CLIENT_KEY

# .env 예시 — create_keychain 또는 Admin UI에서 확인한 값을 입력
BOOTPAY_CLIENT_KEY= # Client Key (프론트엔드 SDK + 서버 Basic Auth 공통)
BOOTPAY_SECRET_KEY= # Secret Key (서버 전용, 프론트엔드 노출 금지)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

잘못된 이름	올바른 이름	비고
`BOOTPAY_REST_APP_ID`	`BOOTPAY_CLIENT_KEY`	"REST API Key"는 Admin UI 라벨일 뿐, 변수명이 아님
`BOOTPAY_PRIVATE_KEY`	`BOOTPAY_SECRET_KEY`	Bootpay에서는 "Secret Key"로 통일
`BOOTPAY_API_KEY`	`BOOTPAY_CLIENT_KEY`	존재하지 않는 변수명
`getAccessToken()`	Basic Auth	v2에서는 토큰 발급 불필요. client_key:secret_key로 직접 인증

핵심 규칙

SDK v2 (5.x) only — bootpay-3.x.x.min.js, bootpay-4.x.x.min.js는 v1(deprecated)이며 동작하지 않음
결제는 프론트엔드에서 시작 — 국내 PG 규정. 백엔드에서 결제를 시작하는 코드 금지
서버승인(분리승인)이 기본 — Bootpay.requestPayment 호출 시 extra.separately_confirmed: true 설정. confirm 시점에 receipt_id를 서버로 전달하면 서버가 confirmPayment()로 최종 승인하고 리턴값으로 금액을 확인 (별도 결제검증 조회 불필요). done 이벤트만 처리하는 클라이언트 승인 코드는 유실 위험이 있어 비권장
웹훅 보완 필수 — 클라이언트 결과 처리는 브라우저 이탈로 유실될 수 있음. 웹훅 엔드포인트를 함께 구현 (부트페이 발신 IP 223.130.82.0/24만 허용 + receiptPayment 재검증 + 멱등 처리)
API 키는 Admin CLI로 발급 → .env에 기록 — placeholder·추측값·랜덤 문자열 금지. create_keychain 또는 list_keychains 반환값만 사용
서버 인증은 Basic Auth — client_key/secret_key 기반. getAccessToken() 불필요
Secret Key는 서버 전용 — 절대 프론트엔드에 노출하지 않을 것

오프라인 · MCP 없이 사용하기

방법 1 — 최신 패키지를 파일로 받아서 설치 (사내망 등 npx 를 못 쓰는 환경)

npm pack @bootpay/mcp@latest # 최신 버전 .tgz 가 현재 폴더에 떨어집니다
npm install -g ./bootpay-mcp-*.tgz # 받은 파일로 전역 설치
bootpay-mcp --version # 설치된 버전 확인

GitHub Releases 의 고정 버전 파일을 받지 마세요. 최신 버전은 항상 npm 에 있습니다. 버전을 고정해야 한다면 npm view @bootpay/mcp versions 로 목록을 보고 @bootpay/mcp@2.1.0 처럼 명시하세요.

방법 2 — 문서만 AI 에게 전달 (npm/git 불필요, MCP 도구는 못 씀)

main.tar.gz 다운로드
AI 도구에 파일 첨부
"부트페이 결제 연동해줘"라고 요청

방법 3 — git clone (문서 참조용)

git clone https://github.com/bootpay/bootpay-mcp.git
# AGENTS.md, llms.txt, SDK_VERSIONS.md, SETUP_GUIDE.md 를 AI에게 전달

방법 2·3 은 문서만 전달합니다. Admin 도구(로그인·키 발급·코드 생성)는 stdio 로 MCP 를 붙여야 씁니다. 이 경우 AI 는 API 키를 자동 조회할 수 없으니, 아래 "MCP 없이 이 저장소만 참조하는 경우" 절을 따르세요.

About This Project

AI 코딩 도구(Claude, Cursor, Windsurf, Cline, GitHub Copilot 등)에서 Bootpay 결제·커머스를 연동할 수 있는 통합 Model Context Protocol (MCP) 서버입니다.

Docs (문서 검색·SDK 버전·트러블슈팅) + Admin (관리자 설정·PG·위젯·코드 생성) + Commerce (스토어·상품·회원) — 하나의 MCP 서버로 제공합니다.

stdio 로 붙으면 기본 75개(Docs 8 + Admin 67), Commerce 를 켜면 88개 도구가 노출됩니다. HTTP 로 붙으면 Docs 8개만 노출됩니다.

Supported PG & Payment Methods

Bootpay는 국내 주요 PG사와 간편결제를 통합 지원합니다:

PG사	코드	지원 결제
나이스페이 (NICE)	`nicepay`	카드, 계좌이체, 가상계좌, 휴대폰
토스페이먼츠 (Toss Payments)	`tosspayments`	카드, 계좌이체, 가상계좌, 휴대폰
KG이니시스 (KG Inicis)	`inicis`	카드, 계좌이체, 가상계좌, 휴대폰
NHN KCP	`kcp`	카드, 계좌이체, 가상계좌, 휴대폰
카카오페이 (Kakao Pay)	`kakao`	간편결제
네이버페이 (Naver Pay)	`naverpay`	간편결제
페이코 (PAYCO)	`payco`	간편결제
토스페이 (Toss Pay)	`tosspay`	간편결제
다날 (Danal)	`danal`	휴대폰 소액결제

결제 유형: 일반결제 (카드/계좌이체/가상계좌/휴대폰) · 정기결제 (빌링키) · 본인인증 · 에스크로 · 현금영수증

Quick Start

두 가지 연결 방식을 지원합니다:

방식	특징	추천 환경
HTTP (Streamable HTTP)	설치 불필요, 원격 서버	Cursor, Windsurf, Cline, 웹 기반
npm (stdio)	로컬 실행, Admin·Commerce 도구 사용 가능	Claude Desktop, Claude Code, Codex, Gemini CLI

0단계: 설치 — 반드시 최신 버전으로

stdio 설정에는 항상 @latest 를 붙이세요.

npx -y @bootpay/mcp@latest

⚠️@latest 를 빼면 예전에 받아둔 사본이 계속 실행됩니다.npx @bootpay/mcp 처럼 버전을 생략하면 npx 는 캐시(~/.npm/_npx/)에 남아 있는 사본을 먼저 씁니다. 한 번 받아둔 사람은 새 버전이 나와도 옛 버전을 계속 실행하게 되고, 그 사이에 고쳐진 것들이 전달되지 않습니다. 실제로 최근 릴리스에서 문서 검색이 조용히 빈 결과를 내던 문제 · 낡은 SDK 버전표 · 일부 도구가 인자를 거절하던 문제가 고쳐졌습니다. 옛 버전을 쓰면 AI 가 그 낡은 정보로 코드를 만듭니다.

지금 무엇이 실행되는지 확인하세요:

npm view @bootpay/mcp version # npm 에 올라온 최신 버전
npx -y @bootpay/mcp@latest --version # 실행될 서버의 버전 (v2.1.1 이상)

--version 은 v2.1.1부터 지원합니다. 그보다 낮은 버전이면 이 명령이 서버를 띄운 채 멈춥니다. 그럴 때는 Ctrl+C 로 끄고 — 그것 자체가 옛 버전이라는 신호이므로 — 아래 캐시 비우기를 바로 실행하세요.

두 값이 같으면 최신입니다. 다르면 캐시를 비우고 다시 받으세요:

npx clear-npx-cache # npx 캐시 비우기
rm -rf ~/.npm/_npx # 위 명령이 안 되면 (macOS/Linux)

Windows PowerShell:

Remove-Item-Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

항상 같은 버전을 고정해서 쓰고 싶다면 전역 설치도 됩니다. 대신 업데이트는 직접 해야 합니다:

npm install -g @bootpay/mcp@latest # 설치 · 업데이트 모두 이 명령
bootpay-mcp --version # 설치된 버전 확인

이 경우 MCP 설정의 command 는 npx 대신 bootpay-mcp 를 쓰고 args 는 비웁니다.

전제조건 — Node.js 18 이상

node -v # v18.0.0 이상이어야 합니다

node 명령이 없다면 https://nodejs.org 에서 LTS 를 먼저 설치하고, 터미널을 새로 여세요 (PATH 반영). Windows 는 설치 후 PowerShell 을 새로 열어야 node 가 잡힙니다.

설정을 저장한 뒤에는 AI 클라이언트를 완전히 종료하고 다시 켜세요. 설정 파일만 고치면 현재 세션에는 반영되지 않습니다. 도구 목록에 부트페이 도구가 안 보이면 대부분 이것 때문입니다. 확인: claude mcp list / codex mcp list / gemini mcp list

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows):

npm (stdio) — 추천:

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP (원격):

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["mcp-remote", "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"]
}
}
}

Claude Code (CLI)

# npm (stdio)
claude mcp add bootpay-docs -- npx -y @bootpay/mcp@latest
# HTTP
claude mcp add bootpay-docs --transport http https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

Cursor

Settings → MCP Servers → Add:

{
"bootpay-docs": {
"url": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}

Codex (OpenAI)

~/.codex/config.toml:

stdio (권장, 전체 도구):

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]

HTTP (Docs 도구만, 설치 불필요):

[mcp_servers.bootpay]
url = "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"

Commerce 도구 활성화:

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]
[mcp_servers.bootpay.env]
BOOTPAY_COMMERCE_CLIENT_KEY = "YOUR_CLIENT_KEY"BOOTPAY_COMMERCE_SECRET_KEY = "YOUR_SECRET_KEY"

또는 CLI로 추가:

codex mcp add bootpay -- npx -y @bootpay/mcp@latest

설정 후 반드시 확인:
현재 Codex 세션을 종료하고 새 세션을 시작하세요
codex mcp list로 bootpay 서버가 보이는지 확인
보이지 않으면 ~/.codex/config.toml의 [mcp_servers.bootpay] 섹션을 재확인

Gemini CLI

~/.gemini/settings.json:

stdio (권장, 전체 도구):

{
"mcpServers": {
"bootpay": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP Streaming:

{
"mcpServers": {
"bootpay": {
"httpUrl": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}
}

또는 CLI로 추가:

gemini mcp add bootpay npx -y @bootpay/mcp@latest

주의: Gemini CLI는 서버 이름에 언더스코어(_)를 사용하면 보안 정책 파싱 오류가 발생합니다. bootpay-docs ✅ / bootpay_docs ❌

Windsurf / Cline / Other MCP Clients

Streamable HTTP endpoint:

https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

What AI Can Do with This MCP

MCP를 연결하면 AI가 다음을 직접 수행합니다:

사용자: "React에서 부트페이 카드결제 연동해줘"
AI 내부 동작:
1. get_sdk_versions → 최신 SDK 버전 확인 (v2 5.x)
2. get_setup_checklist → Client Key + 환경 설정 안내
3. search_docs → get_doc → payment/request 문서 조회
4. 코드 작성 → 문서 기반, 정확한 버전 사용

Docs Tools — 8개 (HTTP + stdio)

Tool	Description
`detect_project_stack`	프로젝트 스택 판정 — 클라이언트 플랫폼·웹 프레임워크·서버 언어·실행 환경(상시/서버리스). 모노레포면 앱마다 판정하고 "서버 1회 + 클라이언트 N회" 호출 계획을 반환
`get_sdk_versions`	모든 SDK 최신 버전 조회 (Web, Android, iOS, Flutter, React Native, 서버 7개 언어)
`search_docs`	120+ 개발자 문서 검색 (12 카테고리)
`get_doc`	특정 문서 전체 마크다운 조회
`list_docs`	카테고리별 문서 목록
`get_setup_checklist`	연동 환경 설정 체크리스트 (API 키, SDK 설치, .env)
`get_troubleshooting`	문제 해결 가이드 (onboarding, sandbox, webhook, billing, subscription, error, cancel, cors, csp, open-type, mobile, widget, unified, certification)
`get_csp_allowlist`	CSP(frame-src) 허용 PG 도메인 목록 + 프레임워크별 설정 스니펫 생성
`get_cs_guide`	고객응대(CS) 매뉴얼 검색

Prompt	Description
`integration-action-plan`	결제유형 × 플랫폼별 6단계 연동 액션 플랜

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Bootpay가 처음이라면 관리자 화면 대신 AI에게 전부 맡기세요. stdio 방식(npx -y @bootpay/mcp@latest)으로 연결하면 Admin 도구 67개가 활성화됩니다.

사용자: "부트페이 결제 연동하고 싶어. 처음이야"
AI 내부 동작:
1. browser_login → 브라우저 팝업으로 로그인
2. create_seller → 셀러(가맹점) 생성 + 기본 프로젝트 자동 생성
3. browser_select_project → 프로젝트 선택
4. activate_payment_method → 나이스페이 카드결제 활성화
5. set_sandbox_mode → 테스트 모드 설정
6. create_keychain(targets=["core"]) → 결제용 API 키 발급 (client_key, secret_key)
7. search_docs + get_doc → 최신 연동 문서 참조
8. 코드 생성 → 발급한 키를 .env에 설정, 코드에서 환경변수 참조

⚠️ 키를 코드에 직접 삽입하지 마세요. 발급한 키는 반드시 .env 파일에 저장하고, 코드에서는 환경변수로 참조합니다. Secret Key는 서버 .env에만 저장하세요. secret_key는 발급 시 1회만 평문으로 표시됩니다.

HTTP 방식에서는 Admin 도구를 사용할 수 없습니다. 프로젝트 설정이 필요하면 반드시 stdio(npx @bootpay/mcp@latest)를 사용하세요.

Admin Tools — 67개 (stdio 전용)

관리자(admin.bootpay.co.kr)의 설정을 AI가 직접 조회·변경할 수 있는 도구입니다. npx -y @bootpay/mcp@latest로 실행하면 자동 활성화됩니다.

카테고리	Tools	Description
코드생성	`generate_payment_code`, `generate_commerce_code`	프리플라이트(인증·키체인·결제수단·SDK 확인) + 클라이언트/서버 코드 원스톱 생성. `payment_type`: `payment`(일반) / `billing`(빌링키) / `subscription`(구독 — 회차·배치·무료체험·해지) / `widget` / `auth`, `scheduler`: `cron` / `http_trigger`(서버리스)
컨텍스트	`get_integration_context`, `get_commerce_context`	인증·프로젝트·결제설정·위젯·키체인을 한 번에 조회 (`readiness.blockers` 반환)
인증	`login`, `browser_login`, `logout`, `list_projects`, `switch_project`, `browser_select_project`, `set_token`, `get_auth_status`	로그인, 프로젝트 전환, 토큰 설정·상태 확인
셀러	`create_seller`, `search_sellers`, `get_seller`, `update_seller`	셀러(가맹점) CRUD
상세설명 블록	`list_content_templates`, `create_content_template`, `delete_content_template`, `list_content_blocks`, `create_content_block`, `update_content_block`, `delete_content_block`, `list_content_block_products`	상세설명을 블록으로 구성. 시작 템플릿(서버 저장분 + MCP 내장 스타터)과 여러 상품이 공유하는 공용 블록 관리. `content_type=4`일 때만 블록이 저장되며, HTML(`content`)은 서버가 컴파일해 채웁니다
디지털 코드풀	`list_digital_codes`, `register_digital_codes`, `disable_digital_code`	시리얼·라이센스 번호 일괄 등록/조회/폐기. `code_distribution_mode="pool"` 상품에서 구매자마다 다른 코드를 발급할 때 사용 (한 번에 최대 5,000개)
이미지	`upload_product_images`	로컬 경로·URL·base64 → Bootpay CDN 업로드 (최대 10장, 장당 10MB)
카테고리	`list_categories`, `create_category`, `update_category`, `delete_category`, `reorder_categories`	카테고리 CRUD. `path="상의 > 티셔츠 > 반팔"`로 계층 일괄 생성, 삭제는 `confirm` 확인 게이트
부속설정	`list_subscription_settings`, `list_delivery_shippings`, `create_subscription_setting`, `create_delivery_shipping`, `list_delivery_shipping_bundles`, `get_product_form_setting`, `get_product_info_notice_forms`	상품에 연결할 구독 설정·배송정책 ID 확보. 정책이 하나도 없는 프로젝트에서는 생성까지 가능 — 배송비·주기 같은 값이 빠지면 저장 대신 `need_answer` 로 무엇을 물어야 하는지 돌려줍니다(금액을 추측해 저장하지 않습니다). 폼 설정 조회로 판매자가 끈 섹션을 건너뛰고, 상품 주요정보(상품정보제공고시)의 상품군(1~40)과 군별 입력 항목도 조회
프로젝트	`create_project`	프로젝트 생성
키체인	`list_api_scopes`, `list_keychains`, `create_keychain`, `delete_keychain`, `get_commerce_keys`	API 키 발급/조회 (source 파라미터로 커머스/결제 구분)
상품	`list_products`, `get_product`, `create_product`, `update_product`, `delete_product`, `create_test_products`	상품 CRUD. `image_paths`로 로컬 사진 경로를 주면 업로드까지 처리, 구독(`subscription_setting_id`)·배송정책(`delivery_shipping_id`) 연결, 상세설명 블록(`content_blocks`), 디지털 지급(`digital_provisioning_type`), 환불정책 노출(`refund_policy_expose_type`) 지원
결제설정	`get_payment_settings`, `activate_payment_method`, `set_sandbox_mode`, `update_payment_resource`, `set_payment_mode`, `browser_select_payment_method`	PG·결제수단 설정
위젯	`list_widgets`, `get_widget`, `create_widget`, `get_widget_default_styles`, `configure_widget`, `update_widget`, `delete_widget`	결제위젯 CRUD
쇼핑몰설정	`get_mall_setting`, `update_mall_setting`	커머스 몰 기본 설정 조회·변경

상품·상세설명 블록·디지털 코드풀·카테고리·이미지 도구는 원격(OAuth) 프로파일에도 포함됩니다. 결제설정·키체인·자격증명 도구는 원격에서 제외됩니다 — 근거와 현재 상태는 원격 커넥터 문서를 보세요.

Commerce Tools — 13개 (stdio 전용, opt-in)

AI 에이전트가 커머스 API를 호출하여 쇼핑몰 기능을 구현할 수 있는 도구입니다. 활성화: 환경변수 BOOTPAY_COMMERCE_ENABLED=true 설정 후 실행.

카테고리	Tools	Description
인증	`set_commerce_credentials`	clientKey/secretKey 설정·검증
스토어	`commerce_get_store`, `commerce_get_store_detail`	가맹점 정보 조회
상품	`commerce_get_products`, `commerce_get_product`, `commerce_create_product`, `commerce_update_product`	상품 CRUD
회원	`commerce_login`, `commerce_get_session`, `commerce_logout`	회원 로그인·세션 관리
리뷰	`commerce_get_reviews`, `commerce_get_review_stats`	리뷰 조회·통계
상태	`commerce_status`	Commerce API 상태 확인

Supported Platforms & SDKs

Client SDKs

Platform	Package
Web (NPM)	`@bootpay/client-js`
Web (CDN)	`bootpay-{version}.min.js`
Android (Kotlin/Java)	`kr.co.bootpay:android`
iOS (Swift/ObjC)	`pod 'Bootpay'`
Flutter	`bootpay_flutter`
React Native	`react-native-bootpay-api`

Server SDKs

Language	Package
Node.js	`@bootpay/backend-js`
Python	`bootpay-backend`
Java / Kotlin	`kr.co.bootpay:backend`
Ruby	`bootpay`
Go	`github.com/bootpay/backend-go/v2`
.NET (C#)	`Bootpay`
PHP	`bootpay/backend-php`

Documentation Categories

Category	Content
`payment`	일반결제 — SDK 설치, 결제창, 서버 검증, 취소/환불
`billing`	정기결제 — 빌링키 발급, 자동결제, 예약결제, 해지
`subscription`	구독관리 — 플랜 생성, 갱신, 해지, 과금
`order`	주문관리 — 주문 생성, 취소, 반품
`customer`	고객관리 — 고객 등록, 그룹, 조회
`product`	상품관리 — 상품 CRUD, 옵션, 카테고리
`webhook`	웹훅 — 설정, 이벤트, 처리, 재시도 정책
`guide`	시작하기 — 키 발급, 환경설정, 개요
`integration`	연동 — 에러코드, 마이그레이션, 호환성
`invoice`	링크페이 — 결제 링크 생성, 알림
`recipes`	레시피 — 업종별 연동 시나리오
`architecture`	아키텍처 — 결제 플로우, 데이터 모델

Ask AI

MCP를 연결한 후 AI에게 이렇게 물어보세요:

부트페이 결제 연동 어떻게 해?
React에서 카드결제 연동하는 전체 코드 알려줘
Flutter에서 정기결제(빌링키) 발급 방법 알려줘
기존 프로젝트에 월 구독결제 붙여줘 (매일 배치로 결제, 같은 달 두 번 결제 방지, 성공 시에만 다음 달 이용 개방)
Next.js에서 결제 검증 서버 코드 작성해줘
웹훅 설정은 어떻게 하는거야?
결제위젯으로 카카오페이, 네이버페이 연동해줘
토스페이먼츠 PG로 가상계좌 결제 구현해줘

Architecture

두 가지 전송 방식을 지원하며, 도구 범위가 다릅니다:

 ┌─────────────────────┐
│ AI Coding Tool │
│ (Claude, Cursor, │
│ Windsurf, Cline, │
│ Codex, Gemini) │
└──────────┬──────────┘
│
┌─────────┴─────────┐
▼ ▼
[HTTP] [stdio]
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────────────┐
│ Cloudflare │ │ npx -y @bootpay/mcp@latest │
│ Workers │ │ │
│ bootpay-docs-mcp │ │ ┌─ Docs ( 8 tools) │
│ .workers.dev/mcp │ │ ├─ Admin (67 tools) │
│ │ │ └─ Commerce (13 tools)* │
│ Docs only │ │ │
│ (8 tools) │ │ * opt-in │
└────────┬─────────┘ └────────────────────────────┘
│
┌────────┴─────────┐
│ KV │
│ 120+ docs │
└──────────────────┘

전송	Docs (8)	Admin (67)	Commerce (13)	노출 도구 수
HTTP (Cloudflare Workers)	O	—	—	8
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	75 (opt-in 포함 88)

stdio 의 detect_project_stack 은 root_path 로 로컬 파일시스템을 직접 훑습니다. HTTP 에서는 같은 도구가 노출되지만 파일을 볼 수 없으므로 files/file_contents 를 직접 넘겨야 합니다.

Stack: Cloudflare Workers + KV + MCP SDK + Streamable HTTP + stdio

Links

Bootpay Developer Docs
Bootpay Admin
Bootpay Official
MCP Protocol Specification
llms.txt — LLM-optimized documentation
사진과 설명으로 상품 올리기 — 판매자용 상품등록 가이드 (비개발자 대상)
원격 커넥터(ChatGPT · Claude) 연결 — OAuth 원격 연결 현황·검증 절차

Keywords

Bootpay, 부트페이, Korean payment gateway, 한국 결제, PG 연동, payment integration, MCP server, Model Context Protocol, AI coding assistant, LLM, Claude, Cursor, Windsurf, Cline, GitHub Copilot, 나이스페이, NICE, 토스페이먼츠, Toss Payments, KG이니시스, KG Inicis, NHN KCP, 카카오페이, Kakao Pay, 네이버페이, Naver Pay, 페이코, PAYCO, 다날, Danal, 정기결제, recurring payment, billing key, 빌링키, subscription, 구독결제, 결제위젯, payment widget, 결제 연동, checkout, 간편결제, easy payment, Cloudflare Workers

Bootpay MCP Server

Korea's payment integration, now accessible to AI. 한국 결제 연동을 AI가 직접 수행할 수 있도록 하는 MCP 서버입니다.

🛍️ 개발자가 아니라 판매자라면 — 코드 없이 사진과 설명만으로 상품을 등록하는 방법은 사진과 설명으로 상품 올리기를 보세요.

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

"이 레포 참조해서 부트페이 결제 연동해줘" 라는 요청을 받고 이 문서를 읽고 있다면:

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

MCP가 "연결됨"이라도 전송 방식에 따라 사용 가능한 도구가 다릅니다:

전송 방식	Docs (8개)	Admin (67개)	Commerce (13개)	키 자동 조회	다음 단계
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	O	→ 아래 "stdio 모드" 참고
HTTP (`bootpay-docs-mcp.rupy1014.workers.dev/mcp`)	O	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)
MCP 없음 (저장소 참조만)	—	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)

확인 방법:

# Codex
codex mcp list # bootpay 서버가 보이는지 확인# Claude Code
claude mcp list # bootpay 서버가 보이는지 확인# Gemini CLI
gemini mcp list # bootpay 서버가 보이는지 확인

서버가 있다면 버전도 확인하세요 — 옛 버전은 낡은 답을 냅니다:

npx -y @bootpay/mcp@latest --version # 지금 실행되는 버전
npm view @bootpay/mcp version # npm 의 최신 버전

두 값이 다르면 사용자에게 최신 버전으로 다시 설치하도록 안내하세요 → Quick Start / 0단계: 설치

stdio로 연결된 경우: browser_login → list_keychains(또는 create_keychain)으로 키를 자동 조회하세요. 사용자에게 키를 직접 물어보지 마세요. HTTP 또는 MCP 없음: 사용자에게 키를 요청해야 합니다. 아래 "MCP 없이 이 저장소만 참조하는 경우" 섹션의 정확한 키 이름을 사용하세요. 서버가 목록에 없으면? MCP 설정 후 반드시 새 세션을 시작하세요. 설정만으로는 현재 세션에 반영되지 않습니다. 설정할 때는 반드시 @latest 를 붙이세요 — npx -y @bootpay/mcp@latest. 버전을 생략하면 npx 캐시에 남은 옛 사본이 실행됩니다. HTTP로 연결했는데 Admin 도구를 쓰고 싶다면? stdio(npx -y @bootpay/mcp@latest)로 재설정 후 새 세션을 시작하세요.

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

중요: 문서(search_docs)를 먼저 읽지 마세요. Admin 도구로 실제 프로젝트 컨텍스트를 먼저 수집하세요.

1. get_integration_context() → 인증/프로젝트/결제설정/위젯/키체인 한 번에 확인 ⭐
→ readiness.ready = true이면 Step 5로 이동
→ readiness.blockers가 있으면 아래 순서로 해결:
2. browser_login → Bootpay 로그인 (미인증 시)
3. browser_select_project → 프로젝트 선택 (미선택 시)
4. create_keychain(targets=["core"]) → 결제용 API 키 발급 (키체인 없을 때)
→ client_key, secret_key 반환 → .env에 즉시 저장
5. get_sdk_versions → 최신 SDK 버전 확인
6. search_docs → get_doc → 관련 문서 조회 (보완 참조)
7. 코드 작성 → .env 환경변수 참조 (키를 코드에 하드코딩 금지)

서버 인증: client_key/secret_key 기반 Basic Auth. getAccessToken() 불필요.

MCP 없이 이 저장소만 참조하는 경우

🚫 API 키를 추측하거나 임의로 생성하지 마세요.692e4c6da0ba315535c9dedf 같은 랜덤 문자열을 .env에 넣으면 100% 실패합니다. Bootpay API 키는 Bootpay 서버가 발급한 값만 유효합니다.

아래 파일을 순서대로 읽고 코드를 작성하세요:

순서	파일	내용
1	`AGENTS.md`	AI 에이전트용 지시 — 금지 행위, 금액 규칙, 통합결제창 판단
2	`SETUP_GUIDE.md`	MCP 최신 설치 · Admin CLI로 키 조회 또는 수동 설정
3	`SDK_VERSIONS.md`	최신 SDK 버전 (v2 5.x) — 3.x/4.x는 deprecated
4	`llms.txt`	핵심 규칙, API 도메인, SDK 패키지, 결제 흐름
5	`examples/`	플랫폼별 전체 코드 예제 (12개)

⚠️MCP 없이는 API 키를 AI가 자동 조회할 수 없습니다. 사용자에게 반드시 아래 안내를 하세요:
admin.bootpay.co.kr → 프로젝트 → 개발자 설정 → API 연동키(결제) 탭에서 아래 3개 키를 확인하여 .env에 입력
또는 stdio 모드로 MCP를 연결하면 list_keychains로 자동 조회 가능
이 안내 없이 키를 추측하거나, 빈 값/.env 없이 코드를 생성하면 실패합니다.

사용자에게 요청할 키 2개 (정확한 이름)

Admin UI(admin.bootpay.co.kr)에서 보이는 라벨과 .env 변수명이 다릅니다. 반드시 아래 매핑을 사용하세요:

Admin UI 라벨	.env 변수명	용도
Client Key (= REST API Key)	`BOOTPAY_CLIENT_KEY`	프론트엔드 SDK 결제창 호출 + 서버 Basic Auth 공통
Secret Key (= Private Key)	`BOOTPAY_SECRET_KEY`	서버 Basic Auth 인증 (비밀)

프론트엔드 빌드 도구에 따라 BOOTPAY_CLIENT_KEY 앞에 접두사를 붙입니다:
Vite → VITE_BOOTPAY_CLIENT_KEY
Next.js → NEXT_PUBLIC_BOOTPAY_CLIENT_KEY
Create React App → REACT_APP_BOOTPAY_CLIENT_KEY

# .env 예시 — create_keychain 또는 Admin UI에서 확인한 값을 입력
BOOTPAY_CLIENT_KEY= # Client Key (프론트엔드 SDK + 서버 Basic Auth 공통)
BOOTPAY_SECRET_KEY= # Secret Key (서버 전용, 프론트엔드 노출 금지)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

잘못된 이름	올바른 이름	비고
`BOOTPAY_REST_APP_ID`	`BOOTPAY_CLIENT_KEY`	"REST API Key"는 Admin UI 라벨일 뿐, 변수명이 아님
`BOOTPAY_PRIVATE_KEY`	`BOOTPAY_SECRET_KEY`	Bootpay에서는 "Secret Key"로 통일
`BOOTPAY_API_KEY`	`BOOTPAY_CLIENT_KEY`	존재하지 않는 변수명
`getAccessToken()`	Basic Auth	v2에서는 토큰 발급 불필요. client_key:secret_key로 직접 인증

핵심 규칙

SDK v2 (5.x) only — bootpay-3.x.x.min.js, bootpay-4.x.x.min.js는 v1(deprecated)이며 동작하지 않음
결제는 프론트엔드에서 시작 — 국내 PG 규정. 백엔드에서 결제를 시작하는 코드 금지
서버승인(분리승인)이 기본 — Bootpay.requestPayment 호출 시 extra.separately_confirmed: true 설정. confirm 시점에 receipt_id를 서버로 전달하면 서버가 confirmPayment()로 최종 승인하고 리턴값으로 금액을 확인 (별도 결제검증 조회 불필요). done 이벤트만 처리하는 클라이언트 승인 코드는 유실 위험이 있어 비권장
웹훅 보완 필수 — 클라이언트 결과 처리는 브라우저 이탈로 유실될 수 있음. 웹훅 엔드포인트를 함께 구현 (부트페이 발신 IP 223.130.82.0/24만 허용 + receiptPayment 재검증 + 멱등 처리)
API 키는 Admin CLI로 발급 → .env에 기록 — placeholder·추측값·랜덤 문자열 금지. create_keychain 또는 list_keychains 반환값만 사용
서버 인증은 Basic Auth — client_key/secret_key 기반. getAccessToken() 불필요
Secret Key는 서버 전용 — 절대 프론트엔드에 노출하지 않을 것

오프라인 · MCP 없이 사용하기

방법 1 — 최신 패키지를 파일로 받아서 설치 (사내망 등 npx 를 못 쓰는 환경)

npm pack @bootpay/mcp@latest # 최신 버전 .tgz 가 현재 폴더에 떨어집니다
npm install -g ./bootpay-mcp-*.tgz # 받은 파일로 전역 설치
bootpay-mcp --version # 설치된 버전 확인

GitHub Releases 의 고정 버전 파일을 받지 마세요. 최신 버전은 항상 npm 에 있습니다. 버전을 고정해야 한다면 npm view @bootpay/mcp versions 로 목록을 보고 @bootpay/mcp@2.1.0 처럼 명시하세요.

방법 2 — 문서만 AI 에게 전달 (npm/git 불필요, MCP 도구는 못 씀)

main.tar.gz 다운로드
AI 도구에 파일 첨부
"부트페이 결제 연동해줘"라고 요청

방법 3 — git clone (문서 참조용)

git clone https://github.com/bootpay/bootpay-mcp.git
# AGENTS.md, llms.txt, SDK_VERSIONS.md, SETUP_GUIDE.md 를 AI에게 전달

방법 2·3 은 문서만 전달합니다. Admin 도구(로그인·키 발급·코드 생성)는 stdio 로 MCP 를 붙여야 씁니다. 이 경우 AI 는 API 키를 자동 조회할 수 없으니, 아래 "MCP 없이 이 저장소만 참조하는 경우" 절을 따르세요.

About This Project

AI 코딩 도구(Claude, Cursor, Windsurf, Cline, GitHub Copilot 등)에서 Bootpay 결제·커머스를 연동할 수 있는 통합 Model Context Protocol (MCP) 서버입니다.

Docs (문서 검색·SDK 버전·트러블슈팅) + Admin (관리자 설정·PG·위젯·코드 생성) + Commerce (스토어·상품·회원) — 하나의 MCP 서버로 제공합니다.

stdio 로 붙으면 기본 75개(Docs 8 + Admin 67), Commerce 를 켜면 88개 도구가 노출됩니다. HTTP 로 붙으면 Docs 8개만 노출됩니다.

Supported PG & Payment Methods

Bootpay는 국내 주요 PG사와 간편결제를 통합 지원합니다:

PG사	코드	지원 결제
나이스페이 (NICE)	`nicepay`	카드, 계좌이체, 가상계좌, 휴대폰
토스페이먼츠 (Toss Payments)	`tosspayments`	카드, 계좌이체, 가상계좌, 휴대폰
KG이니시스 (KG Inicis)	`inicis`	카드, 계좌이체, 가상계좌, 휴대폰
NHN KCP	`kcp`	카드, 계좌이체, 가상계좌, 휴대폰
카카오페이 (Kakao Pay)	`kakao`	간편결제
네이버페이 (Naver Pay)	`naverpay`	간편결제
페이코 (PAYCO)	`payco`	간편결제
토스페이 (Toss Pay)	`tosspay`	간편결제
다날 (Danal)	`danal`	휴대폰 소액결제

결제 유형: 일반결제 (카드/계좌이체/가상계좌/휴대폰) · 정기결제 (빌링키) · 본인인증 · 에스크로 · 현금영수증

Quick Start

두 가지 연결 방식을 지원합니다:

방식	특징	추천 환경
HTTP (Streamable HTTP)	설치 불필요, 원격 서버	Cursor, Windsurf, Cline, 웹 기반
npm (stdio)	로컬 실행, Admin·Commerce 도구 사용 가능	Claude Desktop, Claude Code, Codex, Gemini CLI

0단계: 설치 — 반드시 최신 버전으로

stdio 설정에는 항상 @latest 를 붙이세요.

npx -y @bootpay/mcp@latest

⚠️@latest 를 빼면 예전에 받아둔 사본이 계속 실행됩니다.npx @bootpay/mcp 처럼 버전을 생략하면 npx 는 캐시(~/.npm/_npx/)에 남아 있는 사본을 먼저 씁니다. 한 번 받아둔 사람은 새 버전이 나와도 옛 버전을 계속 실행하게 되고, 그 사이에 고쳐진 것들이 전달되지 않습니다. 실제로 최근 릴리스에서 문서 검색이 조용히 빈 결과를 내던 문제 · 낡은 SDK 버전표 · 일부 도구가 인자를 거절하던 문제가 고쳐졌습니다. 옛 버전을 쓰면 AI 가 그 낡은 정보로 코드를 만듭니다.

지금 무엇이 실행되는지 확인하세요:

npm view @bootpay/mcp version # npm 에 올라온 최신 버전
npx -y @bootpay/mcp@latest --version # 실행될 서버의 버전 (v2.1.1 이상)

--version 은 v2.1.1부터 지원합니다. 그보다 낮은 버전이면 이 명령이 서버를 띄운 채 멈춥니다. 그럴 때는 Ctrl+C 로 끄고 — 그것 자체가 옛 버전이라는 신호이므로 — 아래 캐시 비우기를 바로 실행하세요.

두 값이 같으면 최신입니다. 다르면 캐시를 비우고 다시 받으세요:

npx clear-npx-cache # npx 캐시 비우기
rm -rf ~/.npm/_npx # 위 명령이 안 되면 (macOS/Linux)

Windows PowerShell:

Remove-Item-Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

항상 같은 버전을 고정해서 쓰고 싶다면 전역 설치도 됩니다. 대신 업데이트는 직접 해야 합니다:

npm install -g @bootpay/mcp@latest # 설치 · 업데이트 모두 이 명령
bootpay-mcp --version # 설치된 버전 확인

이 경우 MCP 설정의 command 는 npx 대신 bootpay-mcp 를 쓰고 args 는 비웁니다.

전제조건 — Node.js 18 이상

node -v # v18.0.0 이상이어야 합니다

node 명령이 없다면 https://nodejs.org 에서 LTS 를 먼저 설치하고, 터미널을 새로 여세요 (PATH 반영). Windows 는 설치 후 PowerShell 을 새로 열어야 node 가 잡힙니다.

설정을 저장한 뒤에는 AI 클라이언트를 완전히 종료하고 다시 켜세요. 설정 파일만 고치면 현재 세션에는 반영되지 않습니다. 도구 목록에 부트페이 도구가 안 보이면 대부분 이것 때문입니다. 확인: claude mcp list / codex mcp list / gemini mcp list

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows):

npm (stdio) — 추천:

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP (원격):

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["mcp-remote", "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"]
}
}
}

Claude Code (CLI)

# npm (stdio)
claude mcp add bootpay-docs -- npx -y @bootpay/mcp@latest
# HTTP
claude mcp add bootpay-docs --transport http https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

Cursor

Settings → MCP Servers → Add:

{
"bootpay-docs": {
"url": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}

Codex (OpenAI)

~/.codex/config.toml:

stdio (권장, 전체 도구):

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]

HTTP (Docs 도구만, 설치 불필요):

[mcp_servers.bootpay]
url = "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"

Commerce 도구 활성화:

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]
[mcp_servers.bootpay.env]
BOOTPAY_COMMERCE_CLIENT_KEY = "YOUR_CLIENT_KEY"BOOTPAY_COMMERCE_SECRET_KEY = "YOUR_SECRET_KEY"

또는 CLI로 추가:

codex mcp add bootpay -- npx -y @bootpay/mcp@latest

설정 후 반드시 확인:
현재 Codex 세션을 종료하고 새 세션을 시작하세요
codex mcp list로 bootpay 서버가 보이는지 확인
보이지 않으면 ~/.codex/config.toml의 [mcp_servers.bootpay] 섹션을 재확인

Gemini CLI

~/.gemini/settings.json:

stdio (권장, 전체 도구):

{
"mcpServers": {
"bootpay": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP Streaming:

{
"mcpServers": {
"bootpay": {
"httpUrl": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}
}

또는 CLI로 추가:

gemini mcp add bootpay npx -y @bootpay/mcp@latest

주의: Gemini CLI는 서버 이름에 언더스코어(_)를 사용하면 보안 정책 파싱 오류가 발생합니다. bootpay-docs ✅ / bootpay_docs ❌

Windsurf / Cline / Other MCP Clients

Streamable HTTP endpoint:

https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

What AI Can Do with This MCP

MCP를 연결하면 AI가 다음을 직접 수행합니다:

사용자: "React에서 부트페이 카드결제 연동해줘"
AI 내부 동작:
1. get_sdk_versions → 최신 SDK 버전 확인 (v2 5.x)
2. get_setup_checklist → Client Key + 환경 설정 안내
3. search_docs → get_doc → payment/request 문서 조회
4. 코드 작성 → 문서 기반, 정확한 버전 사용

Docs Tools — 8개 (HTTP + stdio)

Tool	Description
`detect_project_stack`	프로젝트 스택 판정 — 클라이언트 플랫폼·웹 프레임워크·서버 언어·실행 환경(상시/서버리스). 모노레포면 앱마다 판정하고 "서버 1회 + 클라이언트 N회" 호출 계획을 반환
`get_sdk_versions`	모든 SDK 최신 버전 조회 (Web, Android, iOS, Flutter, React Native, 서버 7개 언어)
`search_docs`	120+ 개발자 문서 검색 (12 카테고리)
`get_doc`	특정 문서 전체 마크다운 조회
`list_docs`	카테고리별 문서 목록
`get_setup_checklist`	연동 환경 설정 체크리스트 (API 키, SDK 설치, .env)
`get_troubleshooting`	문제 해결 가이드 (onboarding, sandbox, webhook, billing, subscription, error, cancel, cors, csp, open-type, mobile, widget, unified, certification)
`get_csp_allowlist`	CSP(frame-src) 허용 PG 도메인 목록 + 프레임워크별 설정 스니펫 생성
`get_cs_guide`	고객응대(CS) 매뉴얼 검색

Prompt	Description
`integration-action-plan`	결제유형 × 플랫폼별 6단계 연동 액션 플랜

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Bootpay가 처음이라면 관리자 화면 대신 AI에게 전부 맡기세요. stdio 방식(npx -y @bootpay/mcp@latest)으로 연결하면 Admin 도구 67개가 활성화됩니다.

사용자: "부트페이 결제 연동하고 싶어. 처음이야"
AI 내부 동작:
1. browser_login → 브라우저 팝업으로 로그인
2. create_seller → 셀러(가맹점) 생성 + 기본 프로젝트 자동 생성
3. browser_select_project → 프로젝트 선택
4. activate_payment_method → 나이스페이 카드결제 활성화
5. set_sandbox_mode → 테스트 모드 설정
6. create_keychain(targets=["core"]) → 결제용 API 키 발급 (client_key, secret_key)
7. search_docs + get_doc → 최신 연동 문서 참조
8. 코드 생성 → 발급한 키를 .env에 설정, 코드에서 환경변수 참조

⚠️ 키를 코드에 직접 삽입하지 마세요. 발급한 키는 반드시 .env 파일에 저장하고, 코드에서는 환경변수로 참조합니다. Secret Key는 서버 .env에만 저장하세요. secret_key는 발급 시 1회만 평문으로 표시됩니다.

HTTP 방식에서는 Admin 도구를 사용할 수 없습니다. 프로젝트 설정이 필요하면 반드시 stdio(npx @bootpay/mcp@latest)를 사용하세요.

Admin Tools — 67개 (stdio 전용)

관리자(admin.bootpay.co.kr)의 설정을 AI가 직접 조회·변경할 수 있는 도구입니다. npx -y @bootpay/mcp@latest로 실행하면 자동 활성화됩니다.

카테고리	Tools	Description
코드생성	`generate_payment_code`, `generate_commerce_code`	프리플라이트(인증·키체인·결제수단·SDK 확인) + 클라이언트/서버 코드 원스톱 생성. `payment_type`: `payment`(일반) / `billing`(빌링키) / `subscription`(구독 — 회차·배치·무료체험·해지) / `widget` / `auth`, `scheduler`: `cron` / `http_trigger`(서버리스)
컨텍스트	`get_integration_context`, `get_commerce_context`	인증·프로젝트·결제설정·위젯·키체인을 한 번에 조회 (`readiness.blockers` 반환)
인증	`login`, `browser_login`, `logout`, `list_projects`, `switch_project`, `browser_select_project`, `set_token`, `get_auth_status`	로그인, 프로젝트 전환, 토큰 설정·상태 확인
셀러	`create_seller`, `search_sellers`, `get_seller`, `update_seller`	셀러(가맹점) CRUD
상세설명 블록	`list_content_templates`, `create_content_template`, `delete_content_template`, `list_content_blocks`, `create_content_block`, `update_content_block`, `delete_content_block`, `list_content_block_products`	상세설명을 블록으로 구성. 시작 템플릿(서버 저장분 + MCP 내장 스타터)과 여러 상품이 공유하는 공용 블록 관리. `content_type=4`일 때만 블록이 저장되며, HTML(`content`)은 서버가 컴파일해 채웁니다
디지털 코드풀	`list_digital_codes`, `register_digital_codes`, `disable_digital_code`	시리얼·라이센스 번호 일괄 등록/조회/폐기. `code_distribution_mode="pool"` 상품에서 구매자마다 다른 코드를 발급할 때 사용 (한 번에 최대 5,000개)
이미지	`upload_product_images`	로컬 경로·URL·base64 → Bootpay CDN 업로드 (최대 10장, 장당 10MB)
카테고리	`list_categories`, `create_category`, `update_category`, `delete_category`, `reorder_categories`	카테고리 CRUD. `path="상의 > 티셔츠 > 반팔"`로 계층 일괄 생성, 삭제는 `confirm` 확인 게이트
부속설정	`list_subscription_settings`, `list_delivery_shippings`, `create_subscription_setting`, `create_delivery_shipping`, `list_delivery_shipping_bundles`, `get_product_form_setting`, `get_product_info_notice_forms`	상품에 연결할 구독 설정·배송정책 ID 확보. 정책이 하나도 없는 프로젝트에서는 생성까지 가능 — 배송비·주기 같은 값이 빠지면 저장 대신 `need_answer` 로 무엇을 물어야 하는지 돌려줍니다(금액을 추측해 저장하지 않습니다). 폼 설정 조회로 판매자가 끈 섹션을 건너뛰고, 상품 주요정보(상품정보제공고시)의 상품군(1~40)과 군별 입력 항목도 조회
프로젝트	`create_project`	프로젝트 생성
키체인	`list_api_scopes`, `list_keychains`, `create_keychain`, `delete_keychain`, `get_commerce_keys`	API 키 발급/조회 (source 파라미터로 커머스/결제 구분)
상품	`list_products`, `get_product`, `create_product`, `update_product`, `delete_product`, `create_test_products`	상품 CRUD. `image_paths`로 로컬 사진 경로를 주면 업로드까지 처리, 구독(`subscription_setting_id`)·배송정책(`delivery_shipping_id`) 연결, 상세설명 블록(`content_blocks`), 디지털 지급(`digital_provisioning_type`), 환불정책 노출(`refund_policy_expose_type`) 지원
결제설정	`get_payment_settings`, `activate_payment_method`, `set_sandbox_mode`, `update_payment_resource`, `set_payment_mode`, `browser_select_payment_method`	PG·결제수단 설정
위젯	`list_widgets`, `get_widget`, `create_widget`, `get_widget_default_styles`, `configure_widget`, `update_widget`, `delete_widget`	결제위젯 CRUD
쇼핑몰설정	`get_mall_setting`, `update_mall_setting`	커머스 몰 기본 설정 조회·변경

상품·상세설명 블록·디지털 코드풀·카테고리·이미지 도구는 원격(OAuth) 프로파일에도 포함됩니다. 결제설정·키체인·자격증명 도구는 원격에서 제외됩니다 — 근거와 현재 상태는 원격 커넥터 문서를 보세요.

Commerce Tools — 13개 (stdio 전용, opt-in)

AI 에이전트가 커머스 API를 호출하여 쇼핑몰 기능을 구현할 수 있는 도구입니다. 활성화: 환경변수 BOOTPAY_COMMERCE_ENABLED=true 설정 후 실행.

카테고리	Tools	Description
인증	`set_commerce_credentials`	clientKey/secretKey 설정·검증
스토어	`commerce_get_store`, `commerce_get_store_detail`	가맹점 정보 조회
상품	`commerce_get_products`, `commerce_get_product`, `commerce_create_product`, `commerce_update_product`	상품 CRUD
회원	`commerce_login`, `commerce_get_session`, `commerce_logout`	회원 로그인·세션 관리
리뷰	`commerce_get_reviews`, `commerce_get_review_stats`	리뷰 조회·통계
상태	`commerce_status`	Commerce API 상태 확인

Supported Platforms & SDKs

Client SDKs

Platform	Package
Web (NPM)	`@bootpay/client-js`
Web (CDN)	`bootpay-{version}.min.js`
Android (Kotlin/Java)	`kr.co.bootpay:android`
iOS (Swift/ObjC)	`pod 'Bootpay'`
Flutter	`bootpay_flutter`
React Native	`react-native-bootpay-api`

Server SDKs

Language	Package
Node.js	`@bootpay/backend-js`
Python	`bootpay-backend`
Java / Kotlin	`kr.co.bootpay:backend`
Ruby	`bootpay`
Go	`github.com/bootpay/backend-go/v2`
.NET (C#)	`Bootpay`
PHP	`bootpay/backend-php`

Documentation Categories

Category	Content
`payment`	일반결제 — SDK 설치, 결제창, 서버 검증, 취소/환불
`billing`	정기결제 — 빌링키 발급, 자동결제, 예약결제, 해지
`subscription`	구독관리 — 플랜 생성, 갱신, 해지, 과금
`order`	주문관리 — 주문 생성, 취소, 반품
`customer`	고객관리 — 고객 등록, 그룹, 조회
`product`	상품관리 — 상품 CRUD, 옵션, 카테고리
`webhook`	웹훅 — 설정, 이벤트, 처리, 재시도 정책
`guide`	시작하기 — 키 발급, 환경설정, 개요
`integration`	연동 — 에러코드, 마이그레이션, 호환성
`invoice`	링크페이 — 결제 링크 생성, 알림
`recipes`	레시피 — 업종별 연동 시나리오
`architecture`	아키텍처 — 결제 플로우, 데이터 모델

Ask AI

MCP를 연결한 후 AI에게 이렇게 물어보세요:

부트페이 결제 연동 어떻게 해?
React에서 카드결제 연동하는 전체 코드 알려줘
Flutter에서 정기결제(빌링키) 발급 방법 알려줘
기존 프로젝트에 월 구독결제 붙여줘 (매일 배치로 결제, 같은 달 두 번 결제 방지, 성공 시에만 다음 달 이용 개방)
Next.js에서 결제 검증 서버 코드 작성해줘
웹훅 설정은 어떻게 하는거야?
결제위젯으로 카카오페이, 네이버페이 연동해줘
토스페이먼츠 PG로 가상계좌 결제 구현해줘

Architecture

두 가지 전송 방식을 지원하며, 도구 범위가 다릅니다:

 ┌─────────────────────┐
│ AI Coding Tool │
│ (Claude, Cursor, │
│ Windsurf, Cline, │
│ Codex, Gemini) │
└──────────┬──────────┘
│
┌─────────┴─────────┐
▼ ▼
[HTTP] [stdio]
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────────────┐
│ Cloudflare │ │ npx -y @bootpay/mcp@latest │
│ Workers │ │ │
│ bootpay-docs-mcp │ │ ┌─ Docs ( 8 tools) │
│ .workers.dev/mcp │ │ ├─ Admin (67 tools) │
│ │ │ └─ Commerce (13 tools)* │
│ Docs only │ │ │
│ (8 tools) │ │ * opt-in │
└────────┬─────────┘ └────────────────────────────┘
│
┌────────┴─────────┐
│ KV │
│ 120+ docs │
└──────────────────┘

전송	Docs (8)	Admin (67)	Commerce (13)	노출 도구 수
HTTP (Cloudflare Workers)	O	—	—	8
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	75 (opt-in 포함 88)

stdio 의 detect_project_stack 은 root_path 로 로컬 파일시스템을 직접 훑습니다. HTTP 에서는 같은 도구가 노출되지만 파일을 볼 수 없으므로 files/file_contents 를 직접 넘겨야 합니다.

Stack: Cloudflare Workers + KV + MCP SDK + Streamable HTTP + stdio

Links

Bootpay Developer Docs
Bootpay Admin
Bootpay Official
MCP Protocol Specification
llms.txt — LLM-optimized documentation
사진과 설명으로 상품 올리기 — 판매자용 상품등록 가이드 (비개발자 대상)
원격 커넥터(ChatGPT · Claude) 연결 — OAuth 원격 연결 현황·검증 절차

Keywords

Bootpay, 부트페이, Korean payment gateway, 한국 결제, PG 연동, payment integration, MCP server, Model Context Protocol, AI coding assistant, LLM, Claude, Cursor, Windsurf, Cline, GitHub Copilot, 나이스페이, NICE, 토스페이먼츠, Toss Payments, KG이니시스, KG Inicis, NHN KCP, 카카오페이, Kakao Pay, 네이버페이, Naver Pay, 페이코, PAYCO, 다날, Danal, 정기결제, recurring payment, billing key, 빌링키, subscription, 구독결제, 결제위젯, payment widget, 결제 연동, checkout, 간편결제, easy payment, Cloudflare Workers

Bootpay MCP Server

Korea's payment integration, now accessible to AI. 한국 결제 연동을 AI가 직접 수행할 수 있도록 하는 MCP 서버입니다.

🛍️ 개발자가 아니라 판매자라면 — 코드 없이 사진과 설명만으로 상품을 등록하는 방법은 사진과 설명으로 상품 올리기를 보세요.

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

"이 레포 참조해서 부트페이 결제 연동해줘" 라는 요청을 받고 이 문서를 읽고 있다면:

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

MCP가 "연결됨"이라도 전송 방식에 따라 사용 가능한 도구가 다릅니다:

전송 방식	Docs (8개)	Admin (67개)	Commerce (13개)	키 자동 조회	다음 단계
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	O	→ 아래 "stdio 모드" 참고
HTTP (`bootpay-docs-mcp.rupy1014.workers.dev/mcp`)	O	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)
MCP 없음 (저장소 참조만)	—	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)

확인 방법:

# Codex
codex mcp list # bootpay 서버가 보이는지 확인# Claude Code
claude mcp list # bootpay 서버가 보이는지 확인# Gemini CLI
gemini mcp list # bootpay 서버가 보이는지 확인

서버가 있다면 버전도 확인하세요 — 옛 버전은 낡은 답을 냅니다:

npx -y @bootpay/mcp@latest --version # 지금 실행되는 버전
npm view @bootpay/mcp version # npm 의 최신 버전

두 값이 다르면 사용자에게 최신 버전으로 다시 설치하도록 안내하세요 → Quick Start / 0단계: 설치

stdio로 연결된 경우: browser_login → list_keychains(또는 create_keychain)으로 키를 자동 조회하세요. 사용자에게 키를 직접 물어보지 마세요. HTTP 또는 MCP 없음: 사용자에게 키를 요청해야 합니다. 아래 "MCP 없이 이 저장소만 참조하는 경우" 섹션의 정확한 키 이름을 사용하세요. 서버가 목록에 없으면? MCP 설정 후 반드시 새 세션을 시작하세요. 설정만으로는 현재 세션에 반영되지 않습니다. 설정할 때는 반드시 @latest 를 붙이세요 — npx -y @bootpay/mcp@latest. 버전을 생략하면 npx 캐시에 남은 옛 사본이 실행됩니다. HTTP로 연결했는데 Admin 도구를 쓰고 싶다면? stdio(npx -y @bootpay/mcp@latest)로 재설정 후 새 세션을 시작하세요.

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

중요: 문서(search_docs)를 먼저 읽지 마세요. Admin 도구로 실제 프로젝트 컨텍스트를 먼저 수집하세요.

1. get_integration_context() → 인증/프로젝트/결제설정/위젯/키체인 한 번에 확인 ⭐
→ readiness.ready = true이면 Step 5로 이동
→ readiness.blockers가 있으면 아래 순서로 해결:
2. browser_login → Bootpay 로그인 (미인증 시)
3. browser_select_project → 프로젝트 선택 (미선택 시)
4. create_keychain(targets=["core"]) → 결제용 API 키 발급 (키체인 없을 때)
→ client_key, secret_key 반환 → .env에 즉시 저장
5. get_sdk_versions → 최신 SDK 버전 확인
6. search_docs → get_doc → 관련 문서 조회 (보완 참조)
7. 코드 작성 → .env 환경변수 참조 (키를 코드에 하드코딩 금지)

서버 인증: client_key/secret_key 기반 Basic Auth. getAccessToken() 불필요.

MCP 없이 이 저장소만 참조하는 경우

🚫 API 키를 추측하거나 임의로 생성하지 마세요.692e4c6da0ba315535c9dedf 같은 랜덤 문자열을 .env에 넣으면 100% 실패합니다. Bootpay API 키는 Bootpay 서버가 발급한 값만 유효합니다.

아래 파일을 순서대로 읽고 코드를 작성하세요:

순서	파일	내용
1	`AGENTS.md`	AI 에이전트용 지시 — 금지 행위, 금액 규칙, 통합결제창 판단
2	`SETUP_GUIDE.md`	MCP 최신 설치 · Admin CLI로 키 조회 또는 수동 설정
3	`SDK_VERSIONS.md`	최신 SDK 버전 (v2 5.x) — 3.x/4.x는 deprecated
4	`llms.txt`	핵심 규칙, API 도메인, SDK 패키지, 결제 흐름
5	`examples/`	플랫폼별 전체 코드 예제 (12개)

⚠️MCP 없이는 API 키를 AI가 자동 조회할 수 없습니다. 사용자에게 반드시 아래 안내를 하세요:
admin.bootpay.co.kr → 프로젝트 → 개발자 설정 → API 연동키(결제) 탭에서 아래 3개 키를 확인하여 .env에 입력
또는 stdio 모드로 MCP를 연결하면 list_keychains로 자동 조회 가능
이 안내 없이 키를 추측하거나, 빈 값/.env 없이 코드를 생성하면 실패합니다.

사용자에게 요청할 키 2개 (정확한 이름)

Admin UI(admin.bootpay.co.kr)에서 보이는 라벨과 .env 변수명이 다릅니다. 반드시 아래 매핑을 사용하세요:

Admin UI 라벨	.env 변수명	용도
Client Key (= REST API Key)	`BOOTPAY_CLIENT_KEY`	프론트엔드 SDK 결제창 호출 + 서버 Basic Auth 공통
Secret Key (= Private Key)	`BOOTPAY_SECRET_KEY`	서버 Basic Auth 인증 (비밀)

프론트엔드 빌드 도구에 따라 BOOTPAY_CLIENT_KEY 앞에 접두사를 붙입니다:
Vite → VITE_BOOTPAY_CLIENT_KEY
Next.js → NEXT_PUBLIC_BOOTPAY_CLIENT_KEY
Create React App → REACT_APP_BOOTPAY_CLIENT_KEY

# .env 예시 — create_keychain 또는 Admin UI에서 확인한 값을 입력
BOOTPAY_CLIENT_KEY= # Client Key (프론트엔드 SDK + 서버 Basic Auth 공통)
BOOTPAY_SECRET_KEY= # Secret Key (서버 전용, 프론트엔드 노출 금지)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

잘못된 이름	올바른 이름	비고
`BOOTPAY_REST_APP_ID`	`BOOTPAY_CLIENT_KEY`	"REST API Key"는 Admin UI 라벨일 뿐, 변수명이 아님
`BOOTPAY_PRIVATE_KEY`	`BOOTPAY_SECRET_KEY`	Bootpay에서는 "Secret Key"로 통일
`BOOTPAY_API_KEY`	`BOOTPAY_CLIENT_KEY`	존재하지 않는 변수명
`getAccessToken()`	Basic Auth	v2에서는 토큰 발급 불필요. client_key:secret_key로 직접 인증

핵심 규칙

SDK v2 (5.x) only — bootpay-3.x.x.min.js, bootpay-4.x.x.min.js는 v1(deprecated)이며 동작하지 않음
결제는 프론트엔드에서 시작 — 국내 PG 규정. 백엔드에서 결제를 시작하는 코드 금지
서버승인(분리승인)이 기본 — Bootpay.requestPayment 호출 시 extra.separately_confirmed: true 설정. confirm 시점에 receipt_id를 서버로 전달하면 서버가 confirmPayment()로 최종 승인하고 리턴값으로 금액을 확인 (별도 결제검증 조회 불필요). done 이벤트만 처리하는 클라이언트 승인 코드는 유실 위험이 있어 비권장
웹훅 보완 필수 — 클라이언트 결과 처리는 브라우저 이탈로 유실될 수 있음. 웹훅 엔드포인트를 함께 구현 (부트페이 발신 IP 223.130.82.0/24만 허용 + receiptPayment 재검증 + 멱등 처리)
API 키는 Admin CLI로 발급 → .env에 기록 — placeholder·추측값·랜덤 문자열 금지. create_keychain 또는 list_keychains 반환값만 사용
서버 인증은 Basic Auth — client_key/secret_key 기반. getAccessToken() 불필요
Secret Key는 서버 전용 — 절대 프론트엔드에 노출하지 않을 것

오프라인 · MCP 없이 사용하기

방법 1 — 최신 패키지를 파일로 받아서 설치 (사내망 등 npx 를 못 쓰는 환경)

npm pack @bootpay/mcp@latest # 최신 버전 .tgz 가 현재 폴더에 떨어집니다
npm install -g ./bootpay-mcp-*.tgz # 받은 파일로 전역 설치
bootpay-mcp --version # 설치된 버전 확인

GitHub Releases 의 고정 버전 파일을 받지 마세요. 최신 버전은 항상 npm 에 있습니다. 버전을 고정해야 한다면 npm view @bootpay/mcp versions 로 목록을 보고 @bootpay/mcp@2.1.0 처럼 명시하세요.

방법 2 — 문서만 AI 에게 전달 (npm/git 불필요, MCP 도구는 못 씀)

main.tar.gz 다운로드
AI 도구에 파일 첨부
"부트페이 결제 연동해줘"라고 요청

방법 3 — git clone (문서 참조용)

git clone https://github.com/bootpay/bootpay-mcp.git
# AGENTS.md, llms.txt, SDK_VERSIONS.md, SETUP_GUIDE.md 를 AI에게 전달

방법 2·3 은 문서만 전달합니다. Admin 도구(로그인·키 발급·코드 생성)는 stdio 로 MCP 를 붙여야 씁니다. 이 경우 AI 는 API 키를 자동 조회할 수 없으니, 아래 "MCP 없이 이 저장소만 참조하는 경우" 절을 따르세요.

About This Project

AI 코딩 도구(Claude, Cursor, Windsurf, Cline, GitHub Copilot 등)에서 Bootpay 결제·커머스를 연동할 수 있는 통합 Model Context Protocol (MCP) 서버입니다.

Docs (문서 검색·SDK 버전·트러블슈팅) + Admin (관리자 설정·PG·위젯·코드 생성) + Commerce (스토어·상품·회원) — 하나의 MCP 서버로 제공합니다.

stdio 로 붙으면 기본 75개(Docs 8 + Admin 67), Commerce 를 켜면 88개 도구가 노출됩니다. HTTP 로 붙으면 Docs 8개만 노출됩니다.

Supported PG & Payment Methods

Bootpay는 국내 주요 PG사와 간편결제를 통합 지원합니다:

PG사	코드	지원 결제
나이스페이 (NICE)	`nicepay`	카드, 계좌이체, 가상계좌, 휴대폰
토스페이먼츠 (Toss Payments)	`tosspayments`	카드, 계좌이체, 가상계좌, 휴대폰
KG이니시스 (KG Inicis)	`inicis`	카드, 계좌이체, 가상계좌, 휴대폰
NHN KCP	`kcp`	카드, 계좌이체, 가상계좌, 휴대폰
카카오페이 (Kakao Pay)	`kakao`	간편결제
네이버페이 (Naver Pay)	`naverpay`	간편결제
페이코 (PAYCO)	`payco`	간편결제
토스페이 (Toss Pay)	`tosspay`	간편결제
다날 (Danal)	`danal`	휴대폰 소액결제

결제 유형: 일반결제 (카드/계좌이체/가상계좌/휴대폰) · 정기결제 (빌링키) · 본인인증 · 에스크로 · 현금영수증

Quick Start

두 가지 연결 방식을 지원합니다:

방식	특징	추천 환경
HTTP (Streamable HTTP)	설치 불필요, 원격 서버	Cursor, Windsurf, Cline, 웹 기반
npm (stdio)	로컬 실행, Admin·Commerce 도구 사용 가능	Claude Desktop, Claude Code, Codex, Gemini CLI

0단계: 설치 — 반드시 최신 버전으로

stdio 설정에는 항상 @latest 를 붙이세요.

npx -y @bootpay/mcp@latest

⚠️@latest 를 빼면 예전에 받아둔 사본이 계속 실행됩니다.npx @bootpay/mcp 처럼 버전을 생략하면 npx 는 캐시(~/.npm/_npx/)에 남아 있는 사본을 먼저 씁니다. 한 번 받아둔 사람은 새 버전이 나와도 옛 버전을 계속 실행하게 되고, 그 사이에 고쳐진 것들이 전달되지 않습니다. 실제로 최근 릴리스에서 문서 검색이 조용히 빈 결과를 내던 문제 · 낡은 SDK 버전표 · 일부 도구가 인자를 거절하던 문제가 고쳐졌습니다. 옛 버전을 쓰면 AI 가 그 낡은 정보로 코드를 만듭니다.

지금 무엇이 실행되는지 확인하세요:

npm view @bootpay/mcp version # npm 에 올라온 최신 버전
npx -y @bootpay/mcp@latest --version # 실행될 서버의 버전 (v2.1.1 이상)

--version 은 v2.1.1부터 지원합니다. 그보다 낮은 버전이면 이 명령이 서버를 띄운 채 멈춥니다. 그럴 때는 Ctrl+C 로 끄고 — 그것 자체가 옛 버전이라는 신호이므로 — 아래 캐시 비우기를 바로 실행하세요.

두 값이 같으면 최신입니다. 다르면 캐시를 비우고 다시 받으세요:

npx clear-npx-cache # npx 캐시 비우기
rm -rf ~/.npm/_npx # 위 명령이 안 되면 (macOS/Linux)

Windows PowerShell:

Remove-Item-Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

항상 같은 버전을 고정해서 쓰고 싶다면 전역 설치도 됩니다. 대신 업데이트는 직접 해야 합니다:

npm install -g @bootpay/mcp@latest # 설치 · 업데이트 모두 이 명령
bootpay-mcp --version # 설치된 버전 확인

이 경우 MCP 설정의 command 는 npx 대신 bootpay-mcp 를 쓰고 args 는 비웁니다.

전제조건 — Node.js 18 이상

node -v # v18.0.0 이상이어야 합니다

node 명령이 없다면 https://nodejs.org 에서 LTS 를 먼저 설치하고, 터미널을 새로 여세요 (PATH 반영). Windows 는 설치 후 PowerShell 을 새로 열어야 node 가 잡힙니다.

설정을 저장한 뒤에는 AI 클라이언트를 완전히 종료하고 다시 켜세요. 설정 파일만 고치면 현재 세션에는 반영되지 않습니다. 도구 목록에 부트페이 도구가 안 보이면 대부분 이것 때문입니다. 확인: claude mcp list / codex mcp list / gemini mcp list

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows):

npm (stdio) — 추천:

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP (원격):

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["mcp-remote", "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"]
}
}
}

Claude Code (CLI)

# npm (stdio)
claude mcp add bootpay-docs -- npx -y @bootpay/mcp@latest
# HTTP
claude mcp add bootpay-docs --transport http https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

Cursor

Settings → MCP Servers → Add:

{
"bootpay-docs": {
"url": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}

Codex (OpenAI)

~/.codex/config.toml:

stdio (권장, 전체 도구):

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]

HTTP (Docs 도구만, 설치 불필요):

[mcp_servers.bootpay]
url = "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"

Commerce 도구 활성화:

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]
[mcp_servers.bootpay.env]
BOOTPAY_COMMERCE_CLIENT_KEY = "YOUR_CLIENT_KEY"BOOTPAY_COMMERCE_SECRET_KEY = "YOUR_SECRET_KEY"

또는 CLI로 추가:

codex mcp add bootpay -- npx -y @bootpay/mcp@latest

설정 후 반드시 확인:
현재 Codex 세션을 종료하고 새 세션을 시작하세요
codex mcp list로 bootpay 서버가 보이는지 확인
보이지 않으면 ~/.codex/config.toml의 [mcp_servers.bootpay] 섹션을 재확인

Gemini CLI

~/.gemini/settings.json:

stdio (권장, 전체 도구):

{
"mcpServers": {
"bootpay": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP Streaming:

{
"mcpServers": {
"bootpay": {
"httpUrl": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}
}

또는 CLI로 추가:

gemini mcp add bootpay npx -y @bootpay/mcp@latest

주의: Gemini CLI는 서버 이름에 언더스코어(_)를 사용하면 보안 정책 파싱 오류가 발생합니다. bootpay-docs ✅ / bootpay_docs ❌

Windsurf / Cline / Other MCP Clients

Streamable HTTP endpoint:

https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

What AI Can Do with This MCP

MCP를 연결하면 AI가 다음을 직접 수행합니다:

사용자: "React에서 부트페이 카드결제 연동해줘"
AI 내부 동작:
1. get_sdk_versions → 최신 SDK 버전 확인 (v2 5.x)
2. get_setup_checklist → Client Key + 환경 설정 안내
3. search_docs → get_doc → payment/request 문서 조회
4. 코드 작성 → 문서 기반, 정확한 버전 사용

Docs Tools — 8개 (HTTP + stdio)

Tool	Description
`detect_project_stack`	프로젝트 스택 판정 — 클라이언트 플랫폼·웹 프레임워크·서버 언어·실행 환경(상시/서버리스). 모노레포면 앱마다 판정하고 "서버 1회 + 클라이언트 N회" 호출 계획을 반환
`get_sdk_versions`	모든 SDK 최신 버전 조회 (Web, Android, iOS, Flutter, React Native, 서버 7개 언어)
`search_docs`	120+ 개발자 문서 검색 (12 카테고리)
`get_doc`	특정 문서 전체 마크다운 조회
`list_docs`	카테고리별 문서 목록
`get_setup_checklist`	연동 환경 설정 체크리스트 (API 키, SDK 설치, .env)
`get_troubleshooting`	문제 해결 가이드 (onboarding, sandbox, webhook, billing, subscription, error, cancel, cors, csp, open-type, mobile, widget, unified, certification)
`get_csp_allowlist`	CSP(frame-src) 허용 PG 도메인 목록 + 프레임워크별 설정 스니펫 생성
`get_cs_guide`	고객응대(CS) 매뉴얼 검색

Prompt	Description
`integration-action-plan`	결제유형 × 플랫폼별 6단계 연동 액션 플랜

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Bootpay가 처음이라면 관리자 화면 대신 AI에게 전부 맡기세요. stdio 방식(npx -y @bootpay/mcp@latest)으로 연결하면 Admin 도구 67개가 활성화됩니다.

사용자: "부트페이 결제 연동하고 싶어. 처음이야"
AI 내부 동작:
1. browser_login → 브라우저 팝업으로 로그인
2. create_seller → 셀러(가맹점) 생성 + 기본 프로젝트 자동 생성
3. browser_select_project → 프로젝트 선택
4. activate_payment_method → 나이스페이 카드결제 활성화
5. set_sandbox_mode → 테스트 모드 설정
6. create_keychain(targets=["core"]) → 결제용 API 키 발급 (client_key, secret_key)
7. search_docs + get_doc → 최신 연동 문서 참조
8. 코드 생성 → 발급한 키를 .env에 설정, 코드에서 환경변수 참조

⚠️ 키를 코드에 직접 삽입하지 마세요. 발급한 키는 반드시 .env 파일에 저장하고, 코드에서는 환경변수로 참조합니다. Secret Key는 서버 .env에만 저장하세요. secret_key는 발급 시 1회만 평문으로 표시됩니다.

HTTP 방식에서는 Admin 도구를 사용할 수 없습니다. 프로젝트 설정이 필요하면 반드시 stdio(npx @bootpay/mcp@latest)를 사용하세요.

Admin Tools — 67개 (stdio 전용)

관리자(admin.bootpay.co.kr)의 설정을 AI가 직접 조회·변경할 수 있는 도구입니다. npx -y @bootpay/mcp@latest로 실행하면 자동 활성화됩니다.

카테고리	Tools	Description
코드생성	`generate_payment_code`, `generate_commerce_code`	프리플라이트(인증·키체인·결제수단·SDK 확인) + 클라이언트/서버 코드 원스톱 생성. `payment_type`: `payment`(일반) / `billing`(빌링키) / `subscription`(구독 — 회차·배치·무료체험·해지) / `widget` / `auth`, `scheduler`: `cron` / `http_trigger`(서버리스)
컨텍스트	`get_integration_context`, `get_commerce_context`	인증·프로젝트·결제설정·위젯·키체인을 한 번에 조회 (`readiness.blockers` 반환)
인증	`login`, `browser_login`, `logout`, `list_projects`, `switch_project`, `browser_select_project`, `set_token`, `get_auth_status`	로그인, 프로젝트 전환, 토큰 설정·상태 확인
셀러	`create_seller`, `search_sellers`, `get_seller`, `update_seller`	셀러(가맹점) CRUD
상세설명 블록	`list_content_templates`, `create_content_template`, `delete_content_template`, `list_content_blocks`, `create_content_block`, `update_content_block`, `delete_content_block`, `list_content_block_products`	상세설명을 블록으로 구성. 시작 템플릿(서버 저장분 + MCP 내장 스타터)과 여러 상품이 공유하는 공용 블록 관리. `content_type=4`일 때만 블록이 저장되며, HTML(`content`)은 서버가 컴파일해 채웁니다
디지털 코드풀	`list_digital_codes`, `register_digital_codes`, `disable_digital_code`	시리얼·라이센스 번호 일괄 등록/조회/폐기. `code_distribution_mode="pool"` 상품에서 구매자마다 다른 코드를 발급할 때 사용 (한 번에 최대 5,000개)
이미지	`upload_product_images`	로컬 경로·URL·base64 → Bootpay CDN 업로드 (최대 10장, 장당 10MB)
카테고리	`list_categories`, `create_category`, `update_category`, `delete_category`, `reorder_categories`	카테고리 CRUD. `path="상의 > 티셔츠 > 반팔"`로 계층 일괄 생성, 삭제는 `confirm` 확인 게이트
부속설정	`list_subscription_settings`, `list_delivery_shippings`, `create_subscription_setting`, `create_delivery_shipping`, `list_delivery_shipping_bundles`, `get_product_form_setting`, `get_product_info_notice_forms`	상품에 연결할 구독 설정·배송정책 ID 확보. 정책이 하나도 없는 프로젝트에서는 생성까지 가능 — 배송비·주기 같은 값이 빠지면 저장 대신 `need_answer` 로 무엇을 물어야 하는지 돌려줍니다(금액을 추측해 저장하지 않습니다). 폼 설정 조회로 판매자가 끈 섹션을 건너뛰고, 상품 주요정보(상품정보제공고시)의 상품군(1~40)과 군별 입력 항목도 조회
프로젝트	`create_project`	프로젝트 생성
키체인	`list_api_scopes`, `list_keychains`, `create_keychain`, `delete_keychain`, `get_commerce_keys`	API 키 발급/조회 (source 파라미터로 커머스/결제 구분)
상품	`list_products`, `get_product`, `create_product`, `update_product`, `delete_product`, `create_test_products`	상품 CRUD. `image_paths`로 로컬 사진 경로를 주면 업로드까지 처리, 구독(`subscription_setting_id`)·배송정책(`delivery_shipping_id`) 연결, 상세설명 블록(`content_blocks`), 디지털 지급(`digital_provisioning_type`), 환불정책 노출(`refund_policy_expose_type`) 지원
결제설정	`get_payment_settings`, `activate_payment_method`, `set_sandbox_mode`, `update_payment_resource`, `set_payment_mode`, `browser_select_payment_method`	PG·결제수단 설정
위젯	`list_widgets`, `get_widget`, `create_widget`, `get_widget_default_styles`, `configure_widget`, `update_widget`, `delete_widget`	결제위젯 CRUD
쇼핑몰설정	`get_mall_setting`, `update_mall_setting`	커머스 몰 기본 설정 조회·변경

상품·상세설명 블록·디지털 코드풀·카테고리·이미지 도구는 원격(OAuth) 프로파일에도 포함됩니다. 결제설정·키체인·자격증명 도구는 원격에서 제외됩니다 — 근거와 현재 상태는 원격 커넥터 문서를 보세요.

Commerce Tools — 13개 (stdio 전용, opt-in)

AI 에이전트가 커머스 API를 호출하여 쇼핑몰 기능을 구현할 수 있는 도구입니다. 활성화: 환경변수 BOOTPAY_COMMERCE_ENABLED=true 설정 후 실행.

카테고리	Tools	Description
인증	`set_commerce_credentials`	clientKey/secretKey 설정·검증
스토어	`commerce_get_store`, `commerce_get_store_detail`	가맹점 정보 조회
상품	`commerce_get_products`, `commerce_get_product`, `commerce_create_product`, `commerce_update_product`	상품 CRUD
회원	`commerce_login`, `commerce_get_session`, `commerce_logout`	회원 로그인·세션 관리
리뷰	`commerce_get_reviews`, `commerce_get_review_stats`	리뷰 조회·통계
상태	`commerce_status`	Commerce API 상태 확인

Supported Platforms & SDKs

Client SDKs

Platform	Package
Web (NPM)	`@bootpay/client-js`
Web (CDN)	`bootpay-{version}.min.js`
Android (Kotlin/Java)	`kr.co.bootpay:android`
iOS (Swift/ObjC)	`pod 'Bootpay'`
Flutter	`bootpay_flutter`
React Native	`react-native-bootpay-api`

Server SDKs

Language	Package
Node.js	`@bootpay/backend-js`
Python	`bootpay-backend`
Java / Kotlin	`kr.co.bootpay:backend`
Ruby	`bootpay`
Go	`github.com/bootpay/backend-go/v2`
.NET (C#)	`Bootpay`
PHP	`bootpay/backend-php`

Documentation Categories

Category	Content
`payment`	일반결제 — SDK 설치, 결제창, 서버 검증, 취소/환불
`billing`	정기결제 — 빌링키 발급, 자동결제, 예약결제, 해지
`subscription`	구독관리 — 플랜 생성, 갱신, 해지, 과금
`order`	주문관리 — 주문 생성, 취소, 반품
`customer`	고객관리 — 고객 등록, 그룹, 조회
`product`	상품관리 — 상품 CRUD, 옵션, 카테고리
`webhook`	웹훅 — 설정, 이벤트, 처리, 재시도 정책
`guide`	시작하기 — 키 발급, 환경설정, 개요
`integration`	연동 — 에러코드, 마이그레이션, 호환성
`invoice`	링크페이 — 결제 링크 생성, 알림
`recipes`	레시피 — 업종별 연동 시나리오
`architecture`	아키텍처 — 결제 플로우, 데이터 모델

Ask AI

MCP를 연결한 후 AI에게 이렇게 물어보세요:

부트페이 결제 연동 어떻게 해?
React에서 카드결제 연동하는 전체 코드 알려줘
Flutter에서 정기결제(빌링키) 발급 방법 알려줘
기존 프로젝트에 월 구독결제 붙여줘 (매일 배치로 결제, 같은 달 두 번 결제 방지, 성공 시에만 다음 달 이용 개방)
Next.js에서 결제 검증 서버 코드 작성해줘
웹훅 설정은 어떻게 하는거야?
결제위젯으로 카카오페이, 네이버페이 연동해줘
토스페이먼츠 PG로 가상계좌 결제 구현해줘

Architecture

두 가지 전송 방식을 지원하며, 도구 범위가 다릅니다:

 ┌─────────────────────┐
│ AI Coding Tool │
│ (Claude, Cursor, │
│ Windsurf, Cline, │
│ Codex, Gemini) │
└──────────┬──────────┘
│
┌─────────┴─────────┐
▼ ▼
[HTTP] [stdio]
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────────────┐
│ Cloudflare │ │ npx -y @bootpay/mcp@latest │
│ Workers │ │ │
│ bootpay-docs-mcp │ │ ┌─ Docs ( 8 tools) │
│ .workers.dev/mcp │ │ ├─ Admin (67 tools) │
│ │ │ └─ Commerce (13 tools)* │
│ Docs only │ │ │
│ (8 tools) │ │ * opt-in │
└────────┬─────────┘ └────────────────────────────┘
│
┌────────┴─────────┐
│ KV │
│ 120+ docs │
└──────────────────┘

전송	Docs (8)	Admin (67)	Commerce (13)	노출 도구 수
HTTP (Cloudflare Workers)	O	—	—	8
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	75 (opt-in 포함 88)

stdio 의 detect_project_stack 은 root_path 로 로컬 파일시스템을 직접 훑습니다. HTTP 에서는 같은 도구가 노출되지만 파일을 볼 수 없으므로 files/file_contents 를 직접 넘겨야 합니다.

Stack: Cloudflare Workers + KV + MCP SDK + Streamable HTTP + stdio

Links

Bootpay Developer Docs
Bootpay Admin
Bootpay Official
MCP Protocol Specification
llms.txt — LLM-optimized documentation
사진과 설명으로 상품 올리기 — 판매자용 상품등록 가이드 (비개발자 대상)
원격 커넥터(ChatGPT · Claude) 연결 — OAuth 원격 연결 현황·검증 절차

Keywords

Bootpay, 부트페이, Korean payment gateway, 한국 결제, PG 연동, payment integration, MCP server, Model Context Protocol, AI coding assistant, LLM, Claude, Cursor, Windsurf, Cline, GitHub Copilot, 나이스페이, NICE, 토스페이먼츠, Toss Payments, KG이니시스, KG Inicis, NHN KCP, 카카오페이, Kakao Pay, 네이버페이, Naver Pay, 페이코, PAYCO, 다날, Danal, 정기결제, recurring payment, billing key, 빌링키, subscription, 구독결제, 결제위젯, payment widget, 결제 연동, checkout, 간편결제, easy payment, Cloudflare Workers

Bootpay MCP Server

Korea's payment integration, now accessible to AI. 한국 결제 연동을 AI가 직접 수행할 수 있도록 하는 MCP 서버입니다.

🛍️ 개발자가 아니라 판매자라면 — 코드 없이 사진과 설명만으로 상품을 등록하는 방법은 사진과 설명으로 상품 올리기를 보세요.

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

"이 레포 참조해서 부트페이 결제 연동해줘" 라는 요청을 받고 이 문서를 읽고 있다면:

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

MCP가 "연결됨"이라도 전송 방식에 따라 사용 가능한 도구가 다릅니다:

전송 방식	Docs (8개)	Admin (67개)	Commerce (13개)	키 자동 조회	다음 단계
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	O	→ 아래 "stdio 모드" 참고
HTTP (`bootpay-docs-mcp.rupy1014.workers.dev/mcp`)	O	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)
MCP 없음 (저장소 참조만)	—	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)

확인 방법:

# Codex
codex mcp list # bootpay 서버가 보이는지 확인# Claude Code
claude mcp list # bootpay 서버가 보이는지 확인# Gemini CLI
gemini mcp list # bootpay 서버가 보이는지 확인

서버가 있다면 버전도 확인하세요 — 옛 버전은 낡은 답을 냅니다:

npx -y @bootpay/mcp@latest --version # 지금 실행되는 버전
npm view @bootpay/mcp version # npm 의 최신 버전

두 값이 다르면 사용자에게 최신 버전으로 다시 설치하도록 안내하세요 → Quick Start / 0단계: 설치

stdio로 연결된 경우: browser_login → list_keychains(또는 create_keychain)으로 키를 자동 조회하세요. 사용자에게 키를 직접 물어보지 마세요. HTTP 또는 MCP 없음: 사용자에게 키를 요청해야 합니다. 아래 "MCP 없이 이 저장소만 참조하는 경우" 섹션의 정확한 키 이름을 사용하세요. 서버가 목록에 없으면? MCP 설정 후 반드시 새 세션을 시작하세요. 설정만으로는 현재 세션에 반영되지 않습니다. 설정할 때는 반드시 @latest 를 붙이세요 — npx -y @bootpay/mcp@latest. 버전을 생략하면 npx 캐시에 남은 옛 사본이 실행됩니다. HTTP로 연결했는데 Admin 도구를 쓰고 싶다면? stdio(npx -y @bootpay/mcp@latest)로 재설정 후 새 세션을 시작하세요.

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

중요: 문서(search_docs)를 먼저 읽지 마세요. Admin 도구로 실제 프로젝트 컨텍스트를 먼저 수집하세요.

1. get_integration_context() → 인증/프로젝트/결제설정/위젯/키체인 한 번에 확인 ⭐
→ readiness.ready = true이면 Step 5로 이동
→ readiness.blockers가 있으면 아래 순서로 해결:
2. browser_login → Bootpay 로그인 (미인증 시)
3. browser_select_project → 프로젝트 선택 (미선택 시)
4. create_keychain(targets=["core"]) → 결제용 API 키 발급 (키체인 없을 때)
→ client_key, secret_key 반환 → .env에 즉시 저장
5. get_sdk_versions → 최신 SDK 버전 확인
6. search_docs → get_doc → 관련 문서 조회 (보완 참조)
7. 코드 작성 → .env 환경변수 참조 (키를 코드에 하드코딩 금지)

서버 인증: client_key/secret_key 기반 Basic Auth. getAccessToken() 불필요.

MCP 없이 이 저장소만 참조하는 경우

🚫 API 키를 추측하거나 임의로 생성하지 마세요.692e4c6da0ba315535c9dedf 같은 랜덤 문자열을 .env에 넣으면 100% 실패합니다. Bootpay API 키는 Bootpay 서버가 발급한 값만 유효합니다.

아래 파일을 순서대로 읽고 코드를 작성하세요:

순서	파일	내용
1	`AGENTS.md`	AI 에이전트용 지시 — 금지 행위, 금액 규칙, 통합결제창 판단
2	`SETUP_GUIDE.md`	MCP 최신 설치 · Admin CLI로 키 조회 또는 수동 설정
3	`SDK_VERSIONS.md`	최신 SDK 버전 (v2 5.x) — 3.x/4.x는 deprecated
4	`llms.txt`	핵심 규칙, API 도메인, SDK 패키지, 결제 흐름
5	`examples/`	플랫폼별 전체 코드 예제 (12개)

⚠️MCP 없이는 API 키를 AI가 자동 조회할 수 없습니다. 사용자에게 반드시 아래 안내를 하세요:
admin.bootpay.co.kr → 프로젝트 → 개발자 설정 → API 연동키(결제) 탭에서 아래 3개 키를 확인하여 .env에 입력
또는 stdio 모드로 MCP를 연결하면 list_keychains로 자동 조회 가능
이 안내 없이 키를 추측하거나, 빈 값/.env 없이 코드를 생성하면 실패합니다.

사용자에게 요청할 키 2개 (정확한 이름)

Admin UI(admin.bootpay.co.kr)에서 보이는 라벨과 .env 변수명이 다릅니다. 반드시 아래 매핑을 사용하세요:

Admin UI 라벨	.env 변수명	용도
Client Key (= REST API Key)	`BOOTPAY_CLIENT_KEY`	프론트엔드 SDK 결제창 호출 + 서버 Basic Auth 공통
Secret Key (= Private Key)	`BOOTPAY_SECRET_KEY`	서버 Basic Auth 인증 (비밀)

프론트엔드 빌드 도구에 따라 BOOTPAY_CLIENT_KEY 앞에 접두사를 붙입니다:
Vite → VITE_BOOTPAY_CLIENT_KEY
Next.js → NEXT_PUBLIC_BOOTPAY_CLIENT_KEY
Create React App → REACT_APP_BOOTPAY_CLIENT_KEY

# .env 예시 — create_keychain 또는 Admin UI에서 확인한 값을 입력
BOOTPAY_CLIENT_KEY= # Client Key (프론트엔드 SDK + 서버 Basic Auth 공통)
BOOTPAY_SECRET_KEY= # Secret Key (서버 전용, 프론트엔드 노출 금지)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

잘못된 이름	올바른 이름	비고
`BOOTPAY_REST_APP_ID`	`BOOTPAY_CLIENT_KEY`	"REST API Key"는 Admin UI 라벨일 뿐, 변수명이 아님
`BOOTPAY_PRIVATE_KEY`	`BOOTPAY_SECRET_KEY`	Bootpay에서는 "Secret Key"로 통일
`BOOTPAY_API_KEY`	`BOOTPAY_CLIENT_KEY`	존재하지 않는 변수명
`getAccessToken()`	Basic Auth	v2에서는 토큰 발급 불필요. client_key:secret_key로 직접 인증

핵심 규칙

SDK v2 (5.x) only — bootpay-3.x.x.min.js, bootpay-4.x.x.min.js는 v1(deprecated)이며 동작하지 않음
결제는 프론트엔드에서 시작 — 국내 PG 규정. 백엔드에서 결제를 시작하는 코드 금지
서버승인(분리승인)이 기본 — Bootpay.requestPayment 호출 시 extra.separately_confirmed: true 설정. confirm 시점에 receipt_id를 서버로 전달하면 서버가 confirmPayment()로 최종 승인하고 리턴값으로 금액을 확인 (별도 결제검증 조회 불필요). done 이벤트만 처리하는 클라이언트 승인 코드는 유실 위험이 있어 비권장
웹훅 보완 필수 — 클라이언트 결과 처리는 브라우저 이탈로 유실될 수 있음. 웹훅 엔드포인트를 함께 구현 (부트페이 발신 IP 223.130.82.0/24만 허용 + receiptPayment 재검증 + 멱등 처리)
API 키는 Admin CLI로 발급 → .env에 기록 — placeholder·추측값·랜덤 문자열 금지. create_keychain 또는 list_keychains 반환값만 사용
서버 인증은 Basic Auth — client_key/secret_key 기반. getAccessToken() 불필요
Secret Key는 서버 전용 — 절대 프론트엔드에 노출하지 않을 것

오프라인 · MCP 없이 사용하기

방법 1 — 최신 패키지를 파일로 받아서 설치 (사내망 등 npx 를 못 쓰는 환경)

npm pack @bootpay/mcp@latest # 최신 버전 .tgz 가 현재 폴더에 떨어집니다
npm install -g ./bootpay-mcp-*.tgz # 받은 파일로 전역 설치
bootpay-mcp --version # 설치된 버전 확인

GitHub Releases 의 고정 버전 파일을 받지 마세요. 최신 버전은 항상 npm 에 있습니다. 버전을 고정해야 한다면 npm view @bootpay/mcp versions 로 목록을 보고 @bootpay/mcp@2.1.0 처럼 명시하세요.

방법 2 — 문서만 AI 에게 전달 (npm/git 불필요, MCP 도구는 못 씀)

main.tar.gz 다운로드
AI 도구에 파일 첨부
"부트페이 결제 연동해줘"라고 요청

방법 3 — git clone (문서 참조용)

git clone https://github.com/bootpay/bootpay-mcp.git
# AGENTS.md, llms.txt, SDK_VERSIONS.md, SETUP_GUIDE.md 를 AI에게 전달

방법 2·3 은 문서만 전달합니다. Admin 도구(로그인·키 발급·코드 생성)는 stdio 로 MCP 를 붙여야 씁니다. 이 경우 AI 는 API 키를 자동 조회할 수 없으니, 아래 "MCP 없이 이 저장소만 참조하는 경우" 절을 따르세요.

About This Project

AI 코딩 도구(Claude, Cursor, Windsurf, Cline, GitHub Copilot 등)에서 Bootpay 결제·커머스를 연동할 수 있는 통합 Model Context Protocol (MCP) 서버입니다.

Docs (문서 검색·SDK 버전·트러블슈팅) + Admin (관리자 설정·PG·위젯·코드 생성) + Commerce (스토어·상품·회원) — 하나의 MCP 서버로 제공합니다.

stdio 로 붙으면 기본 75개(Docs 8 + Admin 67), Commerce 를 켜면 88개 도구가 노출됩니다. HTTP 로 붙으면 Docs 8개만 노출됩니다.

Supported PG & Payment Methods

Bootpay는 국내 주요 PG사와 간편결제를 통합 지원합니다:

PG사	코드	지원 결제
나이스페이 (NICE)	`nicepay`	카드, 계좌이체, 가상계좌, 휴대폰
토스페이먼츠 (Toss Payments)	`tosspayments`	카드, 계좌이체, 가상계좌, 휴대폰
KG이니시스 (KG Inicis)	`inicis`	카드, 계좌이체, 가상계좌, 휴대폰
NHN KCP	`kcp`	카드, 계좌이체, 가상계좌, 휴대폰
카카오페이 (Kakao Pay)	`kakao`	간편결제
네이버페이 (Naver Pay)	`naverpay`	간편결제
페이코 (PAYCO)	`payco`	간편결제
토스페이 (Toss Pay)	`tosspay`	간편결제
다날 (Danal)	`danal`	휴대폰 소액결제

결제 유형: 일반결제 (카드/계좌이체/가상계좌/휴대폰) · 정기결제 (빌링키) · 본인인증 · 에스크로 · 현금영수증

Quick Start

두 가지 연결 방식을 지원합니다:

방식	특징	추천 환경
HTTP (Streamable HTTP)	설치 불필요, 원격 서버	Cursor, Windsurf, Cline, 웹 기반
npm (stdio)	로컬 실행, Admin·Commerce 도구 사용 가능	Claude Desktop, Claude Code, Codex, Gemini CLI

0단계: 설치 — 반드시 최신 버전으로

stdio 설정에는 항상 @latest 를 붙이세요.

npx -y @bootpay/mcp@latest

⚠️@latest 를 빼면 예전에 받아둔 사본이 계속 실행됩니다.npx @bootpay/mcp 처럼 버전을 생략하면 npx 는 캐시(~/.npm/_npx/)에 남아 있는 사본을 먼저 씁니다. 한 번 받아둔 사람은 새 버전이 나와도 옛 버전을 계속 실행하게 되고, 그 사이에 고쳐진 것들이 전달되지 않습니다. 실제로 최근 릴리스에서 문서 검색이 조용히 빈 결과를 내던 문제 · 낡은 SDK 버전표 · 일부 도구가 인자를 거절하던 문제가 고쳐졌습니다. 옛 버전을 쓰면 AI 가 그 낡은 정보로 코드를 만듭니다.

지금 무엇이 실행되는지 확인하세요:

npm view @bootpay/mcp version # npm 에 올라온 최신 버전
npx -y @bootpay/mcp@latest --version # 실행될 서버의 버전 (v2.1.1 이상)

--version 은 v2.1.1부터 지원합니다. 그보다 낮은 버전이면 이 명령이 서버를 띄운 채 멈춥니다. 그럴 때는 Ctrl+C 로 끄고 — 그것 자체가 옛 버전이라는 신호이므로 — 아래 캐시 비우기를 바로 실행하세요.

두 값이 같으면 최신입니다. 다르면 캐시를 비우고 다시 받으세요:

npx clear-npx-cache # npx 캐시 비우기
rm -rf ~/.npm/_npx # 위 명령이 안 되면 (macOS/Linux)

Windows PowerShell:

Remove-Item-Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

항상 같은 버전을 고정해서 쓰고 싶다면 전역 설치도 됩니다. 대신 업데이트는 직접 해야 합니다:

npm install -g @bootpay/mcp@latest # 설치 · 업데이트 모두 이 명령
bootpay-mcp --version # 설치된 버전 확인

이 경우 MCP 설정의 command 는 npx 대신 bootpay-mcp 를 쓰고 args 는 비웁니다.

전제조건 — Node.js 18 이상

node -v # v18.0.0 이상이어야 합니다

node 명령이 없다면 https://nodejs.org 에서 LTS 를 먼저 설치하고, 터미널을 새로 여세요 (PATH 반영). Windows 는 설치 후 PowerShell 을 새로 열어야 node 가 잡힙니다.

설정을 저장한 뒤에는 AI 클라이언트를 완전히 종료하고 다시 켜세요. 설정 파일만 고치면 현재 세션에는 반영되지 않습니다. 도구 목록에 부트페이 도구가 안 보이면 대부분 이것 때문입니다. 확인: claude mcp list / codex mcp list / gemini mcp list

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows):

npm (stdio) — 추천:

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP (원격):

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["mcp-remote", "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"]
}
}
}

Claude Code (CLI)

# npm (stdio)
claude mcp add bootpay-docs -- npx -y @bootpay/mcp@latest
# HTTP
claude mcp add bootpay-docs --transport http https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

Cursor

Settings → MCP Servers → Add:

{
"bootpay-docs": {
"url": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}

Codex (OpenAI)

~/.codex/config.toml:

stdio (권장, 전체 도구):

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]

HTTP (Docs 도구만, 설치 불필요):

[mcp_servers.bootpay]
url = "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"

Commerce 도구 활성화:

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]
[mcp_servers.bootpay.env]
BOOTPAY_COMMERCE_CLIENT_KEY = "YOUR_CLIENT_KEY"BOOTPAY_COMMERCE_SECRET_KEY = "YOUR_SECRET_KEY"

또는 CLI로 추가:

codex mcp add bootpay -- npx -y @bootpay/mcp@latest

설정 후 반드시 확인:
현재 Codex 세션을 종료하고 새 세션을 시작하세요
codex mcp list로 bootpay 서버가 보이는지 확인
보이지 않으면 ~/.codex/config.toml의 [mcp_servers.bootpay] 섹션을 재확인

Gemini CLI

~/.gemini/settings.json:

stdio (권장, 전체 도구):

{
"mcpServers": {
"bootpay": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP Streaming:

{
"mcpServers": {
"bootpay": {
"httpUrl": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}
}

또는 CLI로 추가:

gemini mcp add bootpay npx -y @bootpay/mcp@latest

주의: Gemini CLI는 서버 이름에 언더스코어(_)를 사용하면 보안 정책 파싱 오류가 발생합니다. bootpay-docs ✅ / bootpay_docs ❌

Windsurf / Cline / Other MCP Clients

Streamable HTTP endpoint:

https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

What AI Can Do with This MCP

MCP를 연결하면 AI가 다음을 직접 수행합니다:

사용자: "React에서 부트페이 카드결제 연동해줘"
AI 내부 동작:
1. get_sdk_versions → 최신 SDK 버전 확인 (v2 5.x)
2. get_setup_checklist → Client Key + 환경 설정 안내
3. search_docs → get_doc → payment/request 문서 조회
4. 코드 작성 → 문서 기반, 정확한 버전 사용

Docs Tools — 8개 (HTTP + stdio)

Tool	Description
`detect_project_stack`	프로젝트 스택 판정 — 클라이언트 플랫폼·웹 프레임워크·서버 언어·실행 환경(상시/서버리스). 모노레포면 앱마다 판정하고 "서버 1회 + 클라이언트 N회" 호출 계획을 반환
`get_sdk_versions`	모든 SDK 최신 버전 조회 (Web, Android, iOS, Flutter, React Native, 서버 7개 언어)
`search_docs`	120+ 개발자 문서 검색 (12 카테고리)
`get_doc`	특정 문서 전체 마크다운 조회
`list_docs`	카테고리별 문서 목록
`get_setup_checklist`	연동 환경 설정 체크리스트 (API 키, SDK 설치, .env)
`get_troubleshooting`	문제 해결 가이드 (onboarding, sandbox, webhook, billing, subscription, error, cancel, cors, csp, open-type, mobile, widget, unified, certification)
`get_csp_allowlist`	CSP(frame-src) 허용 PG 도메인 목록 + 프레임워크별 설정 스니펫 생성
`get_cs_guide`	고객응대(CS) 매뉴얼 검색

Prompt	Description
`integration-action-plan`	결제유형 × 플랫폼별 6단계 연동 액션 플랜

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Bootpay가 처음이라면 관리자 화면 대신 AI에게 전부 맡기세요. stdio 방식(npx -y @bootpay/mcp@latest)으로 연결하면 Admin 도구 67개가 활성화됩니다.

사용자: "부트페이 결제 연동하고 싶어. 처음이야"
AI 내부 동작:
1. browser_login → 브라우저 팝업으로 로그인
2. create_seller → 셀러(가맹점) 생성 + 기본 프로젝트 자동 생성
3. browser_select_project → 프로젝트 선택
4. activate_payment_method → 나이스페이 카드결제 활성화
5. set_sandbox_mode → 테스트 모드 설정
6. create_keychain(targets=["core"]) → 결제용 API 키 발급 (client_key, secret_key)
7. search_docs + get_doc → 최신 연동 문서 참조
8. 코드 생성 → 발급한 키를 .env에 설정, 코드에서 환경변수 참조

⚠️ 키를 코드에 직접 삽입하지 마세요. 발급한 키는 반드시 .env 파일에 저장하고, 코드에서는 환경변수로 참조합니다. Secret Key는 서버 .env에만 저장하세요. secret_key는 발급 시 1회만 평문으로 표시됩니다.

HTTP 방식에서는 Admin 도구를 사용할 수 없습니다. 프로젝트 설정이 필요하면 반드시 stdio(npx @bootpay/mcp@latest)를 사용하세요.

Admin Tools — 67개 (stdio 전용)

관리자(admin.bootpay.co.kr)의 설정을 AI가 직접 조회·변경할 수 있는 도구입니다. npx -y @bootpay/mcp@latest로 실행하면 자동 활성화됩니다.

카테고리	Tools	Description
코드생성	`generate_payment_code`, `generate_commerce_code`	프리플라이트(인증·키체인·결제수단·SDK 확인) + 클라이언트/서버 코드 원스톱 생성. `payment_type`: `payment`(일반) / `billing`(빌링키) / `subscription`(구독 — 회차·배치·무료체험·해지) / `widget` / `auth`, `scheduler`: `cron` / `http_trigger`(서버리스)
컨텍스트	`get_integration_context`, `get_commerce_context`	인증·프로젝트·결제설정·위젯·키체인을 한 번에 조회 (`readiness.blockers` 반환)
인증	`login`, `browser_login`, `logout`, `list_projects`, `switch_project`, `browser_select_project`, `set_token`, `get_auth_status`	로그인, 프로젝트 전환, 토큰 설정·상태 확인
셀러	`create_seller`, `search_sellers`, `get_seller`, `update_seller`	셀러(가맹점) CRUD
상세설명 블록	`list_content_templates`, `create_content_template`, `delete_content_template`, `list_content_blocks`, `create_content_block`, `update_content_block`, `delete_content_block`, `list_content_block_products`	상세설명을 블록으로 구성. 시작 템플릿(서버 저장분 + MCP 내장 스타터)과 여러 상품이 공유하는 공용 블록 관리. `content_type=4`일 때만 블록이 저장되며, HTML(`content`)은 서버가 컴파일해 채웁니다
디지털 코드풀	`list_digital_codes`, `register_digital_codes`, `disable_digital_code`	시리얼·라이센스 번호 일괄 등록/조회/폐기. `code_distribution_mode="pool"` 상품에서 구매자마다 다른 코드를 발급할 때 사용 (한 번에 최대 5,000개)
이미지	`upload_product_images`	로컬 경로·URL·base64 → Bootpay CDN 업로드 (최대 10장, 장당 10MB)
카테고리	`list_categories`, `create_category`, `update_category`, `delete_category`, `reorder_categories`	카테고리 CRUD. `path="상의 > 티셔츠 > 반팔"`로 계층 일괄 생성, 삭제는 `confirm` 확인 게이트
부속설정	`list_subscription_settings`, `list_delivery_shippings`, `create_subscription_setting`, `create_delivery_shipping`, `list_delivery_shipping_bundles`, `get_product_form_setting`, `get_product_info_notice_forms`	상품에 연결할 구독 설정·배송정책 ID 확보. 정책이 하나도 없는 프로젝트에서는 생성까지 가능 — 배송비·주기 같은 값이 빠지면 저장 대신 `need_answer` 로 무엇을 물어야 하는지 돌려줍니다(금액을 추측해 저장하지 않습니다). 폼 설정 조회로 판매자가 끈 섹션을 건너뛰고, 상품 주요정보(상품정보제공고시)의 상품군(1~40)과 군별 입력 항목도 조회
프로젝트	`create_project`	프로젝트 생성
키체인	`list_api_scopes`, `list_keychains`, `create_keychain`, `delete_keychain`, `get_commerce_keys`	API 키 발급/조회 (source 파라미터로 커머스/결제 구분)
상품	`list_products`, `get_product`, `create_product`, `update_product`, `delete_product`, `create_test_products`	상품 CRUD. `image_paths`로 로컬 사진 경로를 주면 업로드까지 처리, 구독(`subscription_setting_id`)·배송정책(`delivery_shipping_id`) 연결, 상세설명 블록(`content_blocks`), 디지털 지급(`digital_provisioning_type`), 환불정책 노출(`refund_policy_expose_type`) 지원
결제설정	`get_payment_settings`, `activate_payment_method`, `set_sandbox_mode`, `update_payment_resource`, `set_payment_mode`, `browser_select_payment_method`	PG·결제수단 설정
위젯	`list_widgets`, `get_widget`, `create_widget`, `get_widget_default_styles`, `configure_widget`, `update_widget`, `delete_widget`	결제위젯 CRUD
쇼핑몰설정	`get_mall_setting`, `update_mall_setting`	커머스 몰 기본 설정 조회·변경

상품·상세설명 블록·디지털 코드풀·카테고리·이미지 도구는 원격(OAuth) 프로파일에도 포함됩니다. 결제설정·키체인·자격증명 도구는 원격에서 제외됩니다 — 근거와 현재 상태는 원격 커넥터 문서를 보세요.

Commerce Tools — 13개 (stdio 전용, opt-in)

AI 에이전트가 커머스 API를 호출하여 쇼핑몰 기능을 구현할 수 있는 도구입니다. 활성화: 환경변수 BOOTPAY_COMMERCE_ENABLED=true 설정 후 실행.

카테고리	Tools	Description
인증	`set_commerce_credentials`	clientKey/secretKey 설정·검증
스토어	`commerce_get_store`, `commerce_get_store_detail`	가맹점 정보 조회
상품	`commerce_get_products`, `commerce_get_product`, `commerce_create_product`, `commerce_update_product`	상품 CRUD
회원	`commerce_login`, `commerce_get_session`, `commerce_logout`	회원 로그인·세션 관리
리뷰	`commerce_get_reviews`, `commerce_get_review_stats`	리뷰 조회·통계
상태	`commerce_status`	Commerce API 상태 확인

Supported Platforms & SDKs

Client SDKs

Platform	Package
Web (NPM)	`@bootpay/client-js`
Web (CDN)	`bootpay-{version}.min.js`
Android (Kotlin/Java)	`kr.co.bootpay:android`
iOS (Swift/ObjC)	`pod 'Bootpay'`
Flutter	`bootpay_flutter`
React Native	`react-native-bootpay-api`

Server SDKs

Language	Package
Node.js	`@bootpay/backend-js`
Python	`bootpay-backend`
Java / Kotlin	`kr.co.bootpay:backend`
Ruby	`bootpay`
Go	`github.com/bootpay/backend-go/v2`
.NET (C#)	`Bootpay`
PHP	`bootpay/backend-php`

Documentation Categories

Category	Content
`payment`	일반결제 — SDK 설치, 결제창, 서버 검증, 취소/환불
`billing`	정기결제 — 빌링키 발급, 자동결제, 예약결제, 해지
`subscription`	구독관리 — 플랜 생성, 갱신, 해지, 과금
`order`	주문관리 — 주문 생성, 취소, 반품
`customer`	고객관리 — 고객 등록, 그룹, 조회
`product`	상품관리 — 상품 CRUD, 옵션, 카테고리
`webhook`	웹훅 — 설정, 이벤트, 처리, 재시도 정책
`guide`	시작하기 — 키 발급, 환경설정, 개요
`integration`	연동 — 에러코드, 마이그레이션, 호환성
`invoice`	링크페이 — 결제 링크 생성, 알림
`recipes`	레시피 — 업종별 연동 시나리오
`architecture`	아키텍처 — 결제 플로우, 데이터 모델

Ask AI

MCP를 연결한 후 AI에게 이렇게 물어보세요:

부트페이 결제 연동 어떻게 해?
React에서 카드결제 연동하는 전체 코드 알려줘
Flutter에서 정기결제(빌링키) 발급 방법 알려줘
기존 프로젝트에 월 구독결제 붙여줘 (매일 배치로 결제, 같은 달 두 번 결제 방지, 성공 시에만 다음 달 이용 개방)
Next.js에서 결제 검증 서버 코드 작성해줘
웹훅 설정은 어떻게 하는거야?
결제위젯으로 카카오페이, 네이버페이 연동해줘
토스페이먼츠 PG로 가상계좌 결제 구현해줘

Architecture

두 가지 전송 방식을 지원하며, 도구 범위가 다릅니다:

 ┌─────────────────────┐
│ AI Coding Tool │
│ (Claude, Cursor, │
│ Windsurf, Cline, │
│ Codex, Gemini) │
└──────────┬──────────┘
│
┌─────────┴─────────┐
▼ ▼
[HTTP] [stdio]
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────────────┐
│ Cloudflare │ │ npx -y @bootpay/mcp@latest │
│ Workers │ │ │
│ bootpay-docs-mcp │ │ ┌─ Docs ( 8 tools) │
│ .workers.dev/mcp │ │ ├─ Admin (67 tools) │
│ │ │ └─ Commerce (13 tools)* │
│ Docs only │ │ │
│ (8 tools) │ │ * opt-in │
└────────┬─────────┘ └────────────────────────────┘
│
┌────────┴─────────┐
│ KV │
│ 120+ docs │
└──────────────────┘

전송	Docs (8)	Admin (67)	Commerce (13)	노출 도구 수
HTTP (Cloudflare Workers)	O	—	—	8
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	75 (opt-in 포함 88)

stdio 의 detect_project_stack 은 root_path 로 로컬 파일시스템을 직접 훑습니다. HTTP 에서는 같은 도구가 노출되지만 파일을 볼 수 없으므로 files/file_contents 를 직접 넘겨야 합니다.

Stack: Cloudflare Workers + KV + MCP SDK + Streamable HTTP + stdio

Links

Bootpay Developer Docs
Bootpay Admin
Bootpay Official
MCP Protocol Specification
llms.txt — LLM-optimized documentation
사진과 설명으로 상품 올리기 — 판매자용 상품등록 가이드 (비개발자 대상)
원격 커넥터(ChatGPT · Claude) 연결 — OAuth 원격 연결 현황·검증 절차

Keywords

Bootpay, 부트페이, Korean payment gateway, 한국 결제, PG 연동, payment integration, MCP server, Model Context Protocol, AI coding assistant, LLM, Claude, Cursor, Windsurf, Cline, GitHub Copilot, 나이스페이, NICE, 토스페이먼츠, Toss Payments, KG이니시스, KG Inicis, NHN KCP, 카카오페이, Kakao Pay, 네이버페이, Naver Pay, 페이코, PAYCO, 다날, Danal, 정기결제, recurring payment, billing key, 빌링키, subscription, 구독결제, 결제위젯, payment widget, 결제 연동, checkout, 간편결제, easy payment, Cloudflare Workers

Bootpay MCP Server

Korea's payment integration, now accessible to AI. 한국 결제 연동을 AI가 직접 수행할 수 있도록 하는 MCP 서버입니다.

🛍️ 개발자가 아니라 판매자라면 — 코드 없이 사진과 설명만으로 상품을 등록하는 방법은 사진과 설명으로 상품 올리기를 보세요.

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

"이 레포 참조해서 부트페이 결제 연동해줘" 라는 요청을 받고 이 문서를 읽고 있다면:

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

MCP가 "연결됨"이라도 전송 방식에 따라 사용 가능한 도구가 다릅니다:

전송 방식	Docs (8개)	Admin (67개)	Commerce (13개)	키 자동 조회	다음 단계
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	O	→ 아래 "stdio 모드" 참고
HTTP (`bootpay-docs-mcp.rupy1014.workers.dev/mcp`)	O	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)
MCP 없음 (저장소 참조만)	—	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)

확인 방법:

# Codex
codex mcp list # bootpay 서버가 보이는지 확인# Claude Code
claude mcp list # bootpay 서버가 보이는지 확인# Gemini CLI
gemini mcp list # bootpay 서버가 보이는지 확인

서버가 있다면 버전도 확인하세요 — 옛 버전은 낡은 답을 냅니다:

npx -y @bootpay/mcp@latest --version # 지금 실행되는 버전
npm view @bootpay/mcp version # npm 의 최신 버전

두 값이 다르면 사용자에게 최신 버전으로 다시 설치하도록 안내하세요 → Quick Start / 0단계: 설치

stdio로 연결된 경우: browser_login → list_keychains(또는 create_keychain)으로 키를 자동 조회하세요. 사용자에게 키를 직접 물어보지 마세요. HTTP 또는 MCP 없음: 사용자에게 키를 요청해야 합니다. 아래 "MCP 없이 이 저장소만 참조하는 경우" 섹션의 정확한 키 이름을 사용하세요. 서버가 목록에 없으면? MCP 설정 후 반드시 새 세션을 시작하세요. 설정만으로는 현재 세션에 반영되지 않습니다. 설정할 때는 반드시 @latest 를 붙이세요 — npx -y @bootpay/mcp@latest. 버전을 생략하면 npx 캐시에 남은 옛 사본이 실행됩니다. HTTP로 연결했는데 Admin 도구를 쓰고 싶다면? stdio(npx -y @bootpay/mcp@latest)로 재설정 후 새 세션을 시작하세요.

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

중요: 문서(search_docs)를 먼저 읽지 마세요. Admin 도구로 실제 프로젝트 컨텍스트를 먼저 수집하세요.

1. get_integration_context() → 인증/프로젝트/결제설정/위젯/키체인 한 번에 확인 ⭐
→ readiness.ready = true이면 Step 5로 이동
→ readiness.blockers가 있으면 아래 순서로 해결:
2. browser_login → Bootpay 로그인 (미인증 시)
3. browser_select_project → 프로젝트 선택 (미선택 시)
4. create_keychain(targets=["core"]) → 결제용 API 키 발급 (키체인 없을 때)
→ client_key, secret_key 반환 → .env에 즉시 저장
5. get_sdk_versions → 최신 SDK 버전 확인
6. search_docs → get_doc → 관련 문서 조회 (보완 참조)
7. 코드 작성 → .env 환경변수 참조 (키를 코드에 하드코딩 금지)

서버 인증: client_key/secret_key 기반 Basic Auth. getAccessToken() 불필요.

MCP 없이 이 저장소만 참조하는 경우

🚫 API 키를 추측하거나 임의로 생성하지 마세요.692e4c6da0ba315535c9dedf 같은 랜덤 문자열을 .env에 넣으면 100% 실패합니다. Bootpay API 키는 Bootpay 서버가 발급한 값만 유효합니다.

아래 파일을 순서대로 읽고 코드를 작성하세요:

순서	파일	내용
1	`AGENTS.md`	AI 에이전트용 지시 — 금지 행위, 금액 규칙, 통합결제창 판단
2	`SETUP_GUIDE.md`	MCP 최신 설치 · Admin CLI로 키 조회 또는 수동 설정
3	`SDK_VERSIONS.md`	최신 SDK 버전 (v2 5.x) — 3.x/4.x는 deprecated
4	`llms.txt`	핵심 규칙, API 도메인, SDK 패키지, 결제 흐름
5	`examples/`	플랫폼별 전체 코드 예제 (12개)

⚠️MCP 없이는 API 키를 AI가 자동 조회할 수 없습니다. 사용자에게 반드시 아래 안내를 하세요:
admin.bootpay.co.kr → 프로젝트 → 개발자 설정 → API 연동키(결제) 탭에서 아래 3개 키를 확인하여 .env에 입력
또는 stdio 모드로 MCP를 연결하면 list_keychains로 자동 조회 가능
이 안내 없이 키를 추측하거나, 빈 값/.env 없이 코드를 생성하면 실패합니다.

사용자에게 요청할 키 2개 (정확한 이름)

Admin UI(admin.bootpay.co.kr)에서 보이는 라벨과 .env 변수명이 다릅니다. 반드시 아래 매핑을 사용하세요:

Admin UI 라벨	.env 변수명	용도
Client Key (= REST API Key)	`BOOTPAY_CLIENT_KEY`	프론트엔드 SDK 결제창 호출 + 서버 Basic Auth 공통
Secret Key (= Private Key)	`BOOTPAY_SECRET_KEY`	서버 Basic Auth 인증 (비밀)

프론트엔드 빌드 도구에 따라 BOOTPAY_CLIENT_KEY 앞에 접두사를 붙입니다:
Vite → VITE_BOOTPAY_CLIENT_KEY
Next.js → NEXT_PUBLIC_BOOTPAY_CLIENT_KEY
Create React App → REACT_APP_BOOTPAY_CLIENT_KEY

# .env 예시 — create_keychain 또는 Admin UI에서 확인한 값을 입력
BOOTPAY_CLIENT_KEY= # Client Key (프론트엔드 SDK + 서버 Basic Auth 공통)
BOOTPAY_SECRET_KEY= # Secret Key (서버 전용, 프론트엔드 노출 금지)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

잘못된 이름	올바른 이름	비고
`BOOTPAY_REST_APP_ID`	`BOOTPAY_CLIENT_KEY`	"REST API Key"는 Admin UI 라벨일 뿐, 변수명이 아님
`BOOTPAY_PRIVATE_KEY`	`BOOTPAY_SECRET_KEY`	Bootpay에서는 "Secret Key"로 통일
`BOOTPAY_API_KEY`	`BOOTPAY_CLIENT_KEY`	존재하지 않는 변수명
`getAccessToken()`	Basic Auth	v2에서는 토큰 발급 불필요. client_key:secret_key로 직접 인증

핵심 규칙

SDK v2 (5.x) only — bootpay-3.x.x.min.js, bootpay-4.x.x.min.js는 v1(deprecated)이며 동작하지 않음
결제는 프론트엔드에서 시작 — 국내 PG 규정. 백엔드에서 결제를 시작하는 코드 금지
서버승인(분리승인)이 기본 — Bootpay.requestPayment 호출 시 extra.separately_confirmed: true 설정. confirm 시점에 receipt_id를 서버로 전달하면 서버가 confirmPayment()로 최종 승인하고 리턴값으로 금액을 확인 (별도 결제검증 조회 불필요). done 이벤트만 처리하는 클라이언트 승인 코드는 유실 위험이 있어 비권장
웹훅 보완 필수 — 클라이언트 결과 처리는 브라우저 이탈로 유실될 수 있음. 웹훅 엔드포인트를 함께 구현 (부트페이 발신 IP 223.130.82.0/24만 허용 + receiptPayment 재검증 + 멱등 처리)
API 키는 Admin CLI로 발급 → .env에 기록 — placeholder·추측값·랜덤 문자열 금지. create_keychain 또는 list_keychains 반환값만 사용
서버 인증은 Basic Auth — client_key/secret_key 기반. getAccessToken() 불필요
Secret Key는 서버 전용 — 절대 프론트엔드에 노출하지 않을 것

오프라인 · MCP 없이 사용하기

방법 1 — 최신 패키지를 파일로 받아서 설치 (사내망 등 npx 를 못 쓰는 환경)

npm pack @bootpay/mcp@latest # 최신 버전 .tgz 가 현재 폴더에 떨어집니다
npm install -g ./bootpay-mcp-*.tgz # 받은 파일로 전역 설치
bootpay-mcp --version # 설치된 버전 확인

GitHub Releases 의 고정 버전 파일을 받지 마세요. 최신 버전은 항상 npm 에 있습니다. 버전을 고정해야 한다면 npm view @bootpay/mcp versions 로 목록을 보고 @bootpay/mcp@2.1.0 처럼 명시하세요.

방법 2 — 문서만 AI 에게 전달 (npm/git 불필요, MCP 도구는 못 씀)

main.tar.gz 다운로드
AI 도구에 파일 첨부
"부트페이 결제 연동해줘"라고 요청

방법 3 — git clone (문서 참조용)

git clone https://github.com/bootpay/bootpay-mcp.git
# AGENTS.md, llms.txt, SDK_VERSIONS.md, SETUP_GUIDE.md 를 AI에게 전달

방법 2·3 은 문서만 전달합니다. Admin 도구(로그인·키 발급·코드 생성)는 stdio 로 MCP 를 붙여야 씁니다. 이 경우 AI 는 API 키를 자동 조회할 수 없으니, 아래 "MCP 없이 이 저장소만 참조하는 경우" 절을 따르세요.

About This Project

AI 코딩 도구(Claude, Cursor, Windsurf, Cline, GitHub Copilot 등)에서 Bootpay 결제·커머스를 연동할 수 있는 통합 Model Context Protocol (MCP) 서버입니다.

Docs (문서 검색·SDK 버전·트러블슈팅) + Admin (관리자 설정·PG·위젯·코드 생성) + Commerce (스토어·상품·회원) — 하나의 MCP 서버로 제공합니다.

stdio 로 붙으면 기본 75개(Docs 8 + Admin 67), Commerce 를 켜면 88개 도구가 노출됩니다. HTTP 로 붙으면 Docs 8개만 노출됩니다.

Supported PG & Payment Methods

Bootpay는 국내 주요 PG사와 간편결제를 통합 지원합니다:

PG사	코드	지원 결제
나이스페이 (NICE)	`nicepay`	카드, 계좌이체, 가상계좌, 휴대폰
토스페이먼츠 (Toss Payments)	`tosspayments`	카드, 계좌이체, 가상계좌, 휴대폰
KG이니시스 (KG Inicis)	`inicis`	카드, 계좌이체, 가상계좌, 휴대폰
NHN KCP	`kcp`	카드, 계좌이체, 가상계좌, 휴대폰
카카오페이 (Kakao Pay)	`kakao`	간편결제
네이버페이 (Naver Pay)	`naverpay`	간편결제
페이코 (PAYCO)	`payco`	간편결제
토스페이 (Toss Pay)	`tosspay`	간편결제
다날 (Danal)	`danal`	휴대폰 소액결제

결제 유형: 일반결제 (카드/계좌이체/가상계좌/휴대폰) · 정기결제 (빌링키) · 본인인증 · 에스크로 · 현금영수증

Quick Start

두 가지 연결 방식을 지원합니다:

방식	특징	추천 환경
HTTP (Streamable HTTP)	설치 불필요, 원격 서버	Cursor, Windsurf, Cline, 웹 기반
npm (stdio)	로컬 실행, Admin·Commerce 도구 사용 가능	Claude Desktop, Claude Code, Codex, Gemini CLI

0단계: 설치 — 반드시 최신 버전으로

stdio 설정에는 항상 @latest 를 붙이세요.

npx -y @bootpay/mcp@latest

⚠️@latest 를 빼면 예전에 받아둔 사본이 계속 실행됩니다.npx @bootpay/mcp 처럼 버전을 생략하면 npx 는 캐시(~/.npm/_npx/)에 남아 있는 사본을 먼저 씁니다. 한 번 받아둔 사람은 새 버전이 나와도 옛 버전을 계속 실행하게 되고, 그 사이에 고쳐진 것들이 전달되지 않습니다. 실제로 최근 릴리스에서 문서 검색이 조용히 빈 결과를 내던 문제 · 낡은 SDK 버전표 · 일부 도구가 인자를 거절하던 문제가 고쳐졌습니다. 옛 버전을 쓰면 AI 가 그 낡은 정보로 코드를 만듭니다.

지금 무엇이 실행되는지 확인하세요:

npm view @bootpay/mcp version # npm 에 올라온 최신 버전
npx -y @bootpay/mcp@latest --version # 실행될 서버의 버전 (v2.1.1 이상)

--version 은 v2.1.1부터 지원합니다. 그보다 낮은 버전이면 이 명령이 서버를 띄운 채 멈춥니다. 그럴 때는 Ctrl+C 로 끄고 — 그것 자체가 옛 버전이라는 신호이므로 — 아래 캐시 비우기를 바로 실행하세요.

두 값이 같으면 최신입니다. 다르면 캐시를 비우고 다시 받으세요:

npx clear-npx-cache # npx 캐시 비우기
rm -rf ~/.npm/_npx # 위 명령이 안 되면 (macOS/Linux)

Windows PowerShell:

Remove-Item-Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

항상 같은 버전을 고정해서 쓰고 싶다면 전역 설치도 됩니다. 대신 업데이트는 직접 해야 합니다:

npm install -g @bootpay/mcp@latest # 설치 · 업데이트 모두 이 명령
bootpay-mcp --version # 설치된 버전 확인

이 경우 MCP 설정의 command 는 npx 대신 bootpay-mcp 를 쓰고 args 는 비웁니다.

전제조건 — Node.js 18 이상

node -v # v18.0.0 이상이어야 합니다

node 명령이 없다면 https://nodejs.org 에서 LTS 를 먼저 설치하고, 터미널을 새로 여세요 (PATH 반영). Windows 는 설치 후 PowerShell 을 새로 열어야 node 가 잡힙니다.

설정을 저장한 뒤에는 AI 클라이언트를 완전히 종료하고 다시 켜세요. 설정 파일만 고치면 현재 세션에는 반영되지 않습니다. 도구 목록에 부트페이 도구가 안 보이면 대부분 이것 때문입니다. 확인: claude mcp list / codex mcp list / gemini mcp list

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows):

npm (stdio) — 추천:

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP (원격):

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["mcp-remote", "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"]
}
}
}

Claude Code (CLI)

# npm (stdio)
claude mcp add bootpay-docs -- npx -y @bootpay/mcp@latest
# HTTP
claude mcp add bootpay-docs --transport http https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

Cursor

Settings → MCP Servers → Add:

{
"bootpay-docs": {
"url": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}

Codex (OpenAI)

~/.codex/config.toml:

stdio (권장, 전체 도구):

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]

HTTP (Docs 도구만, 설치 불필요):

[mcp_servers.bootpay]
url = "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"

Commerce 도구 활성화:

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]
[mcp_servers.bootpay.env]
BOOTPAY_COMMERCE_CLIENT_KEY = "YOUR_CLIENT_KEY"BOOTPAY_COMMERCE_SECRET_KEY = "YOUR_SECRET_KEY"

또는 CLI로 추가:

codex mcp add bootpay -- npx -y @bootpay/mcp@latest

설정 후 반드시 확인:
현재 Codex 세션을 종료하고 새 세션을 시작하세요
codex mcp list로 bootpay 서버가 보이는지 확인
보이지 않으면 ~/.codex/config.toml의 [mcp_servers.bootpay] 섹션을 재확인

Gemini CLI

~/.gemini/settings.json:

stdio (권장, 전체 도구):

{
"mcpServers": {
"bootpay": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP Streaming:

{
"mcpServers": {
"bootpay": {
"httpUrl": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}
}

또는 CLI로 추가:

gemini mcp add bootpay npx -y @bootpay/mcp@latest

주의: Gemini CLI는 서버 이름에 언더스코어(_)를 사용하면 보안 정책 파싱 오류가 발생합니다. bootpay-docs ✅ / bootpay_docs ❌

Windsurf / Cline / Other MCP Clients

Streamable HTTP endpoint:

https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

What AI Can Do with This MCP

MCP를 연결하면 AI가 다음을 직접 수행합니다:

사용자: "React에서 부트페이 카드결제 연동해줘"
AI 내부 동작:
1. get_sdk_versions → 최신 SDK 버전 확인 (v2 5.x)
2. get_setup_checklist → Client Key + 환경 설정 안내
3. search_docs → get_doc → payment/request 문서 조회
4. 코드 작성 → 문서 기반, 정확한 버전 사용

Docs Tools — 8개 (HTTP + stdio)

Tool	Description
`detect_project_stack`	프로젝트 스택 판정 — 클라이언트 플랫폼·웹 프레임워크·서버 언어·실행 환경(상시/서버리스). 모노레포면 앱마다 판정하고 "서버 1회 + 클라이언트 N회" 호출 계획을 반환
`get_sdk_versions`	모든 SDK 최신 버전 조회 (Web, Android, iOS, Flutter, React Native, 서버 7개 언어)
`search_docs`	120+ 개발자 문서 검색 (12 카테고리)
`get_doc`	특정 문서 전체 마크다운 조회
`list_docs`	카테고리별 문서 목록
`get_setup_checklist`	연동 환경 설정 체크리스트 (API 키, SDK 설치, .env)
`get_troubleshooting`	문제 해결 가이드 (onboarding, sandbox, webhook, billing, subscription, error, cancel, cors, csp, open-type, mobile, widget, unified, certification)
`get_csp_allowlist`	CSP(frame-src) 허용 PG 도메인 목록 + 프레임워크별 설정 스니펫 생성
`get_cs_guide`	고객응대(CS) 매뉴얼 검색

Prompt	Description
`integration-action-plan`	결제유형 × 플랫폼별 6단계 연동 액션 플랜

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Bootpay가 처음이라면 관리자 화면 대신 AI에게 전부 맡기세요. stdio 방식(npx -y @bootpay/mcp@latest)으로 연결하면 Admin 도구 67개가 활성화됩니다.

사용자: "부트페이 결제 연동하고 싶어. 처음이야"
AI 내부 동작:
1. browser_login → 브라우저 팝업으로 로그인
2. create_seller → 셀러(가맹점) 생성 + 기본 프로젝트 자동 생성
3. browser_select_project → 프로젝트 선택
4. activate_payment_method → 나이스페이 카드결제 활성화
5. set_sandbox_mode → 테스트 모드 설정
6. create_keychain(targets=["core"]) → 결제용 API 키 발급 (client_key, secret_key)
7. search_docs + get_doc → 최신 연동 문서 참조
8. 코드 생성 → 발급한 키를 .env에 설정, 코드에서 환경변수 참조

⚠️ 키를 코드에 직접 삽입하지 마세요. 발급한 키는 반드시 .env 파일에 저장하고, 코드에서는 환경변수로 참조합니다. Secret Key는 서버 .env에만 저장하세요. secret_key는 발급 시 1회만 평문으로 표시됩니다.

HTTP 방식에서는 Admin 도구를 사용할 수 없습니다. 프로젝트 설정이 필요하면 반드시 stdio(npx @bootpay/mcp@latest)를 사용하세요.

Admin Tools — 67개 (stdio 전용)

관리자(admin.bootpay.co.kr)의 설정을 AI가 직접 조회·변경할 수 있는 도구입니다. npx -y @bootpay/mcp@latest로 실행하면 자동 활성화됩니다.

카테고리	Tools	Description
코드생성	`generate_payment_code`, `generate_commerce_code`	프리플라이트(인증·키체인·결제수단·SDK 확인) + 클라이언트/서버 코드 원스톱 생성. `payment_type`: `payment`(일반) / `billing`(빌링키) / `subscription`(구독 — 회차·배치·무료체험·해지) / `widget` / `auth`, `scheduler`: `cron` / `http_trigger`(서버리스)
컨텍스트	`get_integration_context`, `get_commerce_context`	인증·프로젝트·결제설정·위젯·키체인을 한 번에 조회 (`readiness.blockers` 반환)
인증	`login`, `browser_login`, `logout`, `list_projects`, `switch_project`, `browser_select_project`, `set_token`, `get_auth_status`	로그인, 프로젝트 전환, 토큰 설정·상태 확인
셀러	`create_seller`, `search_sellers`, `get_seller`, `update_seller`	셀러(가맹점) CRUD
상세설명 블록	`list_content_templates`, `create_content_template`, `delete_content_template`, `list_content_blocks`, `create_content_block`, `update_content_block`, `delete_content_block`, `list_content_block_products`	상세설명을 블록으로 구성. 시작 템플릿(서버 저장분 + MCP 내장 스타터)과 여러 상품이 공유하는 공용 블록 관리. `content_type=4`일 때만 블록이 저장되며, HTML(`content`)은 서버가 컴파일해 채웁니다
디지털 코드풀	`list_digital_codes`, `register_digital_codes`, `disable_digital_code`	시리얼·라이센스 번호 일괄 등록/조회/폐기. `code_distribution_mode="pool"` 상품에서 구매자마다 다른 코드를 발급할 때 사용 (한 번에 최대 5,000개)
이미지	`upload_product_images`	로컬 경로·URL·base64 → Bootpay CDN 업로드 (최대 10장, 장당 10MB)
카테고리	`list_categories`, `create_category`, `update_category`, `delete_category`, `reorder_categories`	카테고리 CRUD. `path="상의 > 티셔츠 > 반팔"`로 계층 일괄 생성, 삭제는 `confirm` 확인 게이트
부속설정	`list_subscription_settings`, `list_delivery_shippings`, `create_subscription_setting`, `create_delivery_shipping`, `list_delivery_shipping_bundles`, `get_product_form_setting`, `get_product_info_notice_forms`	상품에 연결할 구독 설정·배송정책 ID 확보. 정책이 하나도 없는 프로젝트에서는 생성까지 가능 — 배송비·주기 같은 값이 빠지면 저장 대신 `need_answer` 로 무엇을 물어야 하는지 돌려줍니다(금액을 추측해 저장하지 않습니다). 폼 설정 조회로 판매자가 끈 섹션을 건너뛰고, 상품 주요정보(상품정보제공고시)의 상품군(1~40)과 군별 입력 항목도 조회
프로젝트	`create_project`	프로젝트 생성
키체인	`list_api_scopes`, `list_keychains`, `create_keychain`, `delete_keychain`, `get_commerce_keys`	API 키 발급/조회 (source 파라미터로 커머스/결제 구분)
상품	`list_products`, `get_product`, `create_product`, `update_product`, `delete_product`, `create_test_products`	상품 CRUD. `image_paths`로 로컬 사진 경로를 주면 업로드까지 처리, 구독(`subscription_setting_id`)·배송정책(`delivery_shipping_id`) 연결, 상세설명 블록(`content_blocks`), 디지털 지급(`digital_provisioning_type`), 환불정책 노출(`refund_policy_expose_type`) 지원
결제설정	`get_payment_settings`, `activate_payment_method`, `set_sandbox_mode`, `update_payment_resource`, `set_payment_mode`, `browser_select_payment_method`	PG·결제수단 설정
위젯	`list_widgets`, `get_widget`, `create_widget`, `get_widget_default_styles`, `configure_widget`, `update_widget`, `delete_widget`	결제위젯 CRUD
쇼핑몰설정	`get_mall_setting`, `update_mall_setting`	커머스 몰 기본 설정 조회·변경

상품·상세설명 블록·디지털 코드풀·카테고리·이미지 도구는 원격(OAuth) 프로파일에도 포함됩니다. 결제설정·키체인·자격증명 도구는 원격에서 제외됩니다 — 근거와 현재 상태는 원격 커넥터 문서를 보세요.

Commerce Tools — 13개 (stdio 전용, opt-in)

AI 에이전트가 커머스 API를 호출하여 쇼핑몰 기능을 구현할 수 있는 도구입니다. 활성화: 환경변수 BOOTPAY_COMMERCE_ENABLED=true 설정 후 실행.

카테고리	Tools	Description
인증	`set_commerce_credentials`	clientKey/secretKey 설정·검증
스토어	`commerce_get_store`, `commerce_get_store_detail`	가맹점 정보 조회
상품	`commerce_get_products`, `commerce_get_product`, `commerce_create_product`, `commerce_update_product`	상품 CRUD
회원	`commerce_login`, `commerce_get_session`, `commerce_logout`	회원 로그인·세션 관리
리뷰	`commerce_get_reviews`, `commerce_get_review_stats`	리뷰 조회·통계
상태	`commerce_status`	Commerce API 상태 확인

Supported Platforms & SDKs

Client SDKs

Platform	Package
Web (NPM)	`@bootpay/client-js`
Web (CDN)	`bootpay-{version}.min.js`
Android (Kotlin/Java)	`kr.co.bootpay:android`
iOS (Swift/ObjC)	`pod 'Bootpay'`
Flutter	`bootpay_flutter`
React Native	`react-native-bootpay-api`

Server SDKs

Language	Package
Node.js	`@bootpay/backend-js`
Python	`bootpay-backend`
Java / Kotlin	`kr.co.bootpay:backend`
Ruby	`bootpay`
Go	`github.com/bootpay/backend-go/v2`
.NET (C#)	`Bootpay`
PHP	`bootpay/backend-php`

Documentation Categories

Category	Content
`payment`	일반결제 — SDK 설치, 결제창, 서버 검증, 취소/환불
`billing`	정기결제 — 빌링키 발급, 자동결제, 예약결제, 해지
`subscription`	구독관리 — 플랜 생성, 갱신, 해지, 과금
`order`	주문관리 — 주문 생성, 취소, 반품
`customer`	고객관리 — 고객 등록, 그룹, 조회
`product`	상품관리 — 상품 CRUD, 옵션, 카테고리
`webhook`	웹훅 — 설정, 이벤트, 처리, 재시도 정책
`guide`	시작하기 — 키 발급, 환경설정, 개요
`integration`	연동 — 에러코드, 마이그레이션, 호환성
`invoice`	링크페이 — 결제 링크 생성, 알림
`recipes`	레시피 — 업종별 연동 시나리오
`architecture`	아키텍처 — 결제 플로우, 데이터 모델

Ask AI

MCP를 연결한 후 AI에게 이렇게 물어보세요:

부트페이 결제 연동 어떻게 해?
React에서 카드결제 연동하는 전체 코드 알려줘
Flutter에서 정기결제(빌링키) 발급 방법 알려줘
기존 프로젝트에 월 구독결제 붙여줘 (매일 배치로 결제, 같은 달 두 번 결제 방지, 성공 시에만 다음 달 이용 개방)
Next.js에서 결제 검증 서버 코드 작성해줘
웹훅 설정은 어떻게 하는거야?
결제위젯으로 카카오페이, 네이버페이 연동해줘
토스페이먼츠 PG로 가상계좌 결제 구현해줘

Architecture

두 가지 전송 방식을 지원하며, 도구 범위가 다릅니다:

 ┌─────────────────────┐
│ AI Coding Tool │
│ (Claude, Cursor, │
│ Windsurf, Cline, │
│ Codex, Gemini) │
└──────────┬──────────┘
│
┌─────────┴─────────┐
▼ ▼
[HTTP] [stdio]
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────────────┐
│ Cloudflare │ │ npx -y @bootpay/mcp@latest │
│ Workers │ │ │
│ bootpay-docs-mcp │ │ ┌─ Docs ( 8 tools) │
│ .workers.dev/mcp │ │ ├─ Admin (67 tools) │
│ │ │ └─ Commerce (13 tools)* │
│ Docs only │ │ │
│ (8 tools) │ │ * opt-in │
└────────┬─────────┘ └────────────────────────────┘
│
┌────────┴─────────┐
│ KV │
│ 120+ docs │
└──────────────────┘

전송	Docs (8)	Admin (67)	Commerce (13)	노출 도구 수
HTTP (Cloudflare Workers)	O	—	—	8
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	75 (opt-in 포함 88)

stdio 의 detect_project_stack 은 root_path 로 로컬 파일시스템을 직접 훑습니다. HTTP 에서는 같은 도구가 노출되지만 파일을 볼 수 없으므로 files/file_contents 를 직접 넘겨야 합니다.

Stack: Cloudflare Workers + KV + MCP SDK + Streamable HTTP + stdio

Links

Bootpay Developer Docs
Bootpay Admin
Bootpay Official
MCP Protocol Specification
llms.txt — LLM-optimized documentation
사진과 설명으로 상품 올리기 — 판매자용 상품등록 가이드 (비개발자 대상)
원격 커넥터(ChatGPT · Claude) 연결 — OAuth 원격 연결 현황·검증 절차

Keywords

Bootpay, 부트페이, Korean payment gateway, 한국 결제, PG 연동, payment integration, MCP server, Model Context Protocol, AI coding assistant, LLM, Claude, Cursor, Windsurf, Cline, GitHub Copilot, 나이스페이, NICE, 토스페이먼츠, Toss Payments, KG이니시스, KG Inicis, NHN KCP, 카카오페이, Kakao Pay, 네이버페이, Naver Pay, 페이코, PAYCO, 다날, Danal, 정기결제, recurring payment, billing key, 빌링키, subscription, 구독결제, 결제위젯, payment widget, 결제 연동, checkout, 간편결제, easy payment, Cloudflare Workers

Bootpay MCP Server

Korea's payment integration, now accessible to AI. 한국 결제 연동을 AI가 직접 수행할 수 있도록 하는 MCP 서버입니다.

🛍️ 개발자가 아니라 판매자라면 — 코드 없이 사진과 설명만으로 상품을 등록하는 방법은 사진과 설명으로 상품 올리기를 보세요.

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

"이 레포 참조해서 부트페이 결제 연동해줘" 라는 요청을 받고 이 문서를 읽고 있다면:

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

MCP가 "연결됨"이라도 전송 방식에 따라 사용 가능한 도구가 다릅니다:

전송 방식	Docs (8개)	Admin (67개)	Commerce (13개)	키 자동 조회	다음 단계
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	O	→ 아래 "stdio 모드" 참고
HTTP (`bootpay-docs-mcp.rupy1014.workers.dev/mcp`)	O	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)
MCP 없음 (저장소 참조만)	—	—	—	—	→ 아래 "MCP 없이" 참고 (키 수동 입력 필요)

확인 방법:

# Codex
codex mcp list # bootpay 서버가 보이는지 확인# Claude Code
claude mcp list # bootpay 서버가 보이는지 확인# Gemini CLI
gemini mcp list # bootpay 서버가 보이는지 확인

서버가 있다면 버전도 확인하세요 — 옛 버전은 낡은 답을 냅니다:

npx -y @bootpay/mcp@latest --version # 지금 실행되는 버전
npm view @bootpay/mcp version # npm 의 최신 버전

두 값이 다르면 사용자에게 최신 버전으로 다시 설치하도록 안내하세요 → Quick Start / 0단계: 설치

stdio로 연결된 경우: browser_login → list_keychains(또는 create_keychain)으로 키를 자동 조회하세요. 사용자에게 키를 직접 물어보지 마세요. HTTP 또는 MCP 없음: 사용자에게 키를 요청해야 합니다. 아래 "MCP 없이 이 저장소만 참조하는 경우" 섹션의 정확한 키 이름을 사용하세요. 서버가 목록에 없으면? MCP 설정 후 반드시 새 세션을 시작하세요. 설정만으로는 현재 세션에 반영되지 않습니다. 설정할 때는 반드시 @latest 를 붙이세요 — npx -y @bootpay/mcp@latest. 버전을 생략하면 npx 캐시에 남은 옛 사본이 실행됩니다. HTTP로 연결했는데 Admin 도구를 쓰고 싶다면? stdio(npx -y @bootpay/mcp@latest)로 재설정 후 새 세션을 시작하세요.

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

중요: 문서(search_docs)를 먼저 읽지 마세요. Admin 도구로 실제 프로젝트 컨텍스트를 먼저 수집하세요.

1. get_integration_context() → 인증/프로젝트/결제설정/위젯/키체인 한 번에 확인 ⭐
→ readiness.ready = true이면 Step 5로 이동
→ readiness.blockers가 있으면 아래 순서로 해결:
2. browser_login → Bootpay 로그인 (미인증 시)
3. browser_select_project → 프로젝트 선택 (미선택 시)
4. create_keychain(targets=["core"]) → 결제용 API 키 발급 (키체인 없을 때)
→ client_key, secret_key 반환 → .env에 즉시 저장
5. get_sdk_versions → 최신 SDK 버전 확인
6. search_docs → get_doc → 관련 문서 조회 (보완 참조)
7. 코드 작성 → .env 환경변수 참조 (키를 코드에 하드코딩 금지)

서버 인증: client_key/secret_key 기반 Basic Auth. getAccessToken() 불필요.

MCP 없이 이 저장소만 참조하는 경우

🚫 API 키를 추측하거나 임의로 생성하지 마세요.692e4c6da0ba315535c9dedf 같은 랜덤 문자열을 .env에 넣으면 100% 실패합니다. Bootpay API 키는 Bootpay 서버가 발급한 값만 유효합니다.

아래 파일을 순서대로 읽고 코드를 작성하세요:

순서	파일	내용
1	`AGENTS.md`	AI 에이전트용 지시 — 금지 행위, 금액 규칙, 통합결제창 판단
2	`SETUP_GUIDE.md`	MCP 최신 설치 · Admin CLI로 키 조회 또는 수동 설정
3	`SDK_VERSIONS.md`	최신 SDK 버전 (v2 5.x) — 3.x/4.x는 deprecated
4	`llms.txt`	핵심 규칙, API 도메인, SDK 패키지, 결제 흐름
5	`examples/`	플랫폼별 전체 코드 예제 (12개)

⚠️MCP 없이는 API 키를 AI가 자동 조회할 수 없습니다. 사용자에게 반드시 아래 안내를 하세요:
admin.bootpay.co.kr → 프로젝트 → 개발자 설정 → API 연동키(결제) 탭에서 아래 3개 키를 확인하여 .env에 입력
또는 stdio 모드로 MCP를 연결하면 list_keychains로 자동 조회 가능
이 안내 없이 키를 추측하거나, 빈 값/.env 없이 코드를 생성하면 실패합니다.

사용자에게 요청할 키 2개 (정확한 이름)

Admin UI(admin.bootpay.co.kr)에서 보이는 라벨과 .env 변수명이 다릅니다. 반드시 아래 매핑을 사용하세요:

Admin UI 라벨	.env 변수명	용도
Client Key (= REST API Key)	`BOOTPAY_CLIENT_KEY`	프론트엔드 SDK 결제창 호출 + 서버 Basic Auth 공통
Secret Key (= Private Key)	`BOOTPAY_SECRET_KEY`	서버 Basic Auth 인증 (비밀)

프론트엔드 빌드 도구에 따라 BOOTPAY_CLIENT_KEY 앞에 접두사를 붙입니다:
Vite → VITE_BOOTPAY_CLIENT_KEY
Next.js → NEXT_PUBLIC_BOOTPAY_CLIENT_KEY
Create React App → REACT_APP_BOOTPAY_CLIENT_KEY

# .env 예시 — create_keychain 또는 Admin UI에서 확인한 값을 입력
BOOTPAY_CLIENT_KEY= # Client Key (프론트엔드 SDK + 서버 Basic Auth 공통)
BOOTPAY_SECRET_KEY= # Secret Key (서버 전용, 프론트엔드 노출 금지)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

잘못된 이름	올바른 이름	비고
`BOOTPAY_REST_APP_ID`	`BOOTPAY_CLIENT_KEY`	"REST API Key"는 Admin UI 라벨일 뿐, 변수명이 아님
`BOOTPAY_PRIVATE_KEY`	`BOOTPAY_SECRET_KEY`	Bootpay에서는 "Secret Key"로 통일
`BOOTPAY_API_KEY`	`BOOTPAY_CLIENT_KEY`	존재하지 않는 변수명
`getAccessToken()`	Basic Auth	v2에서는 토큰 발급 불필요. client_key:secret_key로 직접 인증

핵심 규칙

SDK v2 (5.x) only — bootpay-3.x.x.min.js, bootpay-4.x.x.min.js는 v1(deprecated)이며 동작하지 않음
결제는 프론트엔드에서 시작 — 국내 PG 규정. 백엔드에서 결제를 시작하는 코드 금지
서버승인(분리승인)이 기본 — Bootpay.requestPayment 호출 시 extra.separately_confirmed: true 설정. confirm 시점에 receipt_id를 서버로 전달하면 서버가 confirmPayment()로 최종 승인하고 리턴값으로 금액을 확인 (별도 결제검증 조회 불필요). done 이벤트만 처리하는 클라이언트 승인 코드는 유실 위험이 있어 비권장
웹훅 보완 필수 — 클라이언트 결과 처리는 브라우저 이탈로 유실될 수 있음. 웹훅 엔드포인트를 함께 구현 (부트페이 발신 IP 223.130.82.0/24만 허용 + receiptPayment 재검증 + 멱등 처리)
API 키는 Admin CLI로 발급 → .env에 기록 — placeholder·추측값·랜덤 문자열 금지. create_keychain 또는 list_keychains 반환값만 사용
서버 인증은 Basic Auth — client_key/secret_key 기반. getAccessToken() 불필요
Secret Key는 서버 전용 — 절대 프론트엔드에 노출하지 않을 것

오프라인 · MCP 없이 사용하기

방법 1 — 최신 패키지를 파일로 받아서 설치 (사내망 등 npx 를 못 쓰는 환경)

npm pack @bootpay/mcp@latest # 최신 버전 .tgz 가 현재 폴더에 떨어집니다
npm install -g ./bootpay-mcp-*.tgz # 받은 파일로 전역 설치
bootpay-mcp --version # 설치된 버전 확인

GitHub Releases 의 고정 버전 파일을 받지 마세요. 최신 버전은 항상 npm 에 있습니다. 버전을 고정해야 한다면 npm view @bootpay/mcp versions 로 목록을 보고 @bootpay/mcp@2.1.0 처럼 명시하세요.

방법 2 — 문서만 AI 에게 전달 (npm/git 불필요, MCP 도구는 못 씀)

main.tar.gz 다운로드
AI 도구에 파일 첨부
"부트페이 결제 연동해줘"라고 요청

방법 3 — git clone (문서 참조용)

git clone https://github.com/bootpay/bootpay-mcp.git
# AGENTS.md, llms.txt, SDK_VERSIONS.md, SETUP_GUIDE.md 를 AI에게 전달

방법 2·3 은 문서만 전달합니다. Admin 도구(로그인·키 발급·코드 생성)는 stdio 로 MCP 를 붙여야 씁니다. 이 경우 AI 는 API 키를 자동 조회할 수 없으니, 아래 "MCP 없이 이 저장소만 참조하는 경우" 절을 따르세요.

About This Project

AI 코딩 도구(Claude, Cursor, Windsurf, Cline, GitHub Copilot 등)에서 Bootpay 결제·커머스를 연동할 수 있는 통합 Model Context Protocol (MCP) 서버입니다.

Docs (문서 검색·SDK 버전·트러블슈팅) + Admin (관리자 설정·PG·위젯·코드 생성) + Commerce (스토어·상품·회원) — 하나의 MCP 서버로 제공합니다.

stdio 로 붙으면 기본 75개(Docs 8 + Admin 67), Commerce 를 켜면 88개 도구가 노출됩니다. HTTP 로 붙으면 Docs 8개만 노출됩니다.

Supported PG & Payment Methods

Bootpay는 국내 주요 PG사와 간편결제를 통합 지원합니다:

PG사	코드	지원 결제
나이스페이 (NICE)	`nicepay`	카드, 계좌이체, 가상계좌, 휴대폰
토스페이먼츠 (Toss Payments)	`tosspayments`	카드, 계좌이체, 가상계좌, 휴대폰
KG이니시스 (KG Inicis)	`inicis`	카드, 계좌이체, 가상계좌, 휴대폰
NHN KCP	`kcp`	카드, 계좌이체, 가상계좌, 휴대폰
카카오페이 (Kakao Pay)	`kakao`	간편결제
네이버페이 (Naver Pay)	`naverpay`	간편결제
페이코 (PAYCO)	`payco`	간편결제
토스페이 (Toss Pay)	`tosspay`	간편결제
다날 (Danal)	`danal`	휴대폰 소액결제

결제 유형: 일반결제 (카드/계좌이체/가상계좌/휴대폰) · 정기결제 (빌링키) · 본인인증 · 에스크로 · 현금영수증

Quick Start

두 가지 연결 방식을 지원합니다:

방식	특징	추천 환경
HTTP (Streamable HTTP)	설치 불필요, 원격 서버	Cursor, Windsurf, Cline, 웹 기반
npm (stdio)	로컬 실행, Admin·Commerce 도구 사용 가능	Claude Desktop, Claude Code, Codex, Gemini CLI

0단계: 설치 — 반드시 최신 버전으로

stdio 설정에는 항상 @latest 를 붙이세요.

npx -y @bootpay/mcp@latest

⚠️@latest 를 빼면 예전에 받아둔 사본이 계속 실행됩니다.npx @bootpay/mcp 처럼 버전을 생략하면 npx 는 캐시(~/.npm/_npx/)에 남아 있는 사본을 먼저 씁니다. 한 번 받아둔 사람은 새 버전이 나와도 옛 버전을 계속 실행하게 되고, 그 사이에 고쳐진 것들이 전달되지 않습니다. 실제로 최근 릴리스에서 문서 검색이 조용히 빈 결과를 내던 문제 · 낡은 SDK 버전표 · 일부 도구가 인자를 거절하던 문제가 고쳐졌습니다. 옛 버전을 쓰면 AI 가 그 낡은 정보로 코드를 만듭니다.

지금 무엇이 실행되는지 확인하세요:

npm view @bootpay/mcp version # npm 에 올라온 최신 버전
npx -y @bootpay/mcp@latest --version # 실행될 서버의 버전 (v2.1.1 이상)

--version 은 v2.1.1부터 지원합니다. 그보다 낮은 버전이면 이 명령이 서버를 띄운 채 멈춥니다. 그럴 때는 Ctrl+C 로 끄고 — 그것 자체가 옛 버전이라는 신호이므로 — 아래 캐시 비우기를 바로 실행하세요.

두 값이 같으면 최신입니다. 다르면 캐시를 비우고 다시 받으세요:

npx clear-npx-cache # npx 캐시 비우기
rm -rf ~/.npm/_npx # 위 명령이 안 되면 (macOS/Linux)

Windows PowerShell:

Remove-Item-Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

항상 같은 버전을 고정해서 쓰고 싶다면 전역 설치도 됩니다. 대신 업데이트는 직접 해야 합니다:

npm install -g @bootpay/mcp@latest # 설치 · 업데이트 모두 이 명령
bootpay-mcp --version # 설치된 버전 확인

이 경우 MCP 설정의 command 는 npx 대신 bootpay-mcp 를 쓰고 args 는 비웁니다.

전제조건 — Node.js 18 이상

node -v # v18.0.0 이상이어야 합니다

node 명령이 없다면 https://nodejs.org 에서 LTS 를 먼저 설치하고, 터미널을 새로 여세요 (PATH 반영). Windows 는 설치 후 PowerShell 을 새로 열어야 node 가 잡힙니다.

설정을 저장한 뒤에는 AI 클라이언트를 완전히 종료하고 다시 켜세요. 설정 파일만 고치면 현재 세션에는 반영되지 않습니다. 도구 목록에 부트페이 도구가 안 보이면 대부분 이것 때문입니다. 확인: claude mcp list / codex mcp list / gemini mcp list

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows):

npm (stdio) — 추천:

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP (원격):

{
"mcpServers": {
"bootpay-docs": {
"command": "npx",
"args": ["mcp-remote", "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"]
}
}
}

Claude Code (CLI)

# npm (stdio)
claude mcp add bootpay-docs -- npx -y @bootpay/mcp@latest
# HTTP
claude mcp add bootpay-docs --transport http https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

Cursor

Settings → MCP Servers → Add:

{
"bootpay-docs": {
"url": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}

Codex (OpenAI)

~/.codex/config.toml:

stdio (권장, 전체 도구):

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]

HTTP (Docs 도구만, 설치 불필요):

[mcp_servers.bootpay]
url = "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"

Commerce 도구 활성화:

[mcp_servers.bootpay]
command = "npx"args = ["-y", "@bootpay/mcp@latest"]
[mcp_servers.bootpay.env]
BOOTPAY_COMMERCE_CLIENT_KEY = "YOUR_CLIENT_KEY"BOOTPAY_COMMERCE_SECRET_KEY = "YOUR_SECRET_KEY"

또는 CLI로 추가:

codex mcp add bootpay -- npx -y @bootpay/mcp@latest

설정 후 반드시 확인:
현재 Codex 세션을 종료하고 새 세션을 시작하세요
codex mcp list로 bootpay 서버가 보이는지 확인
보이지 않으면 ~/.codex/config.toml의 [mcp_servers.bootpay] 섹션을 재확인

Gemini CLI

~/.gemini/settings.json:

stdio (권장, 전체 도구):

{
"mcpServers": {
"bootpay": {
"command": "npx",
"args": ["-y", "@bootpay/mcp@latest"]
}
}
}

HTTP Streaming:

{
"mcpServers": {
"bootpay": {
"httpUrl": "https://bootpay-docs-mcp.rupy1014.workers.dev/mcp"
}
}
}

또는 CLI로 추가:

gemini mcp add bootpay npx -y @bootpay/mcp@latest

주의: Gemini CLI는 서버 이름에 언더스코어(_)를 사용하면 보안 정책 파싱 오류가 발생합니다. bootpay-docs ✅ / bootpay_docs ❌

Windsurf / Cline / Other MCP Clients

Streamable HTTP endpoint:

https://bootpay-docs-mcp.rupy1014.workers.dev/mcp

What AI Can Do with This MCP

MCP를 연결하면 AI가 다음을 직접 수행합니다:

사용자: "React에서 부트페이 카드결제 연동해줘"
AI 내부 동작:
1. get_sdk_versions → 최신 SDK 버전 확인 (v2 5.x)
2. get_setup_checklist → Client Key + 환경 설정 안내
3. search_docs → get_doc → payment/request 문서 조회
4. 코드 작성 → 문서 기반, 정확한 버전 사용

Docs Tools — 8개 (HTTP + stdio)

Tool	Description
`detect_project_stack`	프로젝트 스택 판정 — 클라이언트 플랫폼·웹 프레임워크·서버 언어·실행 환경(상시/서버리스). 모노레포면 앱마다 판정하고 "서버 1회 + 클라이언트 N회" 호출 계획을 반환
`get_sdk_versions`	모든 SDK 최신 버전 조회 (Web, Android, iOS, Flutter, React Native, 서버 7개 언어)
`search_docs`	120+ 개발자 문서 검색 (12 카테고리)
`get_doc`	특정 문서 전체 마크다운 조회
`list_docs`	카테고리별 문서 목록
`get_setup_checklist`	연동 환경 설정 체크리스트 (API 키, SDK 설치, .env)
`get_troubleshooting`	문제 해결 가이드 (onboarding, sandbox, webhook, billing, subscription, error, cancel, cors, csp, open-type, mobile, widget, unified, certification)
`get_csp_allowlist`	CSP(frame-src) 허용 PG 도메인 목록 + 프레임워크별 설정 스니펫 생성
`get_cs_guide`	고객응대(CS) 매뉴얼 검색

Prompt	Description
`integration-action-plan`	결제유형 × 플랫폼별 6단계 연동 액션 플랜

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Bootpay가 처음이라면 관리자 화면 대신 AI에게 전부 맡기세요. stdio 방식(npx -y @bootpay/mcp@latest)으로 연결하면 Admin 도구 67개가 활성화됩니다.

사용자: "부트페이 결제 연동하고 싶어. 처음이야"
AI 내부 동작:
1. browser_login → 브라우저 팝업으로 로그인
2. create_seller → 셀러(가맹점) 생성 + 기본 프로젝트 자동 생성
3. browser_select_project → 프로젝트 선택
4. activate_payment_method → 나이스페이 카드결제 활성화
5. set_sandbox_mode → 테스트 모드 설정
6. create_keychain(targets=["core"]) → 결제용 API 키 발급 (client_key, secret_key)
7. search_docs + get_doc → 최신 연동 문서 참조
8. 코드 생성 → 발급한 키를 .env에 설정, 코드에서 환경변수 참조

⚠️ 키를 코드에 직접 삽입하지 마세요. 발급한 키는 반드시 .env 파일에 저장하고, 코드에서는 환경변수로 참조합니다. Secret Key는 서버 .env에만 저장하세요. secret_key는 발급 시 1회만 평문으로 표시됩니다.

HTTP 방식에서는 Admin 도구를 사용할 수 없습니다. 프로젝트 설정이 필요하면 반드시 stdio(npx @bootpay/mcp@latest)를 사용하세요.

Admin Tools — 67개 (stdio 전용)

관리자(admin.bootpay.co.kr)의 설정을 AI가 직접 조회·변경할 수 있는 도구입니다. npx -y @bootpay/mcp@latest로 실행하면 자동 활성화됩니다.

카테고리	Tools	Description
코드생성	`generate_payment_code`, `generate_commerce_code`	프리플라이트(인증·키체인·결제수단·SDK 확인) + 클라이언트/서버 코드 원스톱 생성. `payment_type`: `payment`(일반) / `billing`(빌링키) / `subscription`(구독 — 회차·배치·무료체험·해지) / `widget` / `auth`, `scheduler`: `cron` / `http_trigger`(서버리스)
컨텍스트	`get_integration_context`, `get_commerce_context`	인증·프로젝트·결제설정·위젯·키체인을 한 번에 조회 (`readiness.blockers` 반환)
인증	`login`, `browser_login`, `logout`, `list_projects`, `switch_project`, `browser_select_project`, `set_token`, `get_auth_status`	로그인, 프로젝트 전환, 토큰 설정·상태 확인
셀러	`create_seller`, `search_sellers`, `get_seller`, `update_seller`	셀러(가맹점) CRUD
상세설명 블록	`list_content_templates`, `create_content_template`, `delete_content_template`, `list_content_blocks`, `create_content_block`, `update_content_block`, `delete_content_block`, `list_content_block_products`	상세설명을 블록으로 구성. 시작 템플릿(서버 저장분 + MCP 내장 스타터)과 여러 상품이 공유하는 공용 블록 관리. `content_type=4`일 때만 블록이 저장되며, HTML(`content`)은 서버가 컴파일해 채웁니다
디지털 코드풀	`list_digital_codes`, `register_digital_codes`, `disable_digital_code`	시리얼·라이센스 번호 일괄 등록/조회/폐기. `code_distribution_mode="pool"` 상품에서 구매자마다 다른 코드를 발급할 때 사용 (한 번에 최대 5,000개)
이미지	`upload_product_images`	로컬 경로·URL·base64 → Bootpay CDN 업로드 (최대 10장, 장당 10MB)
카테고리	`list_categories`, `create_category`, `update_category`, `delete_category`, `reorder_categories`	카테고리 CRUD. `path="상의 > 티셔츠 > 반팔"`로 계층 일괄 생성, 삭제는 `confirm` 확인 게이트
부속설정	`list_subscription_settings`, `list_delivery_shippings`, `create_subscription_setting`, `create_delivery_shipping`, `list_delivery_shipping_bundles`, `get_product_form_setting`, `get_product_info_notice_forms`	상품에 연결할 구독 설정·배송정책 ID 확보. 정책이 하나도 없는 프로젝트에서는 생성까지 가능 — 배송비·주기 같은 값이 빠지면 저장 대신 `need_answer` 로 무엇을 물어야 하는지 돌려줍니다(금액을 추측해 저장하지 않습니다). 폼 설정 조회로 판매자가 끈 섹션을 건너뛰고, 상품 주요정보(상품정보제공고시)의 상품군(1~40)과 군별 입력 항목도 조회
프로젝트	`create_project`	프로젝트 생성
키체인	`list_api_scopes`, `list_keychains`, `create_keychain`, `delete_keychain`, `get_commerce_keys`	API 키 발급/조회 (source 파라미터로 커머스/결제 구분)
상품	`list_products`, `get_product`, `create_product`, `update_product`, `delete_product`, `create_test_products`	상품 CRUD. `image_paths`로 로컬 사진 경로를 주면 업로드까지 처리, 구독(`subscription_setting_id`)·배송정책(`delivery_shipping_id`) 연결, 상세설명 블록(`content_blocks`), 디지털 지급(`digital_provisioning_type`), 환불정책 노출(`refund_policy_expose_type`) 지원
결제설정	`get_payment_settings`, `activate_payment_method`, `set_sandbox_mode`, `update_payment_resource`, `set_payment_mode`, `browser_select_payment_method`	PG·결제수단 설정
위젯	`list_widgets`, `get_widget`, `create_widget`, `get_widget_default_styles`, `configure_widget`, `update_widget`, `delete_widget`	결제위젯 CRUD
쇼핑몰설정	`get_mall_setting`, `update_mall_setting`	커머스 몰 기본 설정 조회·변경

상품·상세설명 블록·디지털 코드풀·카테고리·이미지 도구는 원격(OAuth) 프로파일에도 포함됩니다. 결제설정·키체인·자격증명 도구는 원격에서 제외됩니다 — 근거와 현재 상태는 원격 커넥터 문서를 보세요.

Commerce Tools — 13개 (stdio 전용, opt-in)

AI 에이전트가 커머스 API를 호출하여 쇼핑몰 기능을 구현할 수 있는 도구입니다. 활성화: 환경변수 BOOTPAY_COMMERCE_ENABLED=true 설정 후 실행.

카테고리	Tools	Description
인증	`set_commerce_credentials`	clientKey/secretKey 설정·검증
스토어	`commerce_get_store`, `commerce_get_store_detail`	가맹점 정보 조회
상품	`commerce_get_products`, `commerce_get_product`, `commerce_create_product`, `commerce_update_product`	상품 CRUD
회원	`commerce_login`, `commerce_get_session`, `commerce_logout`	회원 로그인·세션 관리
리뷰	`commerce_get_reviews`, `commerce_get_review_stats`	리뷰 조회·통계
상태	`commerce_status`	Commerce API 상태 확인

Supported Platforms & SDKs

Client SDKs

Platform	Package
Web (NPM)	`@bootpay/client-js`
Web (CDN)	`bootpay-{version}.min.js`
Android (Kotlin/Java)	`kr.co.bootpay:android`
iOS (Swift/ObjC)	`pod 'Bootpay'`
Flutter	`bootpay_flutter`
React Native	`react-native-bootpay-api`

Server SDKs

Language	Package
Node.js	`@bootpay/backend-js`
Python	`bootpay-backend`
Java / Kotlin	`kr.co.bootpay:backend`
Ruby	`bootpay`
Go	`github.com/bootpay/backend-go/v2`
.NET (C#)	`Bootpay`
PHP	`bootpay/backend-php`

Documentation Categories

Category	Content
`payment`	일반결제 — SDK 설치, 결제창, 서버 검증, 취소/환불
`billing`	정기결제 — 빌링키 발급, 자동결제, 예약결제, 해지
`subscription`	구독관리 — 플랜 생성, 갱신, 해지, 과금
`order`	주문관리 — 주문 생성, 취소, 반품
`customer`	고객관리 — 고객 등록, 그룹, 조회
`product`	상품관리 — 상품 CRUD, 옵션, 카테고리
`webhook`	웹훅 — 설정, 이벤트, 처리, 재시도 정책
`guide`	시작하기 — 키 발급, 환경설정, 개요
`integration`	연동 — 에러코드, 마이그레이션, 호환성
`invoice`	링크페이 — 결제 링크 생성, 알림
`recipes`	레시피 — 업종별 연동 시나리오
`architecture`	아키텍처 — 결제 플로우, 데이터 모델

Ask AI

MCP를 연결한 후 AI에게 이렇게 물어보세요:

부트페이 결제 연동 어떻게 해?
React에서 카드결제 연동하는 전체 코드 알려줘
Flutter에서 정기결제(빌링키) 발급 방법 알려줘
기존 프로젝트에 월 구독결제 붙여줘 (매일 배치로 결제, 같은 달 두 번 결제 방지, 성공 시에만 다음 달 이용 개방)
Next.js에서 결제 검증 서버 코드 작성해줘
웹훅 설정은 어떻게 하는거야?
결제위젯으로 카카오페이, 네이버페이 연동해줘
토스페이먼츠 PG로 가상계좌 결제 구현해줘

Architecture

두 가지 전송 방식을 지원하며, 도구 범위가 다릅니다:

 ┌─────────────────────┐
│ AI Coding Tool │
│ (Claude, Cursor, │
│ Windsurf, Cline, │
│ Codex, Gemini) │
└──────────┬──────────┘
│
┌─────────┴─────────┐
▼ ▼
[HTTP] [stdio]
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────────────┐
│ Cloudflare │ │ npx -y @bootpay/mcp@latest │
│ Workers │ │ │
│ bootpay-docs-mcp │ │ ┌─ Docs ( 8 tools) │
│ .workers.dev/mcp │ │ ├─ Admin (67 tools) │
│ │ │ └─ Commerce (13 tools)* │
│ Docs only │ │ │
│ (8 tools) │ │ * opt-in │
└────────┬─────────┘ └────────────────────────────┘
│
┌────────┴─────────┐
│ KV │
│ 120+ docs │
└──────────────────┘

전송	Docs (8)	Admin (67)	Commerce (13)	노출 도구 수
HTTP (Cloudflare Workers)	O	—	—	8
stdio (`npx -y @bootpay/mcp@latest`)	O	O	opt-in	75 (opt-in 포함 88)

stdio 의 detect_project_stack 은 root_path 로 로컬 파일시스템을 직접 훑습니다. HTTP 에서는 같은 도구가 노출되지만 파일을 볼 수 없으므로 files/file_contents 를 직접 넘겨야 합니다.

Stack: Cloudflare Workers + KV + MCP SDK + Streamable HTTP + stdio

Links

Bootpay Developer Docs
Bootpay Admin
Bootpay Official
MCP Protocol Specification
llms.txt — LLM-optimized documentation
사진과 설명으로 상품 올리기 — 판매자용 상품등록 가이드 (비개발자 대상)
원격 커넥터(ChatGPT · Claude) 연결 — OAuth 원격 연결 현황·검증 절차

Keywords

Bootpay, 부트페이, Korean payment gateway, 한국 결제, PG 연동, payment integration, MCP server, Model Context Protocol, AI coding assistant, LLM, Claude, Cursor, Windsurf, Cline, GitHub Copilot, 나이스페이, NICE, 토스페이먼츠, Toss Payments, KG이니시스, KG Inicis, NHN KCP, 카카오페이, Kakao Pay, 네이버페이, Naver Pay, 페이코, PAYCO, 다날, Danal, 정기결제, recurring payment, billing key, 빌링키, subscription, 구독결제, 결제위젯, payment widget, 결제 연동, checkout, 간편결제, easy payment, Cloudflare Workers

Name		Name	Last commit message	Last commit date
docs		docs
examples		examples
public		public
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
SDK_VERSIONS.md		SDK_VERSIONS.md
SETUP_GUIDE.md		SETUP_GUIDE.md
llms.txt		llms.txt

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Bootpay MCP Server

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

MCP 없이 이 저장소만 참조하는 경우

사용자에게 요청할 키 2개 (정확한 이름)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

핵심 규칙

오프라인 · MCP 없이 사용하기

About This Project

Supported PG & Payment Methods

Quick Start

0단계: 설치 — 반드시 최신 버전으로

Claude Desktop

Claude Code (CLI)

Cursor

Codex (OpenAI)

Gemini CLI

Windsurf / Cline / Other MCP Clients

What AI Can Do with This MCP

Docs Tools — 8개 (HTTP + stdio)

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Admin Tools — 67개 (stdio 전용)

Commerce Tools — 13개 (stdio 전용, opt-in)

Supported Platforms & SDKs

Client SDKs

Server SDKs

Documentation Categories

Ask AI

Architecture

Links

Keywords

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Bootpay MCP Server

AI Agents: 이 저장소를 참조받았다면 여기부터 읽으세요

⚡ 세션 프리플라이트 — 먼저 MCP 연결 상태를 확인하세요

stdio 모드 (Admin 도구 사용 가능) — 문서보다 Admin 도구를 먼저 사용하세요

MCP 없이 이 저장소만 참조하는 경우

사용자에게 요청할 키 2개 (정확한 이름)

❌ 흔한 실수 — 이 이름을 사용하지 마세요

핵심 규칙

오프라인 · MCP 없이 사용하기

About This Project

Supported PG & Payment Methods

Quick Start

0단계: 설치 — 반드시 최신 버전으로

Claude Desktop

Claude Code (CLI)

Cursor

Codex (OpenAI)

Gemini CLI

Windsurf / Cline / Other MCP Clients

What AI Can Do with This MCP

Docs Tools — 8개 (HTTP + stdio)

처음부터 끝까지: Admin CLI로 프로젝트 설정 → 결제 연동

Admin Tools — 67개 (stdio 전용)

Commerce Tools — 13개 (stdio 전용, opt-in)

Supported Platforms & SDKs

Client SDKs

Server SDKs

Documentation Categories