MCP 연동하기

MCP(Model Context Protocol)는 AI 개발 도구가 외부 문서, 검색 도구, API 설명 같은 컨텍스트를 연결해서 사용할 수 있게 해주는 표준 방식입니다. NICEPAY PG 기술문서를 MCP 서버와 연결하면 가맹점 개발자는 AI 도구 안에서 결제 연동 흐름, 요청/응답 파라미터, 결과 코드, WebView 처리 방식 등을 문서 기준으로 확인하면서 개발할 수 있습니다.

이 문서는 NICEPAY PG 개발자센터 문서를 MCP 서버로 연결해 사용하는 방법을 안내합니다.

---

1. 활용 목적

MCP 서버를 연결하면 AI 도구가 현재 기술문서를 직접 조회하거나 검색한 뒤 답변할 수 있습니다.

• 결제창 호출, 승인 API, 망취소 API 등 연동 순서 확인
• 인증/비인증/PAYU/조회 API별 요청 파라미터 비교
• 결과 코드의 원인과 조치 방법 확인
• Android WebView, iOS WKWebView 연동 시 필요한 설정 확인
• 샘플 코드 작성 전 문서 기반으로 필수값과 서명 생성 규칙 검증

AI가 생성한 코드는 반드시 실제 기술문서의 요청/응답 규격과 가맹점 테스트 환경에서 다시 검증해야 합니다.

---

2. 사전 준비

MCP 서버를 사용하려면 아래 항목이 준비되어야 합니다.

항목	설명
AI 개발 도구	Cursor, VS Code, Claude Code, Claude Desktop, Codex, Windsurf 등 MCP를 지원하는 도구
MCP 서버 정보	NICEPAY PG 기술문서를 조회할 수 있는 MCP 서버의 실행 명령어 또는 사내 배포 패키지
문서 접근 권한	사내망 또는 배포된 개발자센터 URL에 접근 가능한 네트워크 환경
Node.js 또는 실행 런타임	npx 기반 MCP 서버를 사용하는 경우 Node.js와 npm 실행 환경 필요

회사 내부망에서 npm registry 접근이 제한되는 경우에는 사내 저장소에 미러링된 패키지, 로컬 실행 파일, 또는 사전에 설치된 MCP 서버 경로를 사용합니다.

---

3. MCP 서버 설정 예시

아래 설정은 예시입니다. 실제 command, args, 패키지명, 문서 URL은 NICEPAY에서 제공받은 값 또는 내부 배포 기준에 맞게 변경합니다.

3.1. JSON 설정 방식

Cursor, VS Code, Claude Code, Claude Desktop, Windsurf 등은 JSON 형식의 MCP 설정을 사용합니다.

{
  "mcpServers": {
    "nicepay-docs": {
      "command": "npx",
      "args": ["-y", "@nicepay/developers-mcp"],
      "env": {
        "NICEPAY_DOCS_BASE_URL": "https://{NICEPAY_PG_DEVELOPER_CENTER_URL}"
      }
    }
  }
}

로컬 문서 파일을 직접 조회하는 방식의 MCP 서버라면 문서 경로를 환경변수로 전달할 수 있습니다.

{
  "mcpServers": {
    "nicepay-docs": {
      "command": "node",
      "args": ["C:/node/nicepay-mcp-server/index.js"],
      "env": {
        "NICEPAY_DOCS_PATH": "C:/node/nicepay-manual/docs"
      }
    }
  }
}

3.2. Codex 설정 방식

Codex는 ~/.codex/config.toml 파일에 MCP 서버를 등록합니다.

[mcp_servers.nicepay-docs]
command = "npx"
args = ["-y", "@nicepay/developers-mcp"]

[mcp_servers.nicepay-docs.env]
NICEPAY_DOCS_BASE_URL = "https://{NICEPAY_PG_DEVELOPER_CENTER_URL}"

로컬 문서 기반으로 실행하는 경우에는 아래처럼 문서 경로를 지정할 수 있습니다.

[mcp_servers.nicepay-docs]
command = "node"
args = ["C:/node/nicepay-mcp-server/index.js"]

[mcp_servers.nicepay-docs.env]
NICEPAY_DOCS_PATH = "C:/node/nicepay-manual/docs"

---

4. 도구별 설정 파일 위치

사용 중인 AI 도구의 MCP 설정 파일에 서버 정보를 추가합니다.

도구	설정 파일 위치
Cursor	~/.cursor/mcp.json
VS Code	.vscode/mcp.json
Claude Code	프로젝트 루트의 .mcp.json 또는 ~/.claude.json
Claude Desktop	claude_desktop_config.json
Codex	~/.codex/config.toml
Windsurf	~/.codeium/windsurf/mcp_config.json

설정 파일을 수정한 뒤 AI 도구를 재시작하거나 MCP 서버 목록을 새로고침합니다.

---

5. MCP 서버가 제공하면 좋은 도구

NICEPAY PG 문서용 MCP 서버는 아래와 같은 도구를 제공하도록 구성하는 것을 권장합니다.

도구명	용도
search-documents	기술문서 전체에서 키워드 검색
get-document	특정 문서의 원문 또는 섹션 조회
get-result-code	결과 코드별 메시지와 조치 방법 조회
get-partner-code	카드사, 은행 등 제휴사 코드 조회
list-release-notes	릴리즈 노트 또는 변경 이력 조회

도구명은 MCP 서버 구현 방식에 따라 달라질 수 있습니다. AI 도구에서 질문할 때는 "NICEPAY MCP 문서를 조회해서 답변해줘"처럼 MCP 사용을 명시하면 문서 기반 답변을 유도할 수 있습니다.

---

6. 문서 기준 추천 질문

MCP 서버 연결 후 아래처럼 질문하면 연동에 필요한 정보를 빠르게 확인할 수 있습니다.

NICEPAY MCP 문서를 사용해서 결제창 호출부터 승인 API까지 연동 순서를 알려줘.

비인증 카드키인 API의 필수 요청 파라미터와 SignData 생성 규칙을 문서 기준으로 정리해줘.

가상계좌 발급 후 입금 통보를 처리할 때 확인해야 할 문서를 찾아줘.

ResultCode 4101의 의미와 확인해야 할 연동 항목을 알려줘.

Android WebView에서 카드사 앱 호출이 안 될 때 확인해야 할 Manifest 설정을 찾아줘.

---

7. 주요 문서 경로

MCP 서버가 문서를 검색할 때 우선 참조하면 좋은 대표 문서입니다.

구분	문서
인증 결제 소개	/docs/pg/intro
결제창 호출	/docs/pg/auth/payment-window
승인 API	/docs/pg/auth/authorization
망취소 API	/docs/pg/auth/net-cancel
비인증 결제 소개	/docs/pg/non-auth/intro
카드키인 API	/docs/pg/non-auth/card-keyin
빌키 발급 API	/docs/pg/non-auth/billkey-create
가상계좌 발급 API	/docs/pg/non-auth/virtual-account
결제통보	/docs/pg/add/noti
APP WebView 연동	/docs/pg/add/app-webview
거래조회 API	/docs/pg/inquiry/trans-inquiry
결과 코드	/docs/pg/result-code/intro
Release Notes	/release-notes

---

8. 보안 유의사항

AI 도구와 MCP 서버를 사용할 때는 운영 환경의 민감정보가 전달되지 않도록 주의해야 합니다.

• 운영 MerchantKey, API 인증 정보, 내부 계정 정보는 AI 도구에 입력하지 않습니다.
• 카드번호, 계좌번호, 휴대폰번호, 구매자 정보 등 개인정보를 그대로 입력하지 않습니다.
• 문서 예시 데이터 또는 테스트 환경 데이터를 사용합니다.
• AI가 생성한 SignData, 해시 생성 코드, 인코딩 처리 코드는 반드시 문서 규격과 테스트 요청으로 검증합니다.
• MCP 서버가 외부망에서 실행되는 경우 접근 가능한 문서 범위와 로그 저장 정책을 확인합니다.

---

9. 문제 해결

증상	확인 항목
MCP 서버가 목록에 표시되지 않음	설정 파일 경로, JSON/TOML 문법, AI 도구 재시작 여부 확인
npx 실행 실패	Node.js 설치 여부, npm registry 접근 가능 여부, 사내망 차단 여부 확인
문서를 검색하지 못함	NICEPAY_DOCS_BASE_URL 또는 NICEPAY_DOCS_PATH 값 확인
AI가 일반 지식으로 답변함	질문에 "NICEPAY MCP 문서를 조회해서"라고 명시
특정 문서만 누락됨	MCP 서버의 색인 대상에 docs/pg, docs/mcp, release-notes 경로가 포함되었는지 확인

MCP 서버 연결이 정상이어도 AI 답변은 보조 수단입니다. 실제 연동 기준은 NICEPAY PG 개발자센터의 최신 문서와 가맹점 테스트 결과를 우선합니다.