토스의 사내 Swagger MCP 서버 — Spring-AI로 API 스펙 공유 자동화

요약

API를 개발하면 Swagger에서 링크를 찾아 메신저로 공유하고, 스펙이 변경되면 다시 공유해야 합니다. 토스에서 이 반복을 없애기 위해 LLM이 Swagger에 직접 접근하는 MCP 서버를 Spring-AI로 구축한 과정에 대한 글입니다.

인사이트

• 대량 API를 가진 서버의 전체 스펙을 LLM에 넣으면 토큰 초과 에러 발생 — 미사용 API 제거, JSON 가공, API 그루핑 기반 페이징으로 해결
• SSE 방식은 서버 배포·연결 끊김 시 세션이 유실되어 사용 불가 — Stateless Streamable HTTP로 전환 후 안정화
• LLM이 MCP 서버를 호출하지 않는 경우가 빈번 — Prompt를 별도로 등록하여 호출을 유도해야 함

해결

1. Stateless Streamable HTTP + ASYNC 모드 선택

• SSE/일반 Streamable HTTP는 세션 유실 문제로 부적합, MSA 환경에 맞는 Stateless 방식 채택
• 네트워크 I/O가 많아 ASYNC 모드 적용

2. 4단계 API 스펙 조회 구조

• Step 1: SwaggerCenter에서 전체 서비스 목록 조회
• Step 2: 특정 서비스의 API 목록을 가공하여 반환 (URL, Method, summary만)
• Step 3: 특정 API의 상세 스펙 (parameters, requestBody, responses) 추출
• Step 4: $ref 참조 컴포넌트 스키마 별도 조회

3. Swagger 작성 자동화 (GitHub Actions)

• Controller 파일 변경 감지 → Gemini AI로 @Tag, @Operation 애너테이션 자동 추가 → PR에 코멘트

참고

Spring-AI 1.1.0-M3(Pre-release) 기반 개발이며, Swagger 컴포넌트 이름 충돌(springdoc.use-fqn=true), ArgumentResolver 파라미터 노출 문제 등 실무 트러블슈팅도 포함되어 있습니다.