*** title: AI 도구로 결제 연동하기 description: Claude Code, Cursor, Codex 등 다양한 AI 도구를 활용해서 결제 연동을 쉽게 시작해보세요. keyword: AI, LLM, LLMs, Claude Code, Cursor, Codex, Gemini CLI, VS Code, Claude, Windsurf, MCP, Vibe Coding, 클로드 코드, 커서, 코덱스, 윈드서프, 바이브 코딩 ------------------------------------------------------------------------------------------------------------------------------------------ **Version 2** # AI 도구로 결제 연동하기 {description} AI 도구와 함께 개발하면 결제 연동 속도를 크게 높일 수 있어요. 토스페이먼츠가 AI 도구를 위해 제공하는 자원과 활용 방법을 알려드릴게요. ## AI를 위한 토스페이먼츠 자원 토스페이먼츠는 AI 도구가 결제 연동을 더 잘 이해하도록 3가지를 제공하고 있어요. title: LLM Quick Reference description: AI에게 결제 연동의 핵심을 한 번에 전달하는 페이지예요. href: /guides/v2/get-started/llms-quick-reference title: MCP 서버 description: AI가 토스페이먼츠 docs를 직접 검색하게 해주는 서버예요. href: #mcp-서버-활용하기 title: llms.txt description: AI에게 토스페이먼츠 docs 전체 구조를 알려주는 표준 인덱스예요. href: https://docs.tosspayments.com/llms.txt ## LLM Quick Reference [LLM Quick Reference](/guides/v2/get-started/llms-quick-reference)는 토스페이먼츠 결제 연동에 필요한 핵심을 한 페이지에 압축한 LLM 컨텍스트 페이지예요. 결제 흐름 모델·결정 룰·시나리오 진입점·자주 틀리는 패턴이 정리되어 있어서 AI가 첫 코드를 더 빠르고 정확하게 작성할 수 있어요. **활용 방법** * AI 채팅에 페이지 URL을 공유하거나 페이지 내용을 컨텍스트로 첨부해보세요. * "이 페이지 참고해서 결제 연동 코드 작성해줘"처럼 명시적으로 활용을 요청하면 더 안정적이에요. * 토큰 효율을 위해 본문이 영어로 작성되어 있어요. 디테일이 필요하면 아래 MCP 서버나 llms.txt를 함께 사용하세요. ## MCP 서버 활용하기 Model Context Protocol(이하 MCP)은 AI 모델이 다양한 상황과 맥락을 잘 이해하도록 돕기 위해 [Anthropic](https://www.anthropic.com/)이 정의한 표준이에요. 문제 상황에 적합한 MCP 서버를 활용하면 AI가 더 정확한 답변을 줄 수 있어요. 토스페이먼츠 MCP 서버를 설치하면 AI 도구가 토스페이먼츠 docs를 직접 검색해서 답변해요. ### MCP 서버 설치하기 **터미널 명령으로 설치하기** 터미널 명령을 지원하는 도구는 아래 명령 한 줄로 설치할 수 있어요. 설정 파일을 직접 편집하지 않아도 돼요. ```bash # Claude Code claude mcp add tosspayments-integration-guide -- npx -y @tosspayments/integration-guide-mcp@latest # Codex codex mcp add tosspayments-integration-guide -- npx -y @tosspayments/integration-guide-mcp@latest # Gemini CLI gemini mcp add tosspayments-integration-guide npx -y @tosspayments/integration-guide-mcp@latest # VS Code code --add-mcp '{"name":"tosspayments-integration-guide","command":"npx","args":["-y","@tosspayments/integration-guide-mcp@latest"]}' ``` **설정 파일로 설치하기** 설정 파일에 직접 추가해도 돼요. 대부분의 도구가 아래 형식을 사용해요. ```json title="mcp.json" { "mcpServers": { "tosspayments-integration-guide": { "command": "npx", "args": ["-y", "@tosspayments/integration-guide-mcp@latest"] } } } ``` VS Code는 최상위 키가 `mcpServers`가 아니라 `servers`예요. 위 JSON을 그대로 붙여넣으면 서버가 인식되지 않아요. ```json title=".vscode/mcp.json" { "servers": { "tosspayments-integration-guide": { "command": "npx", "args": ["-y", "@tosspayments/integration-guide-mcp@latest"] } } } ``` Codex는 JSON이 아니라 TOML 형식을 사용해요. ```toml title="~/.codex/config.toml" [mcp_servers.tosspayments-integration-guide] command = "npx" args = ["-y", "@tosspayments/integration-guide-mcp@latest"] ``` **도구별 설정 파일 경로** 자동 설치 링크를 지원하는 도구는 클릭 한 번으로 설정돼요. | AI 도구 | 설정 파일 | 자동 설치 | 공식 가이드 | | ---------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | **Claude Code** | `.mcp.json` (프로젝트) 또는 `~/.claude.json` (전역) | - | [↗](https://code.claude.com/docs/en/mcp) | | **Claude Desktop** | `claude_desktop_config.json` | - | [↗](https://modelcontextprotocol.io/docs/develop/connect-local-servers) | | **Codex** | `.codex/config.toml` (프로젝트) 또는 `~/.codex/config.toml` (전역) | - | [↗](https://learn.chatgpt.com/docs/extend/mcp) | | **Gemini CLI** | `.gemini/settings.json` (프로젝트) 또는 `~/.gemini/settings.json` | - | [↗](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) | | **Cursor** | `.cursor/mcp.json` (프로젝트) 또는 `~/.cursor/mcp.json` (전역) | [설치](cursor://anysphere.cursor-deeplink/mcp/install?name=tosspayments-integration-guide\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB0b3NzcGF5bWVudHMvaW50ZWdyYXRpb24tZ3VpZGUtbWNwQGxhdGVzdCJdfQ==) | [↗](https://cursor.com/docs/mcp) | | **VS Code** | `.vscode/mcp.json` (워크스페이스) | [설치](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22tosspayments-integration-guide%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40tosspayments%2Fintegration-guide-mcp%40latest%22%5D%7D) | [↗](https://code.visualstudio.com/docs/agent-customization/mcp-servers) | | **Devin Desktop (Windsurf)** | `~/.codeium/windsurf/mcp_config.json` | - | [↗](https://docs.devin.ai/desktop/cascade/mcp) | **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](https://docs.tosspayments.com/llms.txt)예요. **활용 방법** * AI 채팅에 "이 llms.txt 참고해서 답변해줘" 식으로 프롬프트에 첨부해보세요. * AI 도구마다 llms.txt를 다루는 방식이 달라요. 확실하게 쓰려면 프롬프트에 주소를 직접 알려주거나, 도구의 문서 소스로 등록하세요. * 결제수단별 디테일이 필요할 때 llms.txt를 참고하라고 명시하면 더 정확한 답변을 받을 수 있어요. > **참고**: llms.txt 표준에 대해 자세히 알고 싶다면 [llmstxt.org](https://llmstxt.org)를 방문해보세요. ## LLM에 질문하기 AI 도구에 자원을 연결한 뒤에 다양한 질문을 채팅으로 할 수 있어요. AI 답변이 이해되지 않거나 잘못된 경우 [토스페이먼츠 개발자 커뮤니티](https://techchat.tosspayments.com/)로 알려주세요. ### 활용 예시 **코드 생성** * "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`](https://docs.tosspayments.com/reference.md) — 코어 API 레퍼런스 * [`https://docs.tosspayments.com/guides/v2/payment-widget.md`](https://docs.tosspayments.com/guides/v2/payment-widget.md) — 결제 가이드 * [`https://docs.tosspayments.com/guides/v2/get-started/llms-guide.md`](https://docs.tosspayments.com/guides/v2/get-started/llms-guide.md) — 이 페이지 llms.txt에 명시된 페이지들도 모두 이 형식으로 가져갈 수 있어요. **Markdown으로 복사하기** 개발자 문서 페이지 상단의 **'Markdown으로 복사' 버튼**으로 페이지 내용을 markdown 형식으로 클립보드에 즉시 복사할 수 있어요. 페이지를 보면서 AI 도구에 바로 붙여넣을 때 편리해요. 바로 옆 **'AI에게 질문' 버튼**을 누르면 개발자 문서에서 곧바로 AI에게 물어볼 수 있어요. 도구를 따로 설치하지 않고 지금 보고 있는 문서를 기준으로 빠르게 확인할 때 사용하세요. ![개발자 문서의 'Markdown으로 복사'와 'AI에게 질문' 버튼](https://static.tosspayments.com/docs/glossary/9_card_easypay.png#1692x822)