Bootpay Developer Docs MCP Server

Bootpay MCP Server

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

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

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

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

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

확인 방법:

# Codex
codex mcp list          # bootpay 서버가 보이는지 확인

# Claude Code
claude mcp list         # bootpay 서버가 보이는지 확인

# Gemini CLI
gemini mcp list         # bootpay 서버가 보이는지 확인

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

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 서버가 발급한 값만 유효합니다.

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

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

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

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

프론트엔드 빌드 도구에 따라 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 (서버 전용, 프론트엔드 노출 금지)

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

핵심 규칙

• SDK v2 (5.x) only — bootpay-3.x.x.min.js, bootpay-4.x.x.min.js는 v1(deprecated)이며 동작하지 않음
• 결제는 프론트엔드에서 시작 — 국내 PG 규정. 백엔드에서 결제를 시작하는 코드 금지
• API 키는 Admin CLI로 발급 → .env에 기록 — placeholder·추측값·랜덤 문자열 금지. create_keychain 또는 list_keychains 반환값만 사용
• 서버 인증은 Basic Auth — client_key/secret_key 기반. getAccessToken() 불필요
• Secret Key는 서버 전용 — 절대 프론트엔드에 노출하지 않을 것

MCP 없이 사용하기

MCP 설정이 어렵거나 npm을 사용할 수 없는 환경에서는, 이 저장소를 직접 다운로드해서 AI에게 전달하세요:

방법 1 — npm 패키지 직접 설치 (npm registry 불필요)

npm install https://github.com/bootpay/bootpay-mcp/releases/download/v2.0.2/bootpay-mcp-2.0.2.tgz

방법 2 — tar.gz 다운로드 (npm/git 불필요)

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

방법 3 — git clone

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

About This Project

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

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

Supported PG & Payment Methods

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

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

Quick Start

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

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"]
    }
  }
}

HTTP (원격):

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

Claude Code (CLI)

# npm (stdio)
claude mcp add bootpay-docs -- npx -y @bootpay/mcp

# HTTP
claude mcp add bootpay-docs --transport http https://mcp.bootpay.ai/mcp

Cursor

Settings → MCP Servers → Add:

{
  "bootpay-docs": {
    "url": "https://mcp.bootpay.ai/mcp"
  }
}

Codex (OpenAI)

~/.codex/config.toml:

stdio (권장, 전체 도구):

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

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

[mcp_servers.bootpay]
url = "https://mcp.bootpay.ai/mcp"

Commerce 도구 활성화:

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

[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

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

Gemini CLI

~/.gemini/settings.json:

stdio (권장, 전체 도구):

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

HTTP Streaming:

{
  "mcpServers": {
    "bootpay": {
      "httpUrl": "https://mcp.bootpay.ai/mcp"
    }
  }
}

또는 CLI로 추가:

gemini mcp add bootpay npx -y @bootpay/mcp

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

Windsurf / Cline / Other MCP Clients

Streamable HTTP endpoint:

https://mcp.bootpay.ai/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 — 7개 (HTTP + stdio)

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

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

사용자: "부트페이 결제 연동하고 싶어. 처음이야"

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)를 사용하세요.

Admin Tools — 34개 (stdio 전용)

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

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

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

Supported Platforms & SDKs

Client SDKs

Server SDKs

Documentation Categories

Ask AI

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

부트페이 결제 연동 어떻게 해?
React에서 카드결제 연동하는 전체 코드 알려줘
Flutter에서 정기결제(빌링키) 발급 방법 알려줘
Next.js에서 결제 검증 서버 코드 작성해줘
웹훅 설정은 어떻게 하는거야?
결제위젯으로 카카오페이, 네이버페이 연동해줘
토스페이먼츠 PG로 가상계좌 결제 구현해줘

Architecture

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

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

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

Links

• Bootpay Developer Docs
• Bootpay Admin
• MCP Protocol Specification
• llms.txt — LLM-optimized documentation

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