@nhnpayco-dev/mcp-devcenter

PAYCO 개발자센터 가이드(온라인결제·자동결제·오프라인결제·오더클라우드·멤버십클라우드·결제정산대사)를 AI 에디터(Claude·Cursor·VS Code 등)에서 바로 조회·검색할 수 있게 해주는 MCP(Model Context Protocol) 서버.

외부 가맹점/제휴사 개발자가 PAYCO 결제 연동을 진행할 때, 가이드 페이지를 일일이 뒤지지 않고 AI 에디터에 자연어로 물어 즉시 정확한 답을 받을 수 있게 해줍니다.

AI 에디터에 이렇게 물어보면 됩니다.

• "PAYCO 자동결제 빌링키 발급부터 결제까지 흐름 알려줘"
• "결제 승인 API 에 필수로 보내야 하는 파라미터가 뭐야?"
• "에러코드 4802 무슨 뜻이야?"
• "BC카드 코드값은 PAYCO 에서 어떻게 표기해?"

요구사항

• Node.js 20 LTS 이상 (node --version 으로 확인)
• 지원 클라이언트: Claude Desktop · Cursor · VS Code(Continue 등) · Windsurf 등 MCP 표준 호환 AI 에디터

설치는 자동입니다(npx 가 알아서 받습니다). 별도 빌드·환경 설정 불필요.

빠른 시작

Claude Desktop

claude_desktop_config.json 파일을 열어 mcpServers 항목에 아래를 추가하세요.

설정 파일 위치:

• Windows: %APPDATA%\Claude\claude_desktop_config.json (MS Store 버전: %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json)
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "payco-devcenter": {
      "command": "npx",
      "args": ["-y", "@nhnpayco-dev/mcp-devcenter@latest"]
    }
  }
}

저장 후 Claude Desktop 을 완전히 종료(시스템 트레이까지) 한 다음 다시 실행하세요. 입력창의 도구 메뉴에서 11개 도구(search_devcenter, get_guide, list_apis, get_api_spec, get_sample_code, get_error_code, get_checklist, list_validatable_apis, validate_payload, export_validation_excel, clear_validation_buffer)가 보이면 정상입니다.

Cursor

.cursor/mcp.json (프로젝트별) 또는 사용자 전역 설정에 추가:

{
  "mcpServers": {
    "payco-devcenter": {
      "command": "npx",
      "args": ["-y", "@nhnpayco-dev/mcp-devcenter@latest"]
    }
  }
}

VS Code (Continue · Cline 등 MCP 지원 확장)

각 확장의 MCP 설정에 동일 명령으로 등록하세요. 예시는 확장 문서를 따릅니다.

제공 도구 (11개)

가이드 조회 (6개)

| 도구 이름 | 설명 | |---|---| | search_devcenter(query) | 가이드 본문·제목·섹션에서 키워드 검색 (예: "결제 승인", "orderProducts") | | get_guide(slug) | 특정 카테고리 가이드 전체를 Markdown 으로 반환 | | list_apis() | 28개 카테고리 + 단계 목록 일람 | | get_api_spec(category) | 특정 카테고리(easypay, autopay …)의 API 명세·파라미터 표가 담긴 가이드 반환 | | get_sample_code(slug, language?) | 가이드 본문에서 코드 블록만 추출 (선택적으로 언어 필터링) | | get_error_code(code) | API 응답코드·결제수단·은행·카드사 등 모든 코드 카테고리에서 일치 항목 조회 |

자동 검수 (5개)

| 도구 이름 | 설명 | |---|---| | list_validatable_apis() | 자동 검증 가능한 API 슬러그 35개 목록 (URL·메서드·파라미터 수 포함) | | get_checklist(service) | 서비스별 사전 검수 체크리스트(자동 + 수동 항목). service: online/offline/order/membership | | validate_payload(api, payload) | API 요청 페이로드 JSON을 검증 — (1) 필수 누락 / 명세 외 파라미터 / 타입 불일치 + (2) 자동 체크리스트(개인정보·URL 인코딩·공백·금액 합산·enum·날짜 형식·returnUrl) + (3) 수동 확인 항목 | | export_validation_excel(path?, clearAfter?) | 누적된 검수 결과를 xlsx로 추출. 3개 시트: 검수요약 / 항목별 상세 / 공통검수체크리스트 | | clear_validation_buffer() | 누적된 검수 결과를 모두 초기화 (새 세션 시작 시) |

검증 도구 사용 예시 (외부 제휴사 시점)

① 페이로드를 붙여넣고 검수를 요청합니다.

이 페이로드 검수해줘. API는 online-easypay-01.

{
  "sellerKey": "S0FSJE",
  "sellerOrderReferenceKey": "ORD-001",
  "totalPaymentAmt": "15000",
  "orderMethod": "EASYPAY"
}

② 검수 결과가 돌아옵니다.

✗ FAIL — online-easypay-01 [POST] /outseller/order/reserve · 주문 예약 API로 결제창 호출하기 서비스: 온라인결제 · 자동실패 1개

검수 체크리스트 — 온라인결제 (22개) ✓ 개인정보 파라미터 미포함 · ✓ orderMethod 유효값 · ⬜ PAYCO 방화벽 등록 · …

API 명세 문제 (1개) ✗ totalPaymentAmt — 명세 number / 실제 string

③ 엑셀로 추출합니다.

엑셀로 추출해줘.

✅ ~/Downloads/payco-validation-20260522-180000.xlsx 생성 완료 시트: 검수요약 / 항목별 상세 / 공통검수체크리스트

⚠️ 운영 로그(실제 카드번호·주민번호·고객 연락처 포함)는 그대로 붙여넣지 말 것. 테스트 환경 로그 또는 마스킹된 로그를 사용하세요. 본 MCP 서버는 입력을 검증만 하고 저장하지 않지만, 검증 단계에서 Claude/Cursor 등 AI 측으로 텍스트가 전달됩니다.

사용 가능한 카테고리 슬러그 (28개)

online — 온라인 결제 online-start · online-easypay · online-autopay · online-etc · online-extra · online-extradata 🆕 · online-code · online-check · online-sample

offline — 오프라인 결제 offline-start · offline-vcat · offline-api · offline-authapi 🆕 · offline-code · offline-check · offline-sample

order — 오더 클라우드 order-start · order-vorder · order-code · order-check · order-sample

membership — 멤버십 클라우드 membership-start · membership-vmem · membership-api · membership-code · membership-check · membership-sample

calculate — 결제/정산 대사 calculate

🆕 표시는 PAYCO 개발자센터에는 없는 사내 문서 기반 가이드입니다.

자동 검증 가능한 API 슬러그 (35개)

온라인 — reserve / 승인 / 취소 online-easypay-01~04 · online-autopay-01~06 · online-etc-01/03/04 · online-extra-02/03

온라인 — reserve 변형 (합성) online-easypay-nonmember (비회원결제) · online-easypay-checkout (바로구매) · online-easypay-ordersheet (주문서결제)

부가정보 스키마 online-extradata — reserve API 의 extraData JSON 내부 26개 필드

오프라인 심플형 offline-api-02~05 인증승인형 🆕 offline-authapi-posauth · -auth · -approval · -cancel · -netcancel VCAT (DLL) offline-vcat-setpaycodata · -getpaycodata

오더 VORDER (DLL) order-vorder-setdata · -senddata

멤버십 API membership-api-05 VMEM (DLL) membership-vmem-execasyncapproval · -execcomplete · -execcancel

데이터 범위

본 패키지에 포함된 가이드 정보:

• PAYCO 개발자센터의 연동하기 > 온라인/오프라인/오더/멤버십 전 섹션 + 결제/정산 대사

• 사내 문서 기반 가이드 2종: 오프라인 POS 인증승인형 연동 가이드, 부가정보(extraData) 명세

• 가이드 본문 카테고리: 28개 (devcenter 크롤 26개 + 사내 문서 2개)

• 에러코드/코드값 표 항목: 500+ 개 (4개 root 의 API 응답코드, 결제수단, 카드사, 은행, VAN사, 결제수단 코드 등 통합)

• 자동 검증 가능한 API 명세: 35개

  • REST API 27개 (easypay/autopay/etc/extra/offline-api/authapi 등)
  • DLL 함수 7개 (offline-vcat, order-vorder, membership-vmem)
  • 합성 변형 슬러그 3개 (online-easypay-nonmember/-checkout/-ordersheet)

검증 가이드 사항 (자동 검증 한계):

• 조건부 필수 파라미터 (예: extraData.appUrl — iOS App 호출 시에만 필수)는 단순 "필수"로 표시될 수 있음
• returnUrl 등 URL 검사는 prefix(http:///https://)만 확인. URL 내부 공백·인코딩 오류는 감지 불가
• 배열 안 객체별 누락은 첫 객체 기준으로 검출

제외 범위:

• 보안사항 확인하기 (USERTrust 루트 인증서 설치 가이드)
• PAYCO 로그인 가이드 (별도 사이트 developers.payco.com)

최신 가이드 반영

PAYCO 개발자센터가 갱신될 경우 본 패키지도 주기적으로 재배포됩니다. 항상 최신을 받으려면 설정에서 @latest 태그를 유지하세요.

특정 시점에 고정하고 싶다면 @1.0.1 같이 버전을 명시할 수 있습니다.

문의 / 이슈

• PAYCO 가이드 자체 문의: [email protected]
• 본 MCP 서버 동작 문의: [email protected]

라이선스 / 출처

• 라이선스: MIT (패키지에 포함된 LICENSE 파일 참조)
• 가이드 본문 원본 저작권: NHN PAYCO Corp.
• 패키지 형태로 가공·배포: PAYCO 개발팀