본문으로 건너뛰기
긴 문서에서 결제 연동에 필요한 맥락을 찾는 토스페이먼츠 MCP
목차

긴 문서에서 결제 연동에 필요한 맥락을 찾는 토스페이먼츠 MCP (2025-06)

원문 정보

  • 원문: 토스페이먼츠 결제 시스템 연동을 돕는 MCP 서버 구현기
  • 매체 · 게시일: 토스 기술 블로그 · 2025-06-24
  • 저자: 김용성 (토스페이먼츠)
  • 원문은 코드가 많이 첨부돼 길다고 안내하며, 길드(서로 다른 팀의 구성원이 느슨하게 모여 관심사를 공유하는 조직)의 작은 논의에서 시작된 아이디어로 구현했다고 밝힙니다.
  • 원문 내용을 바탕으로 재구성한 요약입니다.

정확한 코드가 부족했던 결제 연동

토스페이먼츠는 직관적인 API와 SDK를 새로 만들고 개발자 센터도 마련했지만, 결제 연동이 어려운 고객사는 여전히 많았습니다. 특히 개발팀이 없는 작은 가맹점과 외부에 개발을 맡긴 사업자가 그랬습니다. AI 코딩 도구로 연동 코드를 작성해 봐도 정확도가 떨어졌습니다.

선택한 해법은 대규모 언어 모델(LLM)에 연동 맥락을 제공하는 MCP였습니다. USB가 컴퓨터와 주변기기를 연결하는 표준이듯, MCP는 AI 모델과 여러 환경을 연결하는 표준입니다. 서버 하나를 Cursor, Claude, Windsurf 같은 도구에서 사용할 수 있다는 점을 결제 연동에 활용했습니다.

MCP 연결 뒤 달라진 Cursor

완성한 MCP 서버의 효과는 같은 프롬프트로 비교했습니다. 연동 기술 문제를 지원하는 Technical Account Manager가 Cursor 단독, Docs Context 추가, MCP 연결 조건을 시험했습니다. 각 조건에서 index.html에 토스페이먼츠 V2 SDK로 결제위젯을 연동하고, successUrl 로직을 만들고, 승인 API를 호출해 달라는 요청을 동일하게 사용했습니다.

조건생성된 코드에서 확인한 결과
Cursor 단독JS SDK 주소 오류. 인증·승인 흐름은 어느 정도 맞았으나 세부 스펙과 일부 로직 오류
Cursor + Docs ContextSDK 주소 확인 실패. 클라이언트에서 승인 API 호출, 클라이언트 코드에 Secret Key 노출
Cursor + MCPSDK 주소와 세부 연동 스펙에 맞는 코드 생성. 결제 처리 흐름에 문제 없음

차이는 SDK 주소에만 있지 않았습니다. MCP를 연결한 Cursor는 “승인 API 호출해줘”라는 요청에 Secret Key를 안전하게 보관하고 외부에 노출하지 않아야 하므로, 승인 API를 반드시 백엔드 서버에서 호출해야 한다고 안내했습니다.

개발자 센터와 함께 갱신되는 로컬 MCP

AI에 줄 콘텐츠를 제품별로 새로 만드는 데는 시간과 비용이 많이 듭니다. 토스페이먼츠에는 이미 MDX 기반 개발자 센터가 있었고, 문서는 CI/CD 과정에서 CDN에 배포되고 있었습니다. MCP 서버가 이 콘텐츠를 읽으면 문서 버전업을 그대로 따라갈 수 있다고 보고, LLM의 웹사이트 콘텐츠 이해를 돕는 llms.txt를 만들어 프로토타입을 구성했습니다.

전송 방식으로는 WebSocket이나 SSE 기반의 원격 MCP도 검토했지만, 로컬 실행을 선택했습니다. CDN의 개발자 센터 문서를 단일 기준으로 삼는 SSOT를 유지하고, 각 사용자의 장비에서 실행하므로 사용자가 늘어도 MCP 서버 비용이 발생하지 않는 방식입니다. MCP 스펙에 STDIO Transport가 있었고, NPM에 배포하면 검증된 패키지 매니저를 사용할 수 있어 추가 관리 비용도 들지 않았습니다.

긴 문서 앞에서 잦아진 LLM 호출

첫 버전은 사전 정의된 키워드로 문서를 찾았습니다. LLM이 get-keywords로 목록을 받아 사용자 질의에 맞는 키워드를 고르면, documents-by-keywords가 문서를 순회하며 조건별 점수를 계산해 상위 10개를 반환했습니다. 문서 속 Markdown 링크는 documents-by-link로 따라가고, 찾은 문서는 document-by-id로 읽는 흐름이었습니다.

운영 중에는 AI가 엉뚱한 결과를 내는 Hallucination과 중요한 정보의 누락이 잦았습니다. LLM 호출 빈도도 늘었습니다. 문서 길이가 제각각인 데다 긴 것은 5,000라인을 넘었는데, LLM이 이런 문서를 여러 번 질의하며 체크포인트를 만들거나 대화를 요약하는 동안 중요한 정보가 유실되는 것으로 추측했습니다.

필요한 청크에 앞뒤 맥락을 붙인 BM25

두 번째 버전은 문서를 의미 있는 조각인 청크로 나누고, Gemini와 대화하며 찾은 BM25로 관련 부분을 고르는 방식입니다. Okapi BM25에서 유래한 이 검색 모델은 질의어가 자주 나오는 문서의 점수를 높입니다. 여러 문서에 흔하게 등장하는 단어는 IDF로 가중치를 낮추고, 문서 길이에 따라 빈도의 영향을 보정합니다.

형태소 분석기 없이 나눈 한국어 질의

당시 JavaScript에는 Python처럼 잘 구현된 BM25가 없어 GPT의 도움으로 구현했습니다. 하지만 한국어에 바로 적용하기는 어려웠습니다. “BM25는 정보 검색에 사용되는 랭킹 함수입니다.”를 영어식으로 공백 토큰화하면 bm25는, 검색에, 함수입니다처럼 조사와 어미가 붙은 토큰이 남아, 같은 의미도 표현에 따라 일치하지 않았습니다.

형태소 분석 라이브러리는 쓰지 않았습니다. Java나 C 같은 추가 환경 설정을 요구해 로컬 MCP의 사용성이 나빠질 수 있다고 판단했기 때문입니다. 대신 도구와 파라미터를 LLM이 고른다는 점을 이용해, LLM에 질의를 의미 있는 키워드로 나누게 하고 그 키워드를 정규식으로 바꿔 매번 BM25 점수를 계산했습니다.

헤더를 따라 자른 문서 청크

질의를 잘 나눠도 문서가 너무 크다는 문제는 남습니다. unified와 remark-parse로 마크다운을 AST로 변환한 뒤, unist-util-visit으로 순회하며 depth가 2 이하인 heading(#, ##)을 경계로 잘랐습니다. 너무 잘게 나누면 정보가 유실되거나 의미 없는 조각이 될 수 있어, joinShortChunks로 30단어 미만의 청크를 이어 붙였습니다. 이 함수의 기본값은 minWords = 30입니다.

청크는 TossPaymentsDocument에서 관리하고 점수는 TossPaymentsBM25Calculator에서 계산합니다. 계산기의 기본 계수는 k1 1.2, b 0.75입니다. v1과 v2 문서에 각각 공통 문서를 합쳐 버전별 계산기를 따로 뒀습니다.

청크 하나만으로는 맥락이 모자랄 수 있습니다. 헤더로 나눈 구간이라도 질문의 답은 인접한 내용과 함께 있어야 온전해질 수 있어, getChunkWithWindow로 검색된 청크와 앞뒤 청크를 묶어 LLM에 전달했습니다.

검색 도구도 get-v1-documents와 get-v2-documents로 바뀌었습니다. 반환된 청크를 읽은 LLM이 문서를 더 자세히 탐색하려면 document-by-id를 호출합니다.

이렇게 바꾼 뒤에는 한 번의 질의로 관련 정보를 폭넓게 찾고, 불필요한 정보와 Hallucination을 줄이는 효과를 확인했습니다. 벡터 DB만큼 정밀하지는 않지만 외부 의존성 없이 로컬에서 RAG를 구현한 방식입니다.

초기 비용은 늘었습니다. 첫 버전은 필요할 때 각 문서를 읽어 초기 로딩 비용과 메모리 사용량이 적었지만, 두 번째 버전은 시작 시점에 llms.txt에 포함된 모든 문서를 불러와 메모리 소비와 부트스트랩 비용이 커졌습니다.

BM25 계수와 청크 설정
항목값
BM25 k1 / b1.2 / 0.75
청크 분할 기준heading depth 2 이하 (#, ##)
짧은 청크 병합 기준30단어 미만
검색 결과상위 10개 (topN = 10)
인접 청크 window1
1차 버전 도구get-keywords, documents-by-keywords, documents-by-link, document-by-id
2차 버전 도구get-v1-documents, get-v2-documents, document-by-id
실험 조건Cursor 단독 / Cursor + Docs Context / Cursor + MCP

검색 개선을 위해 남겨 둔 백로그

AI가 생성하는 코드가 100% 완벽하지는 않습니다. 글 작성 시점에는 모델에 제공하는 맥락 정보도 부족할 수 있다고 밝혔습니다. 개선안으로는 특정 키워드의 BM25 점수에 가중치를 주는 방법, 개발 관련 질문과 기술 블로그 문서를 분리하고 카테고리별로 도구를 구분하는 방법 등이 백로그에 정리돼 있었습니다.

마지막 수정 일자