EnrichMCP 소개
EnrichMCP는 전통적인 REST API나 GraphQL이 아닌, AI 에이전트를 위한 스키마 기반 데이터 모델 API를 제공합니다. 이를 통해 LLM 기반으로 데이터 중심 에이전트를 제작할 때, 조직 내부의 도메인 지식과 데이터를 안전하게 공유할 수 있도록 돕습니다.
EnrichMCP는 FastMCP를 기반으로 만들어진 프레임워크로, Pydantic 모델을 기반으로 한 타입 안전 API를 AI 에이전트에게 노출하는 기능을 제공합니다. 단순한 CRUD API를 넘어서, AI가 탐색할 수 있는 스키마, 이해 가능한 관계 구조, 안전한 타입 시스템을 함께 제공합니다.
EnrichMCP는 “Agentic Enrichment”라는 패러다임을 중심으로 설계되었습니다. 이 개념은 AI에게 API를 설명하지 않고, API 스스로를 AI에게 설명하게 하는 구조입니다. 이러한 구조에 따라 에이전트는 EnrichMCP를 통해 explore_data_model()이라는 단일 호출만으로 전체 데이터 구조를 이해할 수 있으며, 이후 관련된 리소스를 호출하거나, 엔티티 간 관계를 따라가며 데이터를 탐색할 수 있습니다. 이 방식은 마치 GraphQL처럼 관계형 탐색이 가능하면서도, Pydantic 기반의 강력한 검증과 IDE 지원을 갖추고 있어, 개발자에게도 매우 친숙합니다.
EnrichMCP의 주요 특징
-
AI 친화적인 API 설계: 모든 모델, 필드, 관계는 설명을 포함해 자기 기술(Self-describing) 구조로 설계되어, 단 한 번의 호출(
explore_data_model())로 전체 데이터 모델 탐색할 수 있습니다. 특히, 관계 기반의 데이터 그래프를 따라 자연스럽게 탐색(Navigable)이 가능합니다. -
Pydantic 기반의 타입 안전성과 유효성 검증: 모든 입력과 출력에 대해 자동 검증이 적용되어 데이터 무결성 보장합니다. 또한, IDE 자동완성 및 타입 힌트 지원으로 개발 생산성을 높이는데 도움을 주며, 런타임 시 유효하지 않은 데이터 차단합니다.
-
보일러플레이트 최소화 및 직관적인 사용성:
@app.entity,@resolver,@resource같은 데코레이터를 활용해 설정을 간소화합니다. GraphQL과 ORM에서 영감을 받은 직관적인 API 구조를 제공하며, 관계, 필터링, 페이징, 캐시, 컨텍스트 등 고급 기능도 기본적으로 지원합니다.
EnrichMCP의 동작 방식은 아래와 같은 단계로 구성되어 있으며, 전체적인 흐름은 AI 에이전트가 데이터 모델을 탐색 → 접근 → 탐색 확장할 수 있도록 설계되어 있습니다:
EnrichMCP의 동작 방식
모델 정의 (Entity)
먼저 @app.entity 데코레이터를 사용해 Pydantic 기반의 도메인 모델을 정의합니다. 이 때, 아래와 같이 각 필드에는 설명(description)을 붙여 AI가 이해할 수 있도록 합니다:
@app.entity
class Customer(EnrichModel):
id: int = Field(description="고객 ID")
email: str = Field(description="이메일 주소")
관계 설정 (Relationship)
앞에서 정의한 Entity 간의 관계를 Relationship 객체로 선언합니다. 이는 AI가 데이터 그래프를 따라가며 탐색할 수 있게 해줍니다:
@app.entity
class Order(EnrichModel):
customer: Customer = Relationship(description="주문한 고객")
리졸버 구현 (Resolver)
각 관계에서 실제 데이터를 가져오는 함수(@resolver)를 정의합니다. 이는 관계 필드가 참조하는 데이터를 어디서 어떻게 가져오는지를 명시합니다:
@Order.customer.resolver
async def resolve_order_customer(order_id: int) -> Customer:
return await db.get_customer_by_order(order_id)
리소스 생성 (Resource)
마지막으로 AI 에이전트가 직접 호출할 수 있는 엔드포인트를 @app.resource로 제공합니다. 이 때, 기본 검색, 조회, 생성 등의 작업을 정의할 수 있습니다:
@app.resource
async def get_customer(customer_id: int) -> Customer:
return await db.get_customer(customer_id)
서버 실행
app.run()으로 FastAPI 기반 MCP 서버를 실행합니다. AI Agent는 이 서버에 접근하여 explore, get, search 등의 작업을 수행할 수 있습니다.
예를 들어, AI Agents의 동작은 다음과 같습니다:
explore_data_model()를 호출하여 전체 스키마 구조를 파악합니다.get_customer(),list_orders()등의 리소스를 통해 데이터에 접근합니다.- 관계 필드를 통해 다른 엔티티로 자연스럽게 이동하며 탐색합니다.
- 모든 과정에서 타입 검증, 필드 설명 등을 기반으로 정확한 호출할 수 있습니다.
EnrichMCP 공식 문서
EnrichMCP GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 