MCP 클라이언트 구현: JSON 복사-붙이기보다 더 나은 방법
카테고리
프로그래밍/소프트웨어 개발
서브카테고리
웹 개발
대상자
MCP 프로토콜을 사용하는 클라이언트/서버 개발자, HTTP 및 이벤트 기반 통신을 다루는 개발자
핵심 요약
- MCP 클라이언트는 STDIO 프로토콜 대신 HTTP+SSE를 사용할 것을 강력히 권장 (STDIO는 파일 시스템 기반으로 서버-클라이언트 연결이 복잡함)
- HTTP MCP 서버는 Server-Sent Events(SSE) 프로토콜을 사용 (단방향 통신,
data:
접두사 +\n\n
구분자 필요) - 클라이언트 코드 예시:
MCPClient
클래스로initialize()
,call_tool()
메서드 구현, JSON-RPC 기반 통신 처리
섹션별 세부 요약
1. MCP 프로토콜 개요
- MCP는 AI 인플루언서가 주장하는 것보다 복잡한 프로토콜로,
STDIO
와HTTP
두 가지 서버 유형 지원 - STDIO는 파일 시스템 기반 통신 (서버 실행 시 클라이언트가 직접 파일 경로를 설정해야 함)
- HTTP+SSE는 인터넷 기반 원격 연결 지원 (사용자가 LLM을 대신하여 행동 수행 가능)
2. STDIO 프로토콜의 문제점
- STDIO는 파일 시스템을 통한 서버 실행 (클라이언트가 서버를 직접 실행해야 함)
- STDIO 서버는 인터넷 노출 불가능 (동일 머신 내부 통신 제한)
- STDIO는 미래 기술이 아니며, 유지보수 어려움 (예:
mcp.json
에서 서버 경로 설정 필요)
3. HTTP+SSE 프로토콜 구현
- SSE는 서버가 클라이언트로 데이터를 비동기적으로 전송 (예:
data: message\n\n
형식) - SSE는 JSON-RPC 요청/응답을 처리 (
POST
요청으로 툴 목록 조회,SSE
로 응답 수신) - SSE 호환성 문제: 연속
\n
이 포함된 응답은 클라이언트가 파싱 실패할 수 있음
4. MCP 클라이언트 구현 예시 (Python)
- 클라이언트 클래스 정의:
MCPClient
로initialize()
,call_tool()
메서드 구현 - JSON-RPC 요청 처리:
uuid
생성,Content-Type: application/json
설정,Mcp-Session-Id
헤더 사용 - SSE 응답 처리:
data:
접두사 제거 후 JSON 파싱,result
또는error
필드 추출
5. 서버 구축 예시 (Node.js)
- mcp-framework 사용:
npm i -g mcp-framework
로 설치,mcp create
명령어로 서버 생성 - 도구 정의:
WeatherTool
클래스로execute()
메서드 구현 (예:city
입력값으로 날씨 정보 반환) - 서버 실행:
npm start
로 실행 후 클라이언트 연결 테스트 가능
결론
- STDIO 프로토콜은 피해야 함 (HTTP+SSE 사용 권장), SSE는
data:
+\n\n
형식을 꼭 준수해야 함 - 클라이언트 구현 시 JSON-RPC와 SSE 처리 로직을 반드시 포함 (예:
MCPClient
클래스의_handle_sse_response()
메서드) - MCP 서버는
mcp-framework
를 사용해 툴을 정의하고npm start
로 실행 (클라이언트 연결 테스트 가능)