MCP 서버 구축의 실전 교훈

카테고리

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

서브카테고리

DevOps

대상자

• 대상자: MCP 서버를 개발하거나 AI 에이전트와 연동하는 개발자
• 난이도: 중급 이상 (MCP 프로토콜 이해 및 서버 구축 경험 필요)

핵심 요약

• MCP 서버의 핵심 구성 요소:
• @mcp.resource()와 @mcp.tool()을 활용한 도구(Tools) 및 자원(Resources) 정의
• 프롬프트(Prompts)를 통해 LLM과의 상호작용 구현
• 트랜스포트 방식의 진화:
• stdio → SSE → Streamable HTTP (현재 최적화된 방식)
• 라이브러리 활용:
• FastMCP 사용을 권장 (스트리밍 지원, 빠른 배포)

섹션별 세부 요약

1. MCP 서버의 주요 구성 요소

• 도구(Tools): 특정 작업을 수행하는 함수 (예: @mcp.tool("math/add"))
• 자원(Resources): 파라미터 기반의 데이터 조회 (예: @mcp.resource("availability://{user_id}/date"))
• 프롬프트(Prompts): LLM에 전달되는 템플릿 (예: PyAirbyte에서 사용)

2. 트랜스포트 방식 비교

• stdio: 로컬 실행 시 사용 (예: uv 명령어) → 광범위한 도구에는 부적합
• SSE: 원격 서버에서 사용 (Express, FastMCP 서버 필요) → Claude Desktop 미지원
• Streamable HTTP:
• 장점: 스케일링, 재연결 지원, Vercel 호환
• 단점: 현재 Client 툴 지원 미흡 (예: --transport http 파라미터 사용 중)

3. 라이브러리 및 코드 예시

• FastMCP:

```python

from fastmcp import MCPApp

app = MCPApp()

@app.tool("math/add")

def add(a: int, b: int) -> int:

return a + b

```

• Streamable HTTP 구현:

```python

from fastapi import FastAPI, Request

from fastapi.responses import StreamingResponse

```

4. 클라이언트 툴 호환성 문제

• 지원되는 클라이언트:
• 로컬 서버: Claude Desktop, Cline, Cursor
• 원격 서버: Cline, Cursor, Claude Code
• 환경 변수 전달 지원: Cursor, Claude Code (Heroku 배포 예시)

5. MCP 프로토콜의 진화

• 문제점:
• LLM의 정보가 지나치게 오래된 경우 (예: ChatGPT)
• 로깅 에러의 불충분성
• 추천: 최신 명세 문서 참조, Streamable HTTP 트랜스포트 채택

결론

• Streamable HTTP 트랜스포트 사용을 권장하고, FastMCP 라이브러리로 서버 구축
• 클라이언트 호환성을 고려해 mcp.json 구성 시 Cursor 또는 Claude Code 사용
• MCP 프로토콜의 변화성을 인지하고, 최신 명세 문서를 항상 참고하세요.