构建 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 服务器，并使用您的客户端尝试一些不同的传输选项，或者提交问题或拉取请求以进行改进或建议新功能。
请在此讨论串中告知我们您的想法、反馈和问题。
