한샘 Swagger MCP Server 개발 및 도입

2025년 12월 18일 (1년 전)

API 연동은 프론트엔드 개발에서 반복적이면서도 실수하기 쉬운 작업이다. Swagger 문서를 열어 endpoint를 찾고, request body 스키마를 확인하고, response 타입을 정의하는 일련의 과정이 매번 필요하다. Hanssem Swagger MCP는 사용자가 등록한 한샘 내부의 Swagger 문서를 탐색하여 이 과정을 LLM에게 위임할 수 있도록 설계된 Model Context Protocol 서버다.

MCP가 해결하는 문제

Model Context Protocol(MCP)은 LLM이 외부 데이터 소스에 접근할 수 있게 하는 표준 프로토콜이다. Swagger MCP 서버는 이 프로토콜을 통해 OpenAPI 문서를 LLM의 context로 제공한다. 개발자는 "user-service의 사용자 조회 API를 TypeScript로 연동해줘"라고 자연어로 요청하면, LLM이 직접 API 스펙을 조회하고 연동 코드를 생성한다.

핵심은 drill-down 방식의 조회 구조다. LLM의 토큰 제한을 고려해, 전체 스펙을 한 번에 로드하지 않고 list_services → list_apis → get_api_detail → get_components 순으로 필요한 정보만 단계적으로 가져온다.

Agentic Coding 워크플로우와의 통합

Swagger MCP의 진정한 가치는 Agentic Coding 워크플로우에서 드러난다. Claude Code나 Cursor 같은 AI 코딩 도구에서 개발자가 자연어로 작업 계획을 작성하면, LLM Agent가 이를 해석하고 필요한 도구를 자동으로 호출한다.

예를 들어, 개발자가 다음과 같은 계획을 작성했다고 하자:

## 작업 계획
1. 장바구니 페이지 컴포넌트 생성
2. order-service의 POST /api/cart API를 참고하여 장바구니 추가 기능 구현
3. user-service의 GET /api/users/{userId}/cart API로 장바구니 목록 조회 연동
4. 에러 핸들링 및 로딩 상태 처리

LLM Agent는 계획 내 "order-service의 POST /api/cart API를 참고"라는 자연어 표현을 인식하고, Swagger MCP 서버의 tool을 자동으로 호출한다. list_apis로 해당 API를 찾고, get_api_detail로 request/response 스키마를 조회한 뒤, 이 정보를 기반으로 실제 코드를 생성한다. 개발자가 별도로 Swagger 문서를 열어볼 필요 없이, 계획에 API 참조만 명시하면 Agent가 알아서 스펙을 가져와 작업에 반영하는 것이다.

이 워크플로우의 장점은 컨텍스트 전환 비용 제거에 있다. 기존에는 코드 작성 → Swagger 문서 확인 → 다시 코드 작성의 반복이 필요했다면, 이제는 계획 단계에서 필요한 API를 자연어로 언급하는 것만으로 전체 연동 과정이 자동화된다.

설정 방법

1. swagger-config.json 생성

조회할 Swagger 문서 목록을 JSON 파일로 정의한다:

{
  "services": [
    {
      "name": "user-service",
      "description": "사용자 관리 서비스",
      "environment": "dev",
      "url": "https://dev-api.example.com/v3/swagger-ui-json"
    },
    {
      "name": "order-service",
      "description": "주문 관리 서비스",
      "environment": "prod",
      "url": "https://api.example.com/swagger-ui-openapi.json"
    }
  ]
}

동일 서비스를 dev, stg, prod 등 여러 환경으로 등록할 수 있다. URL은 반드시 OpenAPI 3.0.x 또는 3.1.x 스펙을 따르는 JSON/YAML 문서여야 한다.

2. MCP 클라이언트 설정

Cursor, Claude Code 등 MCP를 지원하는 클라이언트에 서버를 등록한다. Claude Code의 경우 프로젝트 루트에 .mcp.json 파일을 생성한다:

{
  "mcpServers": {
    "hanssem-swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@hanssem/swagger-mcp@latest"],
      "env": {
        "SWAGGER_CONFIG_PATH": "/절대경로/swagger-config.json",
        "npm_config_@hanssem:registry": "사내 registry 주소",
        "npm_config_//사내 registry 주소/repository/npm-private/:_auth": "사내 registry 인증토큰"
      }
    }
  }
}

SWAGGER_CONFIG_PATH는 반드시 절대 경로로 지정해야 한다.

실제 활용 시나리오

API 연동 코드 생성

사용자: "order-service의 dev 환경에서 주문 생성 API를 사용해서
React 컴포넌트를 만들어줘"

LLM은 list_apis로 주문 생성 API를 찾고, get_api_detail로 request 스키마를 확인한 뒤, get_components로 참조된 타입 정의를 가져와 완성된 React 컴포넌트를 생성한다.

TypeScript 타입 정의 생성

사용자: "order-service의 주문 관련 API들을 조회해서
TypeScript 타입 정의 파일을 생성해줘"

API 스펙의 requestBody와 responses 스키마를 기반으로 interface/type 정의를 자동 생성한다.

테스트 코드 작성

사용자: "user-service의 사용자 생성 API 스펙을 보고
Jest 기반의 통합 테스트 코드를 작성해줘"

API 스펙에서 테스트 데이터와 검증 로직을 도출해 테스트 코드를 생성한다.

참고