MCP 서버 개발의 실전 교훈
카테고리
프로그래밍/소프트웨어 개발
서브카테고리
개발 툴
대상자
- 개발자 (Python, API, MCP 서버 구축 경험자)
- 난이도: 중급~고급 (구체적인 구현 사례와 API 사용 설명 포함)
핵심 요약
- MCP 서버 구성 요소:
tool,resource,prompt이 핵심이며, 각각 도메인별 액션 수행, 백엔드 쿼리 지원, LLM 질의 템플릿 역할 - Transport 방식 비교:
stdio(로컬 자동화),SSE(고전 방식, 지원 제한),Streamable HTTP(스케일링 및 상태 불변성 지원, 추천) - FastMCP 사용 권장:
MCPApp클래스 기반 구현으로 스트리밍 지원 및 빠른 배포 가능
섹션별 세부 요약
1. MCP 서버 구성 요소
- tool: 사용자 액션 수행을 위한 함수 정의 (예:
@app.tool("math/add")) - resource: 파라미터 기반 데이터 조회 지원 (예:
@mcp.resource("availability://{user_id}/date")) - prompt: LLM에 전달하는 템플릿으로, PyAirbyte에서 소스/대상 커넥터 지정에 활용
2. Transport 방식 선택
- stdio: 로컬 파일 실행을 위한 단순한 방식 (예:
uv명령어 실행) - SSE: 서버 엔드포인트 생성 필요 (POST/GET), Claude Desktop 미지원
- Streamable HTTP: 상태 불변성 및 Vercel 호스팅 지원 (현재
--transport http파라미터로 확장 중)
3. FastMCP 활용 사례
- 구현 예제:
from fastmcp import MCPApp
app = MCPApp()
@app.tool("math/add")
def add(a: int, b: int) -> int:
return a + bjsonrpc 형식으로 응답 처리4. OpenAI 및 Agent SDK 동향
- OpenAI: MCP 서버를 활용한 작업 수행 가능 (현재 구현 복잡)
- Google Agent SDK: 유사한 접근 방식 추구 (모델-서버 상호작용 강조)
5. 클라이언트 도구 차이점
- 로컬 서버 지원: Claude Desktop, Cline, Cursor
- 환경 변수 전달: Cursor, Claude Code 지원 (Heroku 배포 시 OpenAI API 키 입력 필요)
6. MCP 프로토콜의 불확실성
- 변경 빈도: 빠른 변화로 인해 에러 로깅 부족 및 LLM 정보 노후화 문제 발생
- 구현 팁:
mcp.json파일 설정 시 클라이언트 도구 호환성 확인 필수
결론
- Streamable HTTP 방식을 권장하며,
FastMCP라이브러리를 사용하여 빠른 배포와 확장성 달성 - 클라이언트 도구 차이점을 명확히 파악하고, 환경 변수 전달을 위해 Cursor/Claude Code 활용
- MCP 프로토콜의 변화에 유연하게 대응해야 하며,
mcp.json설정 시 호환성 검증이 필수적