MCP 서버 개발: 에이전틱(Agentic) AI를 API의 '첫 번째 고객(customer zero)'으로 만들기

Red Hat Trusted Profile Analyzer(TPA)와 Trustify 엔지니어링 팀은 MCP(모델 컨텍스트 프로토콜, Model Context Protocol)를 실험해 보기로 했습니다. 이 글에서는 우리가 그 과정에서 직면했던 여러 과제를 소개하며, 비슷한 시도를 하고 있는 다른 이들에게 도움이 되기를 바랍니다.

먼저 배경을 간략히 설명하자면 Red Hat Trusted Profile Analyzer(TPA)는 SBOM(Software Bill of Materials) 관리를 위한 Red Hat 제품으로, SBOM을 저장하고 SBOM 내의 패키지와 알려진 공개 취약점을 연관시킵니다. 업스트림 프로젝트 Trustify를 기반으로 합니다.

전체적인 아키텍처는 상당히 '전통적'입니다.

• 프론트엔드 개발: React와 PatternFly 컴포넌트(trustify-ui) 사용
• 백엔드 개발: Rust 사용, 데이터베이스 인스턴스 연결 및 SBOM S3 호환 스토리지 저장

진행했던 주요 단계는 다음과 같습니다.

1. TPA/Trustify와의 MCP 서버 통합 설계
2. MCP 서버의 툴 설명 정의
3. MCP 서버의 툴 매개변수 설계

이 글에서는 각 단계에서의 주요 고려 사항을 다루며, 최종 결과물로 GitHub에서 확인할 수 있는 MCP 서버를 소개합니다. 

TPA/Trustify와의 MCP 서버 통합 설계

MCP 서버와 Trustify 간의 통합 방식을 정의하기에 앞서, 우리는 소프트웨어 엔지니어가 흔히 겪는 딜레마에 직면했습니다. 이 프로젝트에 어떤 라이브러리를 채택해야 할까요? 처음부터 직접 모든 것을 직접 개발해야 할까요?

오픈소스의 진정한 신봉자로서, 우리는 MCP 서버 구현을 위한 Rust 라이브러리(Trustify는 주로 Rust로 개발되어 있으므로 Rust 라이브러리가 선호되었음)의 현재 환경을 살펴보았습니다.

MCP가 GitHub 조직에서 공식적으로 제공하는 여러 라이브러리 중 하나가 Rust로 개발되어 있었기 때문에 조사는 오래 걸리지 않았습니다.

이 라이브러리는 MCP 서버 개발에 필요한 코드를 포함할 뿐 아니라, 시작하기 좋은 다양한 예제도 함께 제공합니다.

MCP 서버를 실행하고 매개변수와 함께 사용 가능한 툴을 정의하기 위한 라이브러리별 세부 정보 외에도, 우리는 MCP 서버가 '백엔드' 데이터에 어떻게 액세스할지를 결정해야 했습니다.

두 가지 옵션을 평가했습니다. MCP 서버는 다음 중 하나를 통해 데이터를 검색할 수 있습니다.

• Trustify 백엔드가 데이터를 저장하는 데이터베이스(DB)에 직접 연결하는 방식, 또는
• Trustify 백엔드에서 제공하는 REST 엔드포인트를 호출하는 방식

두 방식 모두 장단점이 있었고, 이에 대한 활발한 논의가 이어졌습니다. 그 요약은 다음과 같습니다.

DB에 직접 연결하는 경우의 장점:

1. 데이터에 빠르게 액세스할 수 있음
2. 텍스트-SQL(text-to-SQL) 접근 방식을 적용할 기회가 있음

단점:

1. MCP 서버가 백엔드와 동일한 아키텍처 레벨에 위치해야 함
2. 백엔드 코드와 비교하여 데이터 액세스를 관리하기 위해 코드를 중복 작성해야 함
3. MCP 툴 호출 결과를 정의하려면 데이터 형식을 별도로 관리해야 함

REST 엔드포인트 호출의 장점:

1. 기존 백엔드 API의 인증 및 권한 부여 체계를 그대로 준수하는 호출
2. MCP 서버에서 액세스하는 데이터가 UI에서 보는 데이터와 완전히 일치함(같은 데이터 소스 사용)
3. 백엔드 API가 반환하는 출력을 그대로 전달함으로써 무료로 JSON 형식 출력 사용 가능

단점:

1. 더 많은 아키텍처 티어를 거쳐야 하므로 성능 저하

최종적으로 우리는 MCP 서버의 툴에서 REST 엔드포인트를 호출하는 방식을 선택했습니다. MCP 서버를 백엔드와 DB 근처에 함께 배치해야 하는 직접 연결 방식이 큰 제약이 되었기 때문입니다. 특히 MCP 서버가 개발자의 로컬 호스트에서 stdio 전송 방식으로 실행되는 경우, 이 제약은 심각한 문제로 작용했습니다.

모든 데이터를 '무료로' JSON 응답 형태로 포맷할 수 있다는 점도 초기 개발 단계에서 큰 이점이었습니다.

MCP 서버의 툴 설명 정의

MCP 서버의 툴이 백엔드 API를 호출하기로 결정한 후, 우리는 각 툴을 어떻게 설명할지 정의해야 했습니다. 첫 번째 단계(iteration)에서는 각 MCP 툴이 단일 백엔드 API 엔드포인트를 호출하도록 설계했습니다.

Trustify는 OpenAPI openapi.yaml 파일을 통해 사용 가능한 엔드포인트를 문서화한다는 점을 고려하여, OpenAPI 엔드포인트의 설명과 정의를 MCP 툴의 설명으로 사용하기로 했습니다. 이를 통해 엔드포인트의 도큐멘테이션이 사용자에게 얼마나 유용한지 평가할 수 있었습니다. 이로 인해 에이전틱(Agentic) AI가 API의 '첫 번째 고객'이 되었습니다.

이 모든 작업은 지속적인 개선을 위한 접근 방식으로 이루어졌습니다. 만약 Trustify의 API 설명이 LLM이 처리할 만큼 명확하다면, 사용자도 그 도큐멘테이션을 쉽게 이해할 수 있다고 보았습니다.

이 접근 방식은 각 엔드포인트를 개선하는 데 도움이 되었으며, 자연스럽게 다음 설계 결정 단계로 이어졌습니다.

MCP 서버의 툴 매개변수 설계

이 단계에서는 툴 호출 시의 입력 매개변수 처리와 관련된 문제에 직면했습니다. 이를 이해하기 위해 한 걸음 물러서야 했습니다. 엔티티 목록을 검색하는 Trustify 엔드포인트는 q라는 쿼리 매개변수를 수락합니다. 이 매개변수를 사용하면 사용자가 OpenAPI 사양에 정의된 문법을 기반으로 쿼리를 지정할 수 있습니다. 

고려한 옵션은 다음과 같습니다.

1. 엔드포인트의 q 경로 매개변수를 MCP 툴의 입력 매개변수로 직접 노출하는 방법
2. q 매개변수 값을 빌드하는 데 사용할 수 있는 내부 필드를 MCP 툴의 입력 매개변수로 노출하는 방법

우리는 두 가지 접근 방식을 모두 테스트했습니다.

첫 번째 접근 방식은 쿼리 매개변수에 대한 강력하고 상세한 설명을 필요로 하지만, 현재 OpenAPI 사양에는 그러한 세부 설명이 제공되어 있지 않습니다. 쿼리 가능한 필드의 전체 목록은 도큐멘테이션의 선택 항목이 아니라 필수 요소로 포함되어야 한다고 판단했습니다. 이 정보가 제공된다면 모든 사용자에게 유용할 것이기 때문입니다.

두 번째 접근 방식은 AI 에이전트에 있어 더 간소화된 방식이었습니다. 취약점 심각도, 게시일, 설명 등과 같이 쿼리 가능한 매개변수를 명시적으로 나열하면, LLM이 이를 직접 더 쉽게 활용할 수 있습니다. 이 접근 방식은 첫 번째 방식에서 필요했던 LLM의 복잡한 쿼리 문법 해석 단계를 제거해 줍니다.

다만, MCP 툴에서 이용 가능한 모든 매개변수를 명시적으로 나열할 경우 실제 백엔드 엔드포인트 구현과의 일관성을 지속적으로 유지해야 하는 부담이 발생합니다. 반면에 사용 가능한 매개변수의 하위 집합만 노출하면 툴의 유연성이 줄어들고, 유지보수 부담이 줄어든다는 보장도 없습니다.

결론적으로 우리는 MCP 툴에서 q 쿼리 매개변수를 사용하기로 했습니다. OpenAPI 정의 내에서 q 매개변수의 설명을 강화하여 모든 사용자가 개선된 도큐멘테이션의 이점을 누리게 할 예정입니다.

결론

MCP 서버를 설계할 때 다음과 같은 접근 방식을 채택했습니다.

• MCP 서버는 기존 API를 활용
• MCP 서버는 기존 OpenAPI 도큐멘테이션을 활용
• MCP 서버 툴은 원격 API 엔드포인트가 기대하는 동일한 매개변수를 노출

앞서 언급했듯이 최종 결과는 GitHub에서 확인할 수 있습니다.