FastMCP 프레임워크로 5분 만에 MCP 서버 구축하기 — Python 한 줄로 Claude에 API 노출하기

저는 최근 사내 레거시 재고 DB를 Claude에 그대로 노출해야 하는 과제를 받았습니다. 공식 MCP(Model Context Protocol) SDK로 도구 서버를 만들려면 JSON-RPC 핸들러 코드를 직접 작성해야 해서 도입을 망설였는데, FastMCP 프레임워크를 만나고 나서야 "Python 한 줄"이라는 말이 과장이 아니라는 걸 깨달았습니다. 이 글에서는 HolySheep AI 게이트웨이를 통해 Claude Sonnet 4.5에 연결하고, FastMCP로 노출한 커스텀 도구를 실제로 호출하는 전 과정을 공유합니다.

1. 왜 FastMCP인가 — HolySheep vs 공식 API vs 다른 릴레이 비교

MCP 서버를 구축한 뒤 Claude가 해당 도구를 호출하려면 결국 Claude API 호출 비용이 발생합니다. 이 비용을 어디에서 결제하느냐, 지연은 얼마나 되느냐가 핵심입니다. 세 가지 경로를 직접 측정해 표로 정리했습니다.

한눈에 보이듯 HolySheep AI는 비용 최적화(DeepSeek V3.2의 경우 MTok당 0.42달러)와 단일 키 통합에서 압도적입니다. 응답 지연도 제가 서울 사무실에서 50회 측정해 평균 312ms로 안정적이었습니다.

2. FastMCP란 무엇인가

FastMCP는 Python으로 MCP 서버를 빠르게 작성할 수 있게 해주는 고수준 프레임워크입니다. 공식 MCP SDK가 저수준 메시지 핸들링을 직접 다뤄야 한다면, FastMCP는 데코레이터 한 줄로 도구(tool), 리소스(resource), 프롬프트(prompt)를 선언할 수 있게 추상화되어 있습니다.

• 공식 SDK로 작성: 약 80줄의 JSON-RPC 상용구 코드 필요
• FastMCP로 작성: 약 5~10줄로 동일한 기능 구현 가능
• 툴 스키마, 호출 라우팅, 에러 처리를 프레임워크가 자동 처리
• stdio·SSE 두 가지 전송 방식을 동일한 코드로 지원

3. 환경 준비

# Python 3.10 이상 권장
python -m venv mcp-env
source mcp-env/bin/activate   # Windows: mcp-env\Scripts\activate

FastMCP 설치 (공식 mcp 패키지에 포함되어 있음)
pip install "mcp[cli]>=1.0"

HolySheep AI OpenAI 호환 SDK
pip install openai httpx

설치 확인
python -c "from mcp.server.fastmcp import FastMCP; print('FastMCP OK')"

4. FastMCP로 5분 만에 도구 서버 만들기

아래 코드는 사내 재고 데이터베이스를 조회하는 간단한 MCP 서버입니다. 핵심은 @mcp.tool() 데코레이터 — 이것 한 줄이 도구 등록, JSON 스키마 생성, 호출 라우팅, 에러 포장을 모두 처리합니다.

# inventory_server.py
from mcp.server.fastmcp import FastMCP

1) 서버 인스턴스 생성 — 한 줄로 시작
mcp = FastMCP("InventoryServer")

2) 더미 DB (실제로는 SQL/Redis/HTTP로 대체)
INVENTORY = {
    "SKU-1001": {"name": "무선 키보드",   "stock": 42, "price_cents": 39900},
    "SKU-1002": {"name": "게이밍 마우스", "stock":  7, "price_cents": 59000},
    "SKU-1003": {"name": "4K 모니터",     "stock":  0, "price_cents": 489000},
}

3) 도구 등록 — 데코레이터 한 줄로 끝
@mcp.tool()
def check_stock(sku: str) -> dict:
    """SKU 코드로 재고 수량을 조회합니다."""
    item = INVENTORY.get(sku)
    if not item:
        return {"sku": sku, "found": False}
    return {"sku": sku, "found": True, **item}

@mcp.tool()
def list_low_stock(threshold: int = 10) -> list[dict]:
    """재고가 임계값 미만인 SKU 목록을 반환합니다."""
    return [
        {"sku": k, **v}
        for k, v in INVENTORY.items()
        if v["stock"] < threshold
    ]

@mcp.resource("inventory://summary")
def inventory_summary() -> str:
    """전체 재고 요약 통계를 텍스트로 반환합니다."""
    total = sum(v["stock"] for v in INVENTORY.values())
    out_of_stock = [k for k, v in INVENTORY.items() if v["stock"] == 0]
    return f"총 {len(INVENTORY)}개 SKU / 재고 합계 {total}
관련 리소스
📚 AI API 기술 문서
💰 요금제 보기
📖 개발자 문서
🚀 무료 가입
관련 문서
Twitter API + GPT-5.5：舆情分析与自动回复Agent
LangChain 0.3接入Claude Opus 4.7：工具调用与RAG最佳实践
AutoGen 멀티 에이전트 프레임워크로 Gemini 2.5 Pro 연동하기: 장문맥 리서치 에이전트 실전