Introduce
들어가기에 앞서, 본 글에서는 Claude Code 같은 LLM 기반 AI 에이전트를 편의상 “AI”라고 하겠습니다.
최근 AI가 기하급수적으로 발전하면서 Claude Code나 Codex 와 같은 AI Agent들은 개발 과정에서 빠질 수 없는 요소가 됐다. 대부분의 많은 개발자들이 터미널 환경에 AI를 붙여 개발을 진행하고 있다. 나 역시 최근 외부 활동을 하며 프로젝트를 진행중에 있는데, 구현 로직을 작성하거나 테스트 코드를 만드는 등 대부분의 작업에서 Claude Code를 활용하고 있다. 개발자는 점점 직접 구현하는 역할 보다는 빠르게 만들고, 검증하고, 조합하는 역할에 가까워지고 있다.
다만 내가 현재 진행중인 프로젝트에서는 AI가 API 연동 과정에서는 충분히 이어지지 못하고 있다. 구현과 테스트는 AI가 빠르게 초안을 만들어주지만 정작 연동 단계에서는 클라이언트 개발자가 직접 Swagger UI를 열고, 수십개의 API들을 스크롤로 찾아가며, 요청과 응답 구조를 눈으로 확인한 뒤 코드를 작성하고 있다. 그러다보니 API 연동과정에서 필드 타입이나 nullable 여부, 에러 핸들링 누락 등과 같은 실수가 쉽게 발생할 수 있다.
이 방식이 나쁘다라기 보다 AI가 개발의 default가 된 시대에 우리가 API 문서를 다루는 방식이 최적화되지 못한 상태라고 생각한다. 그래서 API 문서를 사람이 직접 탐색하지 않고, AI가 질의해서 개발자에게 필요한 정보를 바로 제공하는 형태로 바꿔보고자 한다.
Problem Definition
현재의 API 연동 흐름은, 개발자가 코드를 작성하는 작업과 별개로 직접 문서를 탐색하고, 해석하는 작업이 강하게 요구되어 진다. 이 과정에서 발생하는 문제를 크게 두 가지로 나눌 수 있다.
1. 개발자의 컨택스트 스위칭이 누적되어 개발 흐름이 끊긴다.
AI를 활용해 빠르게 구현하던 맥락이 API 연동 단계에서는 갑자기 멈추고, 문서를 찾고, 구조를 해석하고 DTO 타입을 직접 생성하는 작업으로 전환된다. 그리고 이 작업은 API 마다 반복된다.
이러한 개발자의 컨택스트 스위칭은 생각보다 비용이 높고, 개발 속도를 낮추는 병목이 된다.
2. 에러가 발생하기 쉽다.
인적 자원의 수 작업이 필연적이기 때문에 필드 타입, nullable 여부, 에러 처리 누락 등 실수하기 쉬운 작업들이 많다. 그리고 이러한 작은 실수가 실제로 서비스의 큰 버그로 이어질 수도 있다. 하지만 이는 사람이 직접 옮겨 적는 구조에서는 실수를 완전히 제거하기 어렵다.
결국 문제의 본질은 AI가 개발의 default가 된 흐름 속에서 API 문서가 질의 가능한 형태로 편입되지 못했다는 점이다. 이러한 문제를 해결하기 위해, Swagger API 문서를 AI가 확인하고, 필요한 정보를 즉시 제공할 수 있는 Swagger MCP Server를 구상하게 되었다.
Development Goals
📌 시스템의 흐름
현재 만들고자 하는 시스템의 흐름은 다음과 같다.
1. 클라이언트 개발자가 자연어로 API를 질의한다.
개발자는 "여행 저장 API 알려줘"와 같이 기능 단위로 질문한다.
2. AI는 MCP Server를 통해 Swager API Spec을 탐색하고, 정리한다.
엔드포인트, 요청/응답 구조, 에러 코드등 API 연동에 필요한 정보를 개발자가 읽기 쉬운 형태로 제공한다.
3. 정리된 결과를 바탕으로 API 연동 코드 생성까지 AI에게 위임한다.
개발자는 API 스펙을 다시 해석하거나 수동으로 DTO를 옮겨 적지 않고, 기본적인 연동 코드와 에러 처리까지 AI에게 위임할 수 있다.
4. 개발자는 생성된 코드를 검증하고, 조정한다.
직접 구현을 하지 않고, 생성된 연동 코드를 검증하고, 필요한 부분만 수정한다.
📌 핵심 목표
이 프로젝트의 1차 목표는 완성도 높은 MCP 시스템을 만드는 것이 아니라 AI가 주도하는 개발 환경에서 API 연동까지도 AI에게 작업을 위임하는 것을 빠르게 검증하는 것이다.
그러므로 기능의 완성도나 범위 확장보다는 연동을 AI에게 맡기는 것이 실질적으로 유의미한가? 를 확인하는것이 1차 핵심 목표라고 할 수 있다.
Tech Stack
📌 Server
서버는 Java + Spring Boot + Spring AI로 개발할 예정이다.
자프링(Java + Spring)의 경우 내가 가장 많이 사용해온 스택이라 구현 속도가 아무래도 가장 빠를 것 같다. 그리고 MVP 단계에서는 새로운 언어와 프레임워크 학습 비용을 줄이고, 핵심 기능에 대해서 검증하는 것이 우선이라고 생각하였다.
Spring AI의 경우 예전부터 MCP 서버를 직접 구축하게 되면 꼭 사용해봐야겠다라는 니즈가 있었다.
거기다 자프링을 코어로 잡았기에 Spring 생태계 안에서 MCP 서버를 비교적 쉽게 구축할 수 있다고 생각하여 선택하게 되었다.
📌 Infra
서비스의 인프라는 AWS를 기반으로 구성하고, Terraform으로 관리할 계획이다.
AWS는 워낙 익숙하기도 하고, MVP 단계에서 빠르게 환경을 구성하기에 적합하다고 생각한다. 필요한 구성 요소(서버, 데이터베이스, 네트워크)를 비교적 짧은 시간 안에 갖출 수 있고, 운영 관점에서도 선택지가 명확하다.
여기서 하나 특이한 점은 IaC 도구로 Terraform을 사용한다는 것이다. 사실 Terraform은 아직 실전 경험이 없다. 그럼에도 이번 프로젝트에서 Terraform을 선택한 이유는 두 가지다.
첫째, 최근 외부 활동을 하면서 여러 서버/인프라 구성에서 Terraform을 정말 자주 마주쳤다. “많이 쓰는 도구”라는 사실만으로도 학습 가치가 충분했고, 언젠가가 아니라 이번 기회에 직접 써보자는 동기가 생겼다.
둘째, 이 프로젝트의 큰 목적이 “AI를 활용해 생산성을 끌어올리는 것”이라면, 인프라도 그 방향과 일관되게 가져가고 싶었다. 인프라가 수동 설정이나 콘솔 클릭에 의존하면, 변경 이력과 맥락이 흩어지고 반복 작업이 늘어난다. 하지만 Terraform처럼 인프라가 코드로 표현되면, 구성의 의도를 문서화하기 쉬워지고 수정도 명확해진다. 무엇보다 코드 형태라면, 리뷰, 리팩토링, 개선 제안 같은 영역에서 AI의 도움을 더 쉽게 받을 수 있다고 생각했다.
이렇게 정리해보니, 이번 프로젝트에서 IaC를 선택하지 않을 이유가 오히려 없는 것 같다.
📌 DB
데이터베이스는 MySQL을 선택하였다.
LLM 연동이나 검색을 생각하면 자연스럽게 Vector DB를 떠올릴 수 잇지만, 프로젝트의 목표는 AI가 비슷한 API를 추천 해주는 것이 아니라 정확한 API Spec을 조회하고, 전달하는 것이다. Swagger API는 요청/응답, 에러코드처럼 정형화된 데이터가 중심이라, MySQL로도 충분히 구현이 가능하다고 판단했다.
또한 Vector DB를 한번도 사용해본적 없는 상황에서 러닝 커브가 크다고 생각했다. 그렇기에 우선은 MySQL로 단순하게 시작하고, Vector DB가 필요하다고 생각되면 추후에 고려해볼 계획이다. (Terraform 도 공부해야하는데 Vector DB는 언제함..)
Architecture
아래는 Swagger MCP Server의 전체 흐름을 나타낸 아키텍처이다.
현재는 단순 플로우의 구상도이기 때문에 단순 참고용으로 그려보았다. 또한 API Spec을 동기화를 하는 방법에 대한 정책은 아직 고민중이라 해당 플로우에는 담지 못했다. 그리고 인프라와 관련된 요소도 빠졌기에 개발이 완료되면 시스템 아키텍처를 추가해볼 예정이다.