Hugging Face MCP 서버 구축

Hugging Face는 공식 Model Context Protocol (MCP) 서버(hf.co/mcp)를 출시했습니다. 이를 통해 AI 어시스턴트가 Hugging Face Hub와 연동하고 Spaces에 있는 수천 개의 AI 애플리케이션에 접근할 수 있습니다. 이 통합을 통해 사용자는 도구를 실시간으로 맞춤 설정할 수 있으며, 원격으로 접근 가능한 URL을 제공함으로써 연결 과정을 단순화합니다.

기술 설계 및 맞춤 설정

Hugging Face MCP 서버는 동적으로 설계되어 사용자가 전용 MCP Settings Page에서 특정 도구를 구성할 수 있습니다. 이 접근 방식은 서버가 사용자의 연구, 개발 또는 콘텐츠 제작 요구에 맞게 조정될 수 있도록 보장합니다. 로컬 다운로드 및 설정의 복잡성을 없애기 위해 서버는 원격으로 호스팅되며, 간단한 URL을 통해 AI 클라이언트가 접근할 수 있습니다.

원격 전송 옵션 및 트레이드오프

원격 MCP 서버를 구현할 때 개발자는 여러 전송 메커니즘 중에서 선택해야 합니다. Hugging Face 오픈소스 구현은 다양한 변형을 지원하지만, 프로덕션 환경에서는 Streamable HTTP를 사용합니다.

전송 비교

전송 방식 사용 사례
STDIO 클라이언트와 동일 머신에서 실행되는 로컬 서버; 로컬 파일에 접근 가능.
HTTP with SSE HTTP를 통한 원격 연결; 2025년 3월 26일 버전의 MCP에서 폐기됨.
Streamable HTTP 현대적이고 유연한 원격 HTTP 전송으로, 뛰어난 배포 옵션 제공.

Streamable HTTP 통신 패턴

Streamable HTTP를 사용하는 개발자는 세 가지 주요 통신 패턴을 구현할 수 있습니다:

  1. Direct Response: 표준 요청/응답 패턴(REST API와 유사)으로, 검색과 같은 무상태, 간단한 작업에 이상적입니다.
  2. Request Scoped Streams: 단일 요청에 연결된 임시 SSE 스트림. 진행 상황 업데이트(예: 비디오 생성 중) 또는 서버가 사용자에게 정보를 요청해야 할 때 사용됩니다.
  3. Server Push Streams: 서버가 메시지를 시작할 수 있는 장기 SSE 연결로, 도구 또는 프롬프트 목록 변경에 대한 알림 등에 사용됩니다. 이 경우 keep-alive 및 재개 메커니즘이 필요합니다.

상태 관리

MCP 서버는 Stateless 또는 Stateful로 구성될 수 있습니다. Stateless 서버는 각 요청을 독립적으로 처리하여 수평 확장이 간단합니다. Stateful 서버는 mcp-session-id를 반환하고 클라이언트 컨텍스트를 유지하며, 이는 Request Scoped 스트림 내에서 Sampling 및 Elicitation 요청과 같은 기능에 필요합니다.

프로덕션 배포 전략

프로덕션 배포를 위해 Hugging Face는 Streamable HTTP를 사용한 Stateless, Direct Response 구성을 선택했습니다:

  • Stateless: 사용자 상태(선택된 도구, Gradio 애플리케이션, ZeroGPU 할당량)는 요청당 조회되는 HF_TOKEN 또는 OAuth 자격 증명을 통해 관리되어, 요청 간 세션 상태를 유지할 필요가 없습니다.
  • Direct Response: 가장 낮은 리소스 오버헤드를 제공하며, 현재 도구 세트가 실행 중에 Sampling이나 Elicitation을 필요로 하지 않기 때문에 충분합니다.

구현 인사이트 및 클라이언트 동작

도구 목록 변경 알림

Hugging Face는 Server Push Streams를 통한 실시간 "Tool List Changed" 알림 구현이 과도한 복잡성을 초래한다는 결론에 도달했습니다. 많은 클라이언트가 비활성 상태 후 연결을 끊거나 사용 없이 연결을 유지하기 때문에, 수천 개의 열린 연결을 유지하기보다 필요에 따라 클라이언트가 연결 및 도구 목록을 새로 고치는 것이 효율적입니다.

사용자 경험 및 브라우저 감지

사용자 경험을 개선하기 위해 Hugging Face는 hf.co/mcp에 친절한 안내 페이지를 추가했습니다. 그러나 이로 인해 VSCode가 HTTP 405 오류 대신 웹 페이지를 받았을 때 초당 여러 번 엔드포인트를 폴링하는 문제가 발생했습니다. 팀은 실제 브라우저에만 HTML 페이지를 제공하도록 브라우저 감지를 구현해 문제를 해결했습니다.

클라이언트 트래픽 패턴

2025년 7월 첫 주 분석 결과, 164개의 서로 다른 클라이언트가 서버에 접근했습니다. 팀은 도구 호출당 약 100개의 제어 메시지가 발생하는 높은 비율을 관찰했습니다. 많은 클라이언트가 mcp-remote를 브리지로 사용해 원격 서버에 연결합니다.

기능 및 활용 사례

Hugging Face Hub와 Gradio Spaces를 통합함으로써 LLM은 최신 머신러닝 애플리케이션으로 확장될 수 있습니다. 현재 사용자 구현 사례는 다음과 같습니다:

  • 비디오 제작 오케스트레이션
  • 이미지 편집
  • 문서 검색
  • AI 애플리케이션 개발
  • 기존 모델에 추론 기능 추가

Sources