Version 2
AI 도구로 결제 연동하기
Claude Code・Cursor・Codex 같은 AI 도구로 결제를 연동하는 방법이에요. 토스페이먼츠가 제공하는 MCP 서버와 llms.txt, LLM Quick Reference 를 설정하고 활용하는 방법을 알아보세요.
AI 도구와 함께 개발하면 결제 연동 속도를 크게 높일 수 있어요. 토스페이먼츠가 AI 도구를 위해 제공하는 자원과 활용 방법을 알려드릴게요.
AI를 위한 토스페이먼츠 자원
토스페이먼츠는 AI 도구가 결제 연동을 더 잘 이해하도록 3가지를 제공하고 있어요.
LLM Quick Reference
LLM Quick Reference는 토스페이먼츠 결제 연동에 필요한 핵심을 한 페이지에 압축한 LLM 컨텍스트 페이지예요. 결제 흐름 모델·결정 룰·시나리오 진입점·자주 틀리는 패턴이 정리되어 있어서 AI가 첫 코드를 더 빠르고 정확하게 작성할 수 있어요.
활용 방법
- AI 채팅에 페이지 URL을 공유하거나 페이지 내용을 컨텍스트로 첨부해보세요.
- "이 페이지 참고해서 결제 연동 코드 작성해줘"처럼 명시적으로 활용을 요청하면 더 안정적이에요.
- 토큰 효율을 위해 본문이 영어로 작성되어 있어요. 디테일이 필요하면 아래 MCP 서버나 llms.txt를 함께 사용하세요.
MCP 서버 활용하기
Model Context Protocol(이하 MCP)은 AI 모델이 다양한 상황과 맥락을 잘 이해하도록 돕기 위해 Anthropic이 정의한 표준이에요. 문제 상황에 적합한 MCP 서버를 활용하면 AI가 더 정확한 답변을 줄 수 있어요.
토스페이먼츠 MCP 서버를 설치하면 AI 도구가 토스페이먼츠 docs를 직접 검색해서 답변해요.
MCP 서버 설치하기
터미널 명령으로 설치하기
터미널 명령을 지원하는 도구는 아래 명령 한 줄로 설치할 수 있어요. 설정 파일을 직접 편집하지 않아도 돼요.
설정 파일로 설치하기
설정 파일에 직접 추가해도 돼요. 대부분의 도구가 아래 형식을 사용해요.
VS Code는 최상위 키가 mcpServers가 아니라 servers예요. 위 JSON을 그대로 붙여넣으면 서버가 인식되지 않아요.
Codex는 JSON이 아니라 TOML 형식을 사용해요.
도구별 설정 파일 경로
자동 설치 링크를 지원하는 도구는 클릭 한 번으로 설정돼요.
| AI 도구 | 설정 파일 | 자동 설치 | 공식 가이드 |
|---|---|---|---|
| Claude Code | .mcp.json (프로젝트) 또는 ~/.claude.json (전역) | - | ↗ |
| Claude Desktop | claude_desktop_config.json | - | ↗ |
| Codex | .codex/config.toml (프로젝트) 또는 ~/.codex/config.toml (전역) | - | ↗ |
| Gemini CLI | .gemini/settings.json (프로젝트) 또는 ~/.gemini/settings.json | - | ↗ |
| Cursor | .cursor/mcp.json (프로젝트) 또는 ~/.cursor/mcp.json (전역) | 설치 | ↗ |
| VS Code | .vscode/mcp.json (워크스페이스) | 설치 | ↗ |
| Devin Desktop (Windsurf) | ~/.codeium/windsurf/mcp_config.json | - | ↗ |
MCP 서버가 잘 연결되지 않을 때
- AI 도구의 MCP 설정 화면에서
tosspayments-integration-guide서버가 활성 상태인지 확인하세요. - 설정 파일로 설치했다면 최상위 키가 도구에 맞는지 확인하세요. VS Code는
servers, 나머지 도구는mcpServers예요. npx명령이 실행 가능한 환경인지(Node.js 설치 여부) 확인하세요. 회사 네트워크에서는 npm 레지스트리 접근이 차단될 수 있어요.- AI가 MCP 도구를 사용하지 않는 것 같다면 "토스페이먼츠 MCP를 사용해서 답변해줘"처럼 명시적으로 도구 사용을 요청해보세요.
MCP 서버가 제공하는 도구
| 도구 | 사용자 관점에서 동작 |
|---|---|
get-v2-documents | "결제 코드 짜줘" 등 버전을 명시하지 않은 질문에 → AI가 V2 문서를 자동으로 검색해요 (기본 동작) |
get-v1-documents | "V1으로 작성해줘" 등 V1을 명시한 질문에 → AI가 V1 문서를 자동으로 검색해요 |
get-glossary-documents | "가상계좌 입금 정책 알려줘", "AML이 뭐야" 등 결제 용어·정책·백서 관련 질문에 → AI가 용어집 문서를 자동으로 조회해요 |
document-by-id | 특정 페이지 디테일이 필요할 때 → AI가 문서 ID로 원본 전체를 조회해요 |
llms.txt
llms.txt는 LLM이 웹사이트 정보를 효과적으로 탐색하도록 돕는 표준 파일이에요. 토스페이먼츠 docs 인덱스가 LLM이 읽기 좋은 형태로 정리되어 있어서, AI 도구가 이 파일을 보고 정확한 페이지를 찾아갈 수 있어요.
토스페이먼츠 llms.txt 주소는 https://docs.tosspayments.com/llms.txt예요.
활용 방법
- AI 채팅에 "이 llms.txt 참고해서 답변해줘" 식으로 프롬프트에 첨부해보세요.
- AI 도구마다 llms.txt를 다루는 방식이 달라요. 확실하게 쓰려면 프롬프트에 주소를 직접 알려주거나, 도구의 문서 소스로 등록하세요.
- 결제수단별 디테일이 필요할 때 llms.txt를 참고하라고 명시하면 더 정확한 답변을 받을 수 있어요.
llms.txt 표준에 대해 자세히 알고 싶다면 llmstxt.org를 방문해보세요.
LLM에 질문하기
AI 도구에 자원을 연결한 뒤에 다양한 질문을 채팅으로 할 수 있어요. AI 답변이 이해되지 않거나 잘못된 경우 토스페이먼츠 개발자 커뮤니티로 알려주세요.
활용 예시
코드 생성
- "V2 SDK로 주문서 안에 결제 UI를 삽입하는 코드를 작성해줘"
- "결제 승인 요청하는 Node.js 서버 코드를 작성해줘"
- "가상계좌 발급 후 입금 콜백을 처리하는 코드를 작성해줘"
- "구독 결제(빌링) 흐름을 처음부터 끝까지 만들어줘"
에러 디버깅
- "결제 승인 API에서
ALREADY_PROCESSED_PAYMENT에러가 나와요. 원인이랑 해결법 알려줘" - "결제창에서
INVALID_REQUEST에러가 뜨는데 어떻게 해결하지?"
도큐먼트 조회
- "토스페이먼츠 빌링 API의 요청 바디 필드를 모두 알려줘"
- "결제수단별 취소 정책 차이를 표로 비교해줘"
추가 Tip
페이지 내용을 markdown으로 가져오면 외부 AI 도구에 붙여넣어 질문할 때 페이지의 맥락(결제 흐름, 정책, 코드 예시 등)을 그대로 전달할 수 있어서 더 정확한 답변을 받을 수 있어요. 두 가지 방법이 있어요.
페이지 markdown 원본 접근
모든 docs 페이지는 URL 끝에 .md를 붙이면 markdown 원본을 받을 수 있어요. AI 도구의 컨텍스트로 직접 전달할 때 편리하고, HTML 파싱이 필요 없어 토큰 효율도 좋아요. 탭에 숨겨진 콘텐츠도 모두 노출돼요.
예시:
https://docs.tosspayments.com/reference.md— 코어 API 레퍼런스https://docs.tosspayments.com/guides/v2/payment-widget.md— 결제 가이드https://docs.tosspayments.com/guides/v2/get-started/llms-guide.md— 이 페이지
llms.txt에 명시된 페이지들도 모두 이 형식으로 가져갈 수 있어요.
Markdown으로 복사하기
개발자 문서 페이지 상단의 'Markdown으로 복사' 버튼으로 페이지 내용을 markdown 형식으로 클립보드에 즉시 복사할 수 있어요. 페이지를 보면서 AI 도구에 바로 붙여넣을 때 편리해요.
바로 옆 'AI에게 질문' 버튼을 누르면 개발자 문서에서 곧바로 AI에게 물어볼 수 있어요. 도구를 따로 설치하지 않고 지금 보고 있는 문서를 기준으로 빠르게 확인할 때 사용하세요.
