Hugging Face MCP 서버 구축

TL;DR: Hugging Face 공식 MCP 서버는 Hub 를 접근하는 AI 어시스턴트를 위한 고유한 커스터마이징 옵션을 제공하며, 하나의 간단한 URL 을 통해 수천 개의 AI 애플리케이션에 액세스할 수 있습니다. 우리는 배포를 위해 MCP 의 "Streamable HTTP" 전송 방식을 사용했으며, 서버 개발자가 겪어야 하는 트레이드 오프 (Trade-offs) 를 자세히 검토했습니다. 지난 달 동안 유용한 MCP 서버를 구축하는 데 대해 많은 것을 배웠습니다 - 여기에서 우리의 여정을 설명하겠습니다.

모델 컨텍스트 프로토콜 (Model Context Protocol, MCP) 은 AI 어시스턴트를 외부 세계와 연결하는 표준이 될 약속을 실현하고 있습니다.

Hugging Face 에서 Hub 를 MCP 를 통해 액세스 제공하는 것은 명백한 선택이며, 이 글은 hf.co/mcp MCP 서버 개발 경험을 공유합니다.

커뮤니티는 Hub 를 연구, 개발, 콘텐츠 제작 등 다양한 목적으로 사용합니다. 우리는 사람들이 자신의 필요에 따라 서버를 커스터마이징할 수 있도록 하고, Spaces 에 있는 수천 개의 AI 애플리케이션을 쉽게 액세스할 수 있도록 하고자 했습니다. 이는 MCP 서버를 동적으로 만들어 사용자의 도구를 실시간으로 조정하는 것을 의미했습니다.

우리는 또한 복잡한 다운로드 및 구성을 피하여 액세스를 단순화하고 싶었으므로, 간단한 URL 을 통해 원격으로 액세스 가능하게 만드는 것은 필수였습니다.

원격 MCP 서버를 구축할 때 첫 번째 결정은 클라이언트가 어떻게 연결될 것인지 결정하는 것입니다. MCP 는 다양한 트레이드 오프를 가진 여러 전송 옵션을 제공합니다. TL;DR: 우리의 오픈 소스 코드는 모든 변형을 지원하지만, 프로덕션에서는 가장 현대적인 것을 선택했습니다. 이 섹션은 다른 옵션들을 자세히 검토합니다.

2024 년 11 월 출시 이후 MCP 는 9 개월 동안 3 번의 프로토콜 수정을 거치며 급격한 진화를 겪었습니다. 이는 SSE 전송을 Streamable HTTP 로 대체하고, 인증 (Authorization) 의 도입 및 재설계를 포함했습니다.

이러한 급격한 변화는 클라이언트 애플리케이션에서 다양한 MCP 기능과 수정을 지원한다는 것을 의미하며, 우리의 설계 결정에 추가적인 도전을 제공합니다.

모델 컨텍스트 프로토콜 (MCP) 과 관련 SDK 가 제공하는 전송 옵션의 간략한 요약입니다:

Transport	Notes
STDIO
Typically used when the MCP Server is running on the same computer as the Client. Able to access local resources such as files if needed.
HTTP with SSE
Used for remote connections over HTTP. Deprecated in the 2025-03-26 version of MCP but still in use.
Streamable HTTP
A more flexible remote HTTP transport that provides more options for deployment than the outgoing SSE version

두 가지 STDIO 와 HTTP with SSE 는 기본적으로 완전히 양방향 (bi-directional) 입니다 - 즉, 클라이언트와 서버가 열린 연결을 유지하며 언제든지 서로 메시지를 보낼 수 있습니다.

SSE 는 "Server Sent Events" 를 의미합니다 - HTTP 서버가 열린 연결을 유지하고 요청에 응답하여 이벤트를 전송하는 방법입니다.

MCP 서버 개발자는 Streamable HTTP 전송 방식을 설정할 때 많은 선택지를 마주합니다.

선택해야 할 3 가지 주요 통신 패턴이 있습니다:

Direct Response- 단순 요청/응답 (표준 REST API와 유사). 이는 간단한 검색과 같은 무상태 (stateless) 연동에 이상적입니다.Request Scoped Streams- 단일 요청과 연결된 임시 SSE 스트림. 도구 호출이 오래 걸리는 경우 (예: 비디오 생성) 진행 업데이트를 전송하는 데 유용합니다. 또한 서버는 Elicitation 으로 사용자 정보 요청하거나 Sampling 요청을 수행할 수도 있습니다.Server Push Streams- 서버가 메시지를 시작할 수 있는 장기적인 SSE 연결. 이는 리소스, 도구 및 프롬프트 목록 변경 알림 또는 임의의 Sampling 과 Elicitation 을 가능하게 합니다. 이 연결들은 재연결 시 keep-alive 와 재개 메커니즘과 같은 추가 관리가 필요합니다.

공식 SDK 를 사용할 때 Request Scoped Streams 를 사용하려면 RequestHandlerExtra (TypeScript) 의 sendNotification() 및 sendRequest() 방법을 사용하거나 (Python), related_request_id 를 설정하여 올바른 스트림으로 메시지를 전송합니다.

추가적으로 고려해야 할 요소는 MCP 서버가 각 연결마다 상태를 유지할 필요가 있는지 여부입니다. 이는 클라이언트가 Initialize 요청을 보낼 때 서버가 결정합니다:

Stateless	Stateful
Session IDs	필요 없음
What it means	각 요청은 독립적임
Scaling	단순 수평 확장: 모든 인스턴스가 모든 요청을 처리할 수 있음
Resumption	필요 없음

아래 표는 MCP 기능과 지원되는 통신 패턴을 요약합니다:

| MCP Feature | Server Push | Request Scoped | Direct Response |
|---|---|---|
| Tools, Prompts, Resources | Y | Y | Y |
| ... |

Request Scoped 스트림을 사용할 때 Sampling 과 Elicitation 요청은 mcp-session-id 를 응답 연동에 사용할 수 있도록 Stateful 연결이 필요합니다.

Hugging Face MCP 서버는 오픈 소스이며 Direct Response 와 Server Push 모드 모두에서 STDIO, SSE 및 Streamable HTTP 배포를 지원합니다. Server Push Streams 을 사용할 때 keep-alive 와 마지막 활동 타임아웃을 구성할 수 있습니다. 또한 다른 클라이언트가 연결을 관리하고 도구 목록 변경 알림을 처리하는 방식을 이해하는 데 사용할 수 있는 내장 관측성 대시보드도 있습니다.

다음 그림은 "Server Push" Streamable HTTP 모드에서 실행 중인 MCP 서버 연결 대시보드를 보여줍니다:

대량 생산용 (production) 에서는 Stateless, Direct Response 구성으로 Streamable HTTP 를 사용하여 MCP 서버를 출시했습니다. 이유는 다음과 같습니다:

Stateless 익명 사용자에게는 Hub 를 사용하는 데 사용할 표준 도구 세트와 이미지 생성기를 제공합니다. 인증된 사용자에 대해서는 선택된 도구 및 Gradio 애플리케이션이 상태 (state) 로 구성됩니다. 또한 사용자의 ZeroGPU 쿼타가 계정에 올바르게 적용되도록 보장합니다. 이는 요청에서 조회하는 제공된 HF_TOKEN 또는 OAuth 자격 증명로 관리됩니다. 기존 도구의 어느 것도 요청 간에 다른 상태를 유지해야 합니다.

OAuth 로진 (login) 을 사용하려면 MCP 서버 URL 에 ?login 을 추가할 수 있습니다. 예: https://huggingface.co/mcp?login. claude.ai 원격 통합이 최신 OAuth 스펙을 지원하면 이것이 기본값으로 설정될 수 있습니다.

Direct Response 는 최소한의 배포 자원 오버헤드를 제공하며, 현재 실행 중 Sampling 또는 Elicitation 을 필요로 하는 도구는 없습니다.

Future Support 출시 당시, 많은 MCP 클라이언트에서 "HTTP with SSE" 전송 방식이 여전히 원격 기본값이었습니다. 그러나 곧 폐기될 예정이기 때문에 이를 관리하는 데 과도하게 투자하고 싶지 않았습니다. 다행히 인기 있는 클라이언트들 (VSCode 와 Cursor) 은 이미 전환을 시작했고, 출시 후 1 주 안에 claude.ai 또한 지원 추가했습니다. SSE 를 연결해야 하는 경우, 무료 CPU Hugging Face Space 에 저희 서버의 복제본을 배포해 주세요.

미래에는 Hub 에서 사용자가 설정을 업데이트할 때 실시간 Tool List Changed 알림을 지원하고 싶습니다. 그러나 이는 몇 가지 실용적인 문제를 제기합니다:

첫째, 사용자는 일반적으로 선호하는 MCP 서버를 클라이언트에 구성하여 활성화 상태로 두는 경향이 있습니다. 이는 애플리케이션이 열려 있을 때 클라이언트가 연결 상태를 유지함을 의미합니다. 알림을 전송하려면 현재 활성 클라이언트 수와 무관하게 사용자가 도구 구성을 업데이트할 경우에도 많은 개수의 열린 연결을 유지해야 합니다.

둘째, 대부분의 MCP 서버와 클라이언트는 불활성 기간 후 연결을 끊고 필요시 재연결합니다. 이는 즉각적인 푸시 알림이 누락됨을 의미합니다 - 알림 채널이 닫혀 있기 때문입니다. 실제로는 클라이언트가 필요할 때마다 연결과 Tool List 를 새로 고치는 것이 훨씬 간단합니다.

클라이언트/서버 쌍에 대한 합리적인 통제 권한이 없는 경우, Server Push Streams 사용은 더 낮은 리소스 솔루션이 존재하는 Tool List 새로 고침을 위해 많은 복잡성을 추가합니다.

출시 직전, @julien-c 는 hf.co/mcp 를 방문하는 사용자에게 친절한 지침을 포함하도록 PR 을 제출했습니다. 이는 사용자 경험을 크게 개선 - 기본적으로는 불친절인 JSON 조각이 반환됩니다.

초기에는 이것이 엄청난 양의 트래픽을 생성한다는 것을 발견했습니다. 조사 후 VSCode 가 웹 페이지를 반환할 때 HTTP 405 오류 대신 여러 초마다 엔드포인트를 폴링한다고 알게 되었습니다.

@coyotte508 이 제안한 해결책은 브라우저 를 올바르게 감지하고 해당 상황에서만 페이지를 반환하는 것이었습니다. 또한 VSCode 팀에 감사드립니다 - 그들은 이를 빠르게 수정했습니다.

특히 명시되지 않았지만, 이러한 방식으로 페이지를 반환하는 것은 MCP 규격 내에서 도수적으로 허용되는 것으로 보입니다.

MCP 프로토콜은 초기화 동안 여러 요청을 전송합니다. 일반적인 연결 순서는: Initialize, Notifications/Initialize, tools/list 및 prompts/list 입니다.

MCP 클라이언트가 열려 있을 때 연결하고 재연결하며 사용자가 주기적으로 호출한다는 사실로 인해, 우리는 약 100 개의 MCP 제어 메시지에 대한 1 개 Tool Call 의 비율을 발견했습니다.

일부 클라이언트는 Stateless, Direct Response 구성에 맞지 않는 요청도 전송합니다 - 예를 들어 Pings, Cancellations 또는 리소스 목록화 시도 (현재 광고하지 않는 기능입니다).

2025 년 7 월 첫 주에는 놀라운 164 개의 다른 클라이언트가 저희 서버에 액세스했습니다. 흥미롭게도, 가장 인기 있는 도구 중 하나는 mcp-remote 입니다. 모든 클라이언트의 약 절반이 이를 원격 서버에 연결하는 브리지로 사용합니다.

MCP 는 빠르게 진화하고 있으며, 지난 몇 달간 채팅 애플리케이션, IDE, 에이전트 및 MCP 서버에서 이미 달성된 것에 대해 매우 기대합니다.

Hugging Face Hub 를 통합하는 것이 얼마나 강력한지 이미 확인할 수 있습니다. Gradio Spaces 지원이 이제 LLM 을 최신 머신러닝 애플리케이션과 쉽게 확장할 수 있게 합니다.

원문(rawText)을 읽고 한국어로 번역합니다.

규칙:

• 원문에 없는 내용 추가 금지
• 외국어 원문은 충실하게 한국어로 번역 (정보량 100% 보존, 요약/압축/확장 금지)
• 전문용어는 영문 병기 (예: "강화학습 (RL)")
• 숫자·고유명사는 원문과 일치
• 원문 구조(서론/본론/결론) 그대로 유지
• 원문이 이미 한국어면 그대로 사용 (다듬기 금지)

JSON 형식으로만 응답:
{"title": "한국어 제목", "content": "한국어 번역 본문"}