Hugging Face 复盘 hf.co/mcp MCP Server 的构建与部署选型

TL;DR: The Hugging Face Official MCP Server offers unique customization options for AI Assistants accessing the Hub, along with access to thousands of AI applications through one simple URL. We used MCPs "Streamable HTTP" transport for deployment, and examine in detail the trade-offs that Server Developers have.
在过去一个月里，我们学到了许多关于构建一个有用的 MCP 服务器的经验——我们将在本文中描述我们的历程。

引言

Model Context Protocol（MCP）正在兑现其作为连接 AI 助手与外部世界的标准的承诺。

在 Hugging Face，通过 MCP 提供对 Hub 的访问是显而易见的选择，本文分享了我们在开发 hf.co/mcp MCP Server 过程中的经验。

设计选择

社区使用 Hub 进行研究、开发、内容创作等。我们希望让人们能够根据自己的需求定制服务器，同时轻松访问 Spaces 上数千个可用的 AI 应用。这意味着要让 MCP Server 具备动态性，能够即时调整用户的工具。

The Hugging Face MCP Settings Page — Hugging Face MCP 设置页面，用户可以在其中配置自己的工具。

我们还希望通过避免复杂的下载和配置来简化访问，因此通过一个简单的 URL 实现远程访问是必须的。

远程服务器

在构建远程 MCP Server 时，首先要决定的是客户端如何连接到它。MCP 提供了多种传输选项，各有不同的权衡。TL;DR：我们的开源代码支持所有变体，但在生产环境中我们选择了最现代的一种。本节将详细介绍各种选项。

自 2024 年 11 月推出以来，MCP 经历了快速演进，9 个月内进行了 3 次协议修订。这期间 SSE Transport 被 Streamable HTTP 取代，授权机制也被引入并重新设计。

这些快速变化意味着客户端应用对不同 MCP 功能和修订版本的支持参差不齐，为我们的设计选择带来了额外的挑战。

以下是 Model Context Protocol 及相关 SDK 提供的传输选项的简要总结：

传输方式	说明
`STDIO`	通常用于 MCP Server 与 Client 运行在同一台计算机上的情况。如有需要，可以访问文件等本地资源。
`HTTP with SSE`	用于通过 HTTP 进行远程连接。在 MCP 的 2025-03-26 版本中已弃用，但仍在使用中。
`Streamable HTTP`	一种更灵活的远程 HTTP 传输方式，相比即将淘汰的 SSE 版本提供了更多的部署选项

STDIO 和 HTTP with SSE 默认都是完全双向的——这意味着 Client 和 Server 保持开放连接，可以随时互相发送消息。

SSE 指的是 "Server Sent Events"——一种 HTTP 服务器保持开放连接并响应请求发送事件的方式。

理解 Streamable HTTP

MCP Server 开发者在设置 Streamable HTTP 传输时面临许多选择。

有 3 种主要的通信模式可供选择：

直接响应——简单的请求/响应（类似标准 REST API）。非常适合简单搜索等直接、无状态的操作。
请求作用域流——与单个请求关联的临时 SSE 流。如果工具调用耗时较长（例如视频生成），这对于发送进度更新非常有用。此外，服务器可能需要通过 Elicitation 向用户请求信息，或进行 Sampling 请求。
服务器推送流 - 支持服务器主动发起消息的长连接 SSE 连接。这可以实现 Resource、Tool 和 Prompt 列表变更通知，或临时的 Sampling 和 Elicitations。这些连接需要额外的管理，例如 keep-alive 以及重新连接时的恢复机制。

在官方 SDK 中使用 Request Scoped Streams 时，请使用 RequestHandlerExtra 参数中提供的 sendNotification() 和 sendRequest() 方法（TypeScript），或设置 related_request_id（Python），以便将消息发送到正确的流。

另一个需要考虑的因素是 MCP Server 本身是否需要为每个连接维护状态。这由 Server 在 Client 发送 Initialize 请求时决定：

	无状态	有状态
Session ID	不需要	Server 以 `mcp-session-id` 响应
含义	每个请求相互独立	Server 维护客户端上下文
扩展性	简单的水平扩展：任何实例都可以处理任何请求	需要会话亲和性或共享状态机制
恢复	不需要	可能会为断开的连接重放消息

下表总结了 MCP Features 及其支持的通信模式：

MCP Feature	Server Push	Request Scoped	Direct Response
Tools、Prompts、Resources	Y	Y	Y
Sampling/Elicitation	Server 随时发起	与 Client 发起的请求相关	N
Resource Subscriptions	Y	N	N
Tool/Prompt List Changes	Y	N	N
Tool Progress Notification	-	Y	N

使用 Request Scoped streams 时，Sampling 和 Elicitation 请求需要 Stateful 连接，以便可以使用 mcp-session-id 进行响应关联。

Hugging Face MCP Server 是开源的——并且支持 STDIO、SSE 和 Streamable HTTP 部署，涵盖 Direct Response 和 Server Push 模式。使用 Server Push Streams 时，你可以配置 keep-alive 和最后活动超时。还有一个内置的可观测性仪表盘，你可以用它来了解不同 Client 如何管理连接，以及处理 Tool List 变更通知。

下图展示了我们的 MCP Server 连接仪表盘在“Server Push”Streamable HTTP 模式下运行的情况：

The Hugging Face MCP Server Connection Dashboard — Hugging Face MCP Server 连接仪表盘。

生产部署

对于生产环境，我们决定以无状态、Direct Response 配置的 Streamable HTTP 启动我们的 MCP Server，原因如下：

无状态 对于匿名用户，我们提供一组用于 Hub 的标准 Tools 以及一个 Image Generator。对于已认证用户，我们的状态包括他们选择的工具和选定的 Gradio 应用。我们还确保用户的 ZeroGPU 配额正确应用于其账户。这通过提供的 HF_TOKEN 或我们在请求时查找的 OAuth 凭据进行管理。我们现有的工具都不要求我们在请求之间维护任何其他状态。

你可以通过在 MCP Server URL 中添加 ?login 来使用 OAuth 登录——例如 https://huggingface.co/mcp?login。一旦 claude.ai 远程集成支持最新的 OAuth 规范，我们可能会将其设为默认方式。

Direct Response 提供最低的部署资源开销——而且我们目前没有任何 Tools 需要在执行期间进行 Sampling 或 Elicitation。

未来支持 在发布时，“HTTP with SSE”传输在许多 MCP 客户端中仍是远程默认选项。然而，由于它即将被弃用，我们不想在管理上投入过多。幸运的是，流行客户端已经开始切换（VSCode 和 Cursor），并且在发布后一周内 claude.ai 也添加了支持。如果您需要连接 SSE，请随时在 FreeCPU 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 的支持现在使得 LLMs 能够轻松地通过最新的机器学习应用进行扩展。

以下是一些人们迄今为止使用我们的 MCP Server 所做的一些很好的例子：

我们希望这篇文章能为构建远程 MCP 服务器时需要做出的决策提供一些见解，并鼓励你在你最喜欢的 MCP 客户端中尝试一些示例。

看看我们的开源 MCP 服务器，并在你的客户端中尝试一些不同的传输选项，或者提交 Issue 或 Pull Request 来改进或建议新功能。

在这个讨论帖中告诉我们你的想法、反馈和问题。