첫 번째 MCP 서버 구축

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발

대상자

• 대상자: Python 및 FastAPI 기반 웹 서비스 개발자
• 난이도: 중간 (MCP 프로토콜 구현, HTTP API 설계, 테스트 프레임워크 사용 경험 필요)

핵심 요약

• MCP 프로토콜을 직접 구현하여 HTTP API 패턴 기반의 AI-agent Ready 서버를 구축
• FastAPI + Pydantic 스택 사용, search_products, get_product_details, check_inventory 등 핵심 기능 구현
• Docker 지원 및 pytest 기반 18개 이상 테스트 포함

섹션별 세부 요약

1. 프로젝트 구조 정의

• mcp_service/data.py에서 제품 데이터 정의 (PRODUCTS 리스트)
• search_products, get_product_details, check_inventory 함수를 통해 제품 검색 및 재고 확인 기능 구현
• requirements.txt에 fastapi, uvicorn, pydantic, pytest, httpx 의존성 명시

2. MCP 프로토콜 핸들러 구현

• mcp_service/handlers.py에서 MCPRequest/MCPResponse Pydantic 모델 정의
• /mcp/message 엔드포인트에서 capabilities, search_products, get_product_details, check_inventory 메서드 처리
• HTTP 상태 코드 기반 오류 처리 (-32602 매개변수 누락, -32603 내부 오류 등)

3. 서버 실행 및 테스트

• mcp_service/main.py에서 uvicorn을 사용한 서버 실행 (host="0.0.0.0", port=8000)
• curl 명령어로 capabilities, search_products, get_product_details 등 REST API 직접 호출 가능
• pytest tests/ 명령어로 18개 이상의 단위 테스트 실행 (예: test_search_products_message 성공)

4. AI Agent 클라이언트 예시

• MCPProductClient 클래스로 MCP 서버와의 상호작용 구현
• discover_capabilities() 및 call_tool() 메서드로 동적 도구 호출 가능
• httpx.AsyncClient를 사용한 비동기 HTTP 요청 처리

결론

• MCP 서버 구현 시 HTTP API 패턴을 중심으로 설계하여 라이브러리 변화에 대응 가능
• FastAPI, Pydantic, pytest를 활용한 모던 웹 개발 스택 적용 권장
• Docker 컨테이너화 및 자동화된 테스트를 통해 생산성과 안정성 확보
• GitHub 링크에서 전체 구현 코드 확인 가능