構建 Hugging Face MCP 伺服器
TL;DR： Hugging Face 官方 MCP 伺服器為訪問 Hub 的 AI 助手提供了獨特的自定義選項，並透過一個簡單的 URL 即可訪問數千個 AI 應用程式。我們使用 MCP 的“流式 HTTP”傳輸進行部署，並詳細探討了伺服器開發人員面臨的權衡。
在過去一個月裡，我們學會了許多關於構建一個有用的 MCP 伺服器的知識——我們將在本文中描述我們的旅程。
導言
模型上下文協議 (MCP) 正在實現其承諾，成為連線 AI 助手與外部世界的標準。
在 Hugging Face，透過 MCP 提供對 Hub 的訪問是一個顯而易見的選擇，本文分享了我們開發 hf.co/mcp MCP 伺服器的經驗。
設計選擇
社群使用 Hub 進行研究、開發、內容創作等。我們希望人們能夠根據自己的需求自定義伺服器，並透過 Spaces 輕鬆訪問數千個 AI 應用程式。這意味著透過動態調整使用者的工具來使 MCP 伺服器動態化。
我們還希望透過避免複雜的下載和配置來簡化訪問，因此透過簡單的 URL 進行遠端訪問是必須的。
遠端伺服器
構建遠端 MCP 伺服器時，第一個決定是如何連線客戶端。MCP 提供多種傳輸選項，權衡不同。TL;DR：我們的開原始碼支援所有變體，但為了生產，我們選擇了最現代的一種。本節詳細介紹了不同的選項。
自 2024 年 11 月推出以來，MCP 在 9 個月內經歷了 3 次協議修訂，快速演變。這包括將 SSE 傳輸替換為可流式 HTTP，以及引入和重構授權。
這些快速變化意味著客戶端應用程式對不同 MCP 功能和修訂版本的支援有所不同，這給我們的設計選擇帶來了額外的挑戰。
以下是模型上下文協議和相關 SDK 提供的傳輸選項簡要總結
| 傳輸 | 備註 |
|---|---|
STDIO |
通常在 MCP 伺服器與客戶端在同一臺計算機上執行時使用。如果需要，可以訪問本地資源，例如檔案。 |
帶 SSE 的 HTTP |
用於透過 HTTP 的遠端連線。在 MCP 的 2025-03-26 版本中已棄用，但仍在使用。 |
可流式 HTTP |
一種更靈活的遠端 HTTP 傳輸，比即將推出的 SSE 版本提供更多部署選項 |
STDIO 和 帶 SSE 的 HTTP 預設情況下都是完全雙向的——這意味著客戶端和伺服器保持開放連線並可以隨時相互發送訊息。
SSE 指的是“伺服器傳送事件”——一種 HTTP 伺服器保持開放連線並響應請求傳送事件的方式。
理解可流式 HTTP
MCP 伺服器開發人員在設定可流式 HTTP 傳輸時面臨許多選擇。
有 3 種主要的通訊模式可供選擇
- 直接響應 - 簡單的請求/響應（像標準 REST API）。這非常適合直接、無狀態的操作，例如簡單的搜尋。
- 請求作用域流 - 與單個請求關聯的臨時 SSE 流。這對於在工具呼叫耗時較長（例如影片生成）時傳送進度更新非常有用。此外，伺服器可能需要透過引導請求使用者提供資訊，或執行取樣請求。
- 伺服器推送流 - 支援伺服器發起訊息的長期 SSE 連線。這允許資源、工具和提示列表更改通知或即時取樣和引導。這些連線需要額外的管理，例如保持活動和重新連線時的恢復機制。
當使用官方 SDK 的請求作用域流時，使用
RequestHandlerExtra引數（TypeScript）中提供的sendNotification()和sendRequest()方法，或者設定related_request_id（Python）將訊息傳送到正確的流。
另一個需要考慮的因素是 MCP 伺服器本身是否需要為每個連線維護狀態。這由伺服器在客戶端傳送其初始化請求時決定。
| 無狀態 | 有狀態 | |
|---|---|---|
| 會話 ID | 不需要 | 伺服器響應一個 mcp-session-id |
| 這意味著什麼 | 每個請求都是獨立的 | 伺服器維護客戶端上下文 |
| 擴充套件 | 簡單的水平擴充套件：任何例項都可以處理任何請求 | 需要會話親和性或共享狀態機制 |
| 恢復 | 不需要 | 可能會重播已中斷連線的訊息 |
下表總結了 MCP 功能及其支援的通訊模式
| MCP 功能 | 伺服器推送 | 請求作用域 | 直接響應 |
|---|---|---|---|
| 工具、提示、資源 | Y | Y | Y |
| 取樣/引導 | 伺服器隨時發起 | 與客戶端發起的請求相關 | N |
| 資源訂閱 | Y | N | N |
| 工具/提示列表更改 | Y | N | N |
| 工具進度通知 | - | Y | N |
在使用請求作用域流時，取樣和誘導請求需要一個有狀態連線，以便可以使用 mcp-session-id 進行響應關聯。
Hugging Face MCP 伺服器是開源的——並支援 STDIO、SSE 和流式 HTTP 部署，包括直接響應模式和伺服器推送模式。您可以在使用伺服器推送流時配置保持活動和最後活動超時。還有一個內建的可觀察性儀表板，您可以使用它來了解不同的客戶端如何管理連線，以及如何處理工具列表更改通知。
下圖顯示了我們在“伺服器推送”流式 HTTP 模式下執行的 MCP 伺服器連線儀表板
生產部署
出於以下原因，我們決定在生產環境中以無狀態、直接響應配置啟動我們的 MCP 伺服器：
無狀態 對於匿名使用者，我們提供一套標準的工具來使用 Hub 和一個影像生成器。對於已認證使用者，我們的狀態包括他們選擇的工具和選定的 Gradio 應用程式。我們還確保使用者的 ZeroGPU 配額正確應用於他們的帳戶。這透過我們在請求時查詢提供的 HF_TOKEN 或 OAuth 憑據進行管理。我們現有的工具都不需要我們在請求之間維護任何其他狀態。
您可以透過在 MCP 伺服器 URL 中新增
?login來使用 OAuth 登入，例如https://huggingface.co/mcp?login。一旦claude.ai遠端整合支援最新的 OAuth 規範，我們可能會將其設為預設。
直接響應 提供最低的部署資源開銷——而且我們目前沒有任何工具需要在執行期間進行取樣或引導。
未來支援 在釋出時，“帶 SSE 的 HTTP”傳輸仍然是許多 MCP 客戶端中的遠端預設設定。然而，由於它即將棄用，我們不想投入大量精力進行管理。幸運的是，流行的客戶端（VSCode 和 Cursor）已經開始轉換，並且在釋出一週內，claude.ai 也添加了支援。如果您需要連線 SSE，請隨時在免費 CPU Hugging Face Space 上部署我們的伺服器副本。
工具列表更改通知
未來，我們希望支援當用戶在 Hub 上更新其設定時，即時工具列表更改通知。然而，這帶來了一些實際問題：
首先，使用者傾向於在他們的客戶端中配置他們喜歡的 MCP 伺服器並保持啟用。這意味著只要應用程式開啟，客戶端就會保持連線。傳送通知意味著要維護與當前活躍客戶端一樣多的開放連線——無論活躍使用情況如何——以防使用者更新其工具配置。
其次，大多數 MCP 伺服器和客戶端在一段時間不活動後會斷開連線，並在需要時恢復。這不可避免地意味著即時推送通知會被錯過——因為通知通道將已關閉。實際上，客戶端按需重新整理連線和工具列表要簡單得多。
除非您能合理控制客戶端/伺服器對，否則使用 伺服器推送流 會給公共部署增加很多複雜性，而現有更低資源的解決方案可以重新整理工具列表。
URL 使用者體驗
在釋出前，@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、取消或嘗試列出資源（這並非我們當前宣傳的功能）。
2025 年 7 月的第一週，有驚人的 164 個不同客戶端訪問了我們的伺服器。有趣的是，最受歡迎的工具之一是 mcp-remote。大約一半的客戶端將其作為橋樑，連線到我們的遠端伺服器。
結論
MCP 正在迅速發展，我們對過去幾個月在聊天應用程式、IDE、代理和 MCP 伺服器上取得的成就感到興奮。
我們已經看到了整合 Hugging Face Hub 的強大之處，現在對 Gradio Spaces 的支援使得 LLM 可以輕鬆地與最新的機器學習應用程式進行擴充套件。
以下是一些人們迄今為止使用我們的 MCP 伺服器的精彩示例：
我們希望這篇帖子能為構建遠端 MCP 伺服器所需的決策提供見解，並鼓勵您在您喜歡的 MCP 客戶端中嘗試一些示例。
請檢視我們的開源 MCP 伺服器，並使用您的客戶端嘗試一些不同的傳輸選項，或者提交問題或拉取請求以進行改進或建議新功能。
請在此討論串中告知我們您的想法、反饋和問題。
