I Almost Hand-Rolled JSON-RPC for an MCP Server. Eight Tools Later I'm Glad I Didn't.

개요

MCP 서버 개발 시 JSON-RPC를 직접 구현하는 대신 FastMCP의 데코레이터 API를 사용하는 것이 개발 효율성과 유지보수성 측면에서 훨씬 유리하며, 이는 특히 다수의 API 래퍼를 도구로 노출하는 경우에 해당한다.

주요 내용

* 저수준 MCP 프로토콜 직접 구현의 단점:
* 각 도구마다 이름, 설명, 입력 JSON 스키마를 list_tools 핸들러에 등록해야 함.
* call_tool 디스패처를 작성하여 도구 이름을 매칭하고 인수를 수동으로 언패킹해야 함.
* 응답 값을 MCP가 기대하는 TextContent/ImageContent 래퍼 타입으로 직렬화해야 함.
* 수동으로 작성한 스키마와 디스패처의 인수 파싱 로직을 동기화해야 하는 보일러플레이트 코드가 도구 수에 비례하여 증가함.
* FastMCP 데코레이터 API 사용의 장점:
* Python 함수의 타입 힌트가 JSON 스키마로, 독스트링이 도구 설명으로 자동 변환됨.
* 반환 타입 힌트가 응답 스키마로 활용되어 별도의 스키마 관리가 불필요함.
* 새 도구 추가 시 함수 작성 및 @mcp.tool() 데코레이터 적용만으로 간단하게 완료됨.
* 프로토콜 계층 코드를 직접 건드리지 않아 복잡성이 감소함.
* FastMCP 사용 시 발생 가능한 문제점 및 해결 방안:
* 암시적 반환 타입 변환의 오해: 타입 힌트만으로는 인수의 유효 범위(예: 최대값)를 명확히 제약하지 못할 수 있으므로, 함수 내에서 별도의 유효성 검증 로직을 추가해야 함 (예: min(per_page, 30)).
* 도구 함수 내부 오류의 불투명성: 도구 함수 내에서 발생하는 예외는 에이전트에게 "오류 발생"으로만 전달될 수 있으므로, 중요한 HTTP 상태 코드 등은 명시적으로 포착하여 에이전트가 이해할 수 있는 오류 메시지로 재포매팅해야 함.

시사점

REST API 래퍼를 에이전트 도구로 노출하는 MCP 서버 개발 시, 저수준 프로토콜 구현은 불필요한 복잡성을 야기하며 FastMCP의 데코레이터 API는 스키마 자동 생성 및 동기화 부담을 줄여주는 효율적인 솔루션이다. 다만, 인자 유효성 검증 및 오류 메시지 구체화는 여전히 개발자의 책임 영역으로 남아있다.