API 연동 자동화를 위한 여정: 토스는 왜 사내 MCP 서버를 개발하였는가? with Spring-AI

Swagger 링크를 찾아 공유하고 변경된 API 스펙을 다시 확인하는 번거로움을 줄이기 위해, 토스는 Spring AI 기반의 사내 Swagger MCP 서버를 구축했습니다. 서버 목록, API 요약, 상세 스펙, 컴포넌트 스키마를 단계별 도구로 제공하고, 원격 환경의 세션 유실을 피하려 Stateless Streamable-HTTP와 비동기 실행을 선택했습니다. 대량 스펙으로 인한 토큰 초과는 불필요한 정보 제거와 API 그룹화·페이징으로 완화했으며, 도구 호출을 돕는 MCP Prompt도 추가했습니다. 정확한 Swagger 문서가 LLM 활용의 기반이며, 자동 문서화에는 도메인 맥락을 보완할 방법이 필요하다는 점을 얻었습니다.

• LLM에 대량의 Swagger 원문을 한꺼번에 전달하면 토큰 한도에 걸릴 수 있으므로, 필요한 필드만 추리고 API를 그룹화해 단계적으로 조회하세요.
• 원격 MCP 서버에서 세션 유실이 문제가 된다면 Stateless Streamable-HTTP를 검토하고, 네트워크 I/O가 많은 작업에는 비동기 실행을 고려할 수 있습니다.
• LLM이 도구를 적절히 호출하지 않는다면 재사용 가능한 MCP Prompt를 제공해 호출에 필요한 입력과 작업 맥락을 명시하세요.
• Swagger 문서의 정확도는 LLM이 얻는 컨텍스트 품질에 영향을 줍니다. 자동 생성만으로 부족한 도메인 지식은 RAG나 추가 컨텍스트로 보완해야 합니다.