Hugging Face 分享 MCP Server 建置經驗與部署取捨
Building the Hugging Face MCP Server
Hugging Face 分享其官方 MCP Server 的建置經驗,説明 AI 助手如何透過 hf.co/mcp 存取 Hub 及 Spaces 上的 AI 應用。
文章拆解遠端 MCP Server 在傳輸模式、連線狀態與資源開銷上的取捨,並以 Hugging Face 的部署配置呈現決策脈絡。
TL;DR: The Hugging Face Official MCP Server 為連接 Hub 的 AI 助理提供獨特的自訂選項,並提供透過一個簡單網址存取數以千計 AI 應用程式的途徑。我們在部署時採用 MCP 的「Streamable HTTP」傳輸方式,並詳細探討伺服器開發者所面對的取捨。過去一個月,我們在打造實用的 MCP 伺服器方面學到不少;本文會分享我們的歷程。
引言
模型上下文協定(MCP)正逐步實現其承諾,成為連接 AI 助理與外界的標準。
對 Hugging Face 而言,透過 MCP 開放 Hub 的存取能力是順理成章的選擇;本文會分享我們開發 hf.co/mcp MCP 伺服器的經驗。
設計取捨
社羣使用 Hub 進行研究、開發、內容創作等工作。我們希望使用者既可按自己的需要自訂伺服器,也能輕鬆使用 Spaces 上數以千計的 AI 應用程式。因此,MCP 伺服器必須能動態調整使用者可用的工具。
我們亦希望簡化存取方式,免卻繁複的下載和設定,因此必須提供簡單網址,讓使用者可遙距連線。
遠端伺服器
建置遠端 MCP 伺服器時,首先要決定用戶端如何連線。MCP 提供多種傳輸選項,各有不同取捨。簡而言之:我們的開源程式碼支援所有方案,但正式環境採用了最新的一種。本節會詳細介紹各種選項。
MCP 自 November 2024 推出以來快速演進,在 9 個月內修訂了 3 次協定。過程中,SSE 傳輸方式被 Streamable HTTP 取代,授權機制亦經歷引入和重新設計。
由於變化迅速,不同 MCP 功能和協定版本在各用戶端應用程式上的支援程度不一,為設計帶來額外挑戰。
以下簡介模型上下文協定及相關 SDK 提供的傳輸選項:
| 傳輸方式 | 備註 |
|---|---|
STDIO |
通常用於 MCP 伺服器和用戶端在同一部電腦上執行的情況;如有需要,也可存取本機檔案等資源。 |
HTTP with SSE |
用於透過 HTTP 遙距連線。此方式已在 MCP 的 2025-03-26 版本中棄用,但仍有人使用。 |
Streamable HTTP |
較靈活的遠端 HTTP 傳輸方式,提供比舊版 SSE 更多部署選項。 |
STDIO 和 HTTP with SSE 預設均為全雙向傳輸,也就是用戶端和伺服器會維持連線,並可隨時互相傳送訊息。
SSE 是「伺服器傳送事件」(Server Sent Events)的簡稱,指 HTTP 伺服器維持連線,並按請求傳送事件的方式。
瞭解 Streamable HTTP
設定 Streamable HTTP 傳輸時,MCP 伺服器開發者需要作出多項選擇。
主要有 3 種通訊模式可供選擇:
- 直接回應 - 簡單的請求/回應模式(類似標準 REST API),最適合簡單搜尋等直接而無狀態的操作。
- 請求範圍串流 - 與單一請求關聯的臨時 SSE 串流。若工具呼叫需時較長(例如影片生成),可用來傳送進度更新。此外,伺服器亦可透過徵詢(Elicitation)向使用者索取資料,或進行 Sampling 請求。
- 伺服器推送串流 - 長連線 SSE 串流,支援伺服器主動發送訊息,可用於資源、工具及提示清單變更通知,或即時發起 Sampling 和徵詢。這些連線需要額外管理,例如保持連線,以及斷線後重新連線時的恢復機制。
使用官方 SDK 配合請求範圍串流時,請使用
sendNotification()和sendRequest()方法;這些方法由RequestHandlerExtra參數提供(TypeScript)。Python 則設定related_request_id,將訊息送到正確的串流。
另一個考慮因素是 MCP 伺服器本身是否需要為每條連線保留狀態。用戶端傳送 Initialize 請求時,伺服器會決定採用哪種模式:
| 無狀態 | 有狀態 | |
|---|---|---|
| 工作階段 ID | 不需要 | 伺服器會回傳 mcp-session-id |
| 含義 | 每個請求均獨立處理 | 伺服器會保留用戶端上下文 |
| 擴展能力 | 水平擴展簡單:任何執行個體都可處理任何請求 | 需要工作階段黏著,或共享狀態機制 |
| 連線恢復 | 不需要 | 可在連線中斷後重播訊息 |
下表概述各項 MCP 功能支援的通訊模式:
| MCP 功能 | 伺服器推送 | 請求範圍 | 直接回應 |
|---|---|---|---|
| 工具、提示、資源 | Y | Y | Y |
| Sampling/徵詢 | 伺服器可隨時主動發起 | 與用戶端發起的請求相關 | N |
| 資源訂閲 | Y | N | N |
| 工具/提示清單變更 | Y | N | N |
| 工具進度通知 | - | Y | N |
在請求範圍串流中,Sampling 和徵詢請求需要有狀態連線,才能透過 mcp-session-id 將回覆配對到相應請求。
Hugging Face MCP 伺服器是開源專案,支援以 STDIO、SSE 及 Streamable HTTP 部署,並提供直接回應和伺服器推送兩種模式。使用伺服器推送串流時,可設定保持連線和最後活動時間逾時。它亦內置可觀測性儀錶板,方便了解不同用戶端如何管理連線及處理工具清單變更通知。
以下圖片展示我們的 MCP 伺服器連線儀錶板在 Streamable HTTP「伺服器推送」模式下的畫面:
正式環境部署
正式環境中,我們決定以 Streamable HTTP 的無狀態直接回應模式推出 MCP 伺服器,原因如下:
無狀態 對匿名使用者,我們提供一套標準工具,用來使用 Hub 和圖像生成器。對已驗證使用者而言,我們只需保留他們選取的工具和所選的 Gradio 應用程式。我們亦會確保其 ZeroGPU 配額正確套用至帳戶。這些資料透過提供的 HF_TOKEN 或 OAuth 憑證管理,並會按請求查詢。我們現有的工具都不需要在請求之間保留其他狀態。
在 MCP 伺服器網址後加上
?login,即可使用 OAuth 登入,例如https://huggingface.co/mcp?login。待claude.ai遠端整合支援最新 OAuth 規格後,我們或會將此設為預設方式。
直接回應 可將部署所需資源降至最低,而且目前沒有任何工具需要在執行期間使用 Sampling 或徵詢。
未來支援 推出時,許多 MCP 用戶端的遠端預設傳輸方式仍是「HTTP with SSE」。不過,考慮到它即將被棄用,我們不希望投入大量資源維護。幸好,VSCode 和 Cursor 等熱門用戶端已開始轉用新方式,而在推出後一週內,claude.ai 亦加入支援。如需透過 SSE 連線,可在免費 CPU Hugging Face Space部署我們伺服器的副本。
工具清單變更通知
未來,我們希望支援即時的工具清單變更通知,讓使用者更新 Hub 設定時能即時收到通知。不過,這會帶來幾個實際問題:
首先,使用者通常會在用戶端設定好自己喜歡的 MCP 伺服器,並一直保持啟用。只要應用程式開着,用戶端就會維持連線。若要發送通知,就得為目前所有活躍用戶端維持同等數目的開放連線,即使它們沒有正在使用;而這一切只是為了應付使用者可能更新工具設定的情況。
其次,大多數 MCP 伺服器和用戶端會在閒置一段時間後斷線,需要時才重新連線。這代表即時推送通知難免會漏掉,因為當時通知通道可能已關閉。實際上,讓用戶端按需要重新整理連線和工具清單簡單得多。
除非你能合理控制用戶端與伺服器兩端,否則在公開部署中採用伺服器推送串流會大幅增加複雜度,而重新整理工具清單其實有耗用資源較少的方案。
網址使用體驗
推出前不久,@julien-c提交了一個 PR,為瀏覽 hf.co/mcp 的使用者加入淺白易懂的指引,大幅改善使用體驗;否則預設只會顯示一段不友善的 JSON。
起初,我們發現這造成大量流量。調查後才發現,只要伺服器回傳網頁而非 HTTP 405 錯誤,VSCode 就會每秒多次輪詢該端點!
@coyotte508建議的修正方法,是妥善識別瀏覽器,只在這種情況下回傳網頁。也感謝 VSCode 團隊迅速修正問題。
雖然 MCP 規格沒有明文説明,但以這種方式回傳網頁,看來是可接受的。
MCP 用戶端行為
MCP 協定會在初始化期間發送多個請求。典型的連線順序是:Initialize、Notifications/Initialize、tools/list,然後是 prompts/list。
MCP 用戶端會在應用程式開啟期間連線及重新連線,加上使用者會定期呼叫工具,我們發現每次工具呼叫約對應 100 個 MCP 控制訊息。
有些用戶端也會發送一些不適用於我們無狀態直接回應設定的請求,例如 Ping、取消操作,或列出資源的請求(我們目前並未宣告支援這項能力)。
July 2025 的第一週,竟有 164 個不同用戶端連線至我們的伺服器。有趣的是,最受歡迎的工具之一是 mcp-remote。約有一半用戶端透過它連接我們的遠端伺服器。
總結
MCP 正快速演進;過去幾個月,聊天應用程式、IDE、代理程式和 MCP 伺服器均已有令人振奮的成果,我們對此感到期待。
我們已看到整合 Hugging Face Hub 帶來的強大效益;現在支援 Gradio Spaces,更讓 LLM 能輕鬆延伸至最新的機器學習應用程式。
以下是目前大家運用我們 MCP 伺服器所做的一些精彩示例:
希望本文能讓你瞭解建置遠端 MCP 伺服器時需要作出的決定,並鼓勵你在常用的 MCP 用戶端試試其中一些示例。
歡迎看看我們的開源 MCP 伺服器,在你的用戶端試用不同傳輸選項;亦可提交 Issue 或 Pull Request,協助改良或建議新功能。
歡迎在這個討論串分享想法、意見和問題。
來源:Hugging Face Blog · huggingface.co