构建 Hugging Face MCP 服务器

Hugging Face 已推出官方的模型上下文协议（Model Context Protocol，MCP）服务器（hf.co/mcp），使 AI 助手能够与 Hugging Face Hub 交互并访问 Spaces 上数千个 AI 应用程序。此集成允许用户随时定制可用工具，并通过提供可远程访问的 URL 简化连接过程。

技术设计与定制

Hugging Face MCP 服务器被设计为动态的，允许用户通过专用的 MCP Settings Page 配置其特定工具。此方式确保服务器能够适应用户的特定研究、开发或内容创作需求。为消除本地下载和配置的复杂性，服务器在远程托管，可通过简易的 URL 供 AI 客户端访问。

远程传输选项与权衡

在实现远程 MCP 服务器时，开发者必须在多种传输机制之间进行选择。虽然 Hugging Face 开源实现支持多种变体，但生产环境使用 Streamable HTTP。

传输比较

传输方式 使用场景
STDIO 在与客户端同一机器上运行的本地服务器；允许访问本地文件。
HTTP with SSE 通过 HTTP 的远程连接；自 2025 年 3 月 26 日的 MCP 版本起已弃用。
Streamable HTTP 现代、灵活的远程 HTTP 传输，具备更佳的部署选项。

Streamable HTTP 通信模式

使用 Streamable HTTP 的开发者可以实现三种主要的通信模式：

  1. 直接响应：一种标准的请求/响应模式（类似于 REST API），适用于无状态、简单的操作，如搜索。
  2. 请求范围流：与单个请求绑定的临时 SSE 流。用于进度更新（例如视频生成期间）或服务器需要向用户获取信息时。
  3. 服务器推送流：长连接的 SSE，允许服务器主动发送消息，例如工具或提示列表变更的通知。这需要保持活跃和恢复机制。

状态管理

MCP 服务器可以配置为 无状态 或 有状态。无状态服务器将每个请求视为独立的，从而实现简单的水平扩展。有状态服务器会返回 mcp-session-id 并维护客户端上下文，这对于请求范围流中的采样（Sampling）和信息获取（Elicitation）请求等功能是必需的。

生产部署策略

在生产部署中，Hugging Face 选择了使用 Streamable HTTP 的 无状态、直接响应 配置，原因如下：

  • 无状态：用户状态（已选工具、Gradio 应用和 ZeroGPU 配额）通过每次请求查找的 HF_TOKEN 或 OAuth 凭证进行管理，无需在请求之间维护会话状态。
  • 直接响应：此方式资源开销最低，并且足以满足当前工具集在执行过程中不需要采样或信息获取的需求。

实现洞察与客户端行为

工具列表变更通知

Hugging Face 认为通过服务器推送流实现实时的“工具列表已更改”通知会带来过度的复杂性。由于许多客户端在不活跃后会断开连接，或在未使用时保持连接，客户端在需要时刷新连接和工具列表比维持成千上万的打开连接更高效。

用户体验与浏览器检测

为提升用户体验，Hugging Face 在 hf.co/mcp 添加了友好的说明页面。然而，这导致 VSCode 在收到网页而非 HTTP 405 错误时，每秒多次轮询该端点。团队通过实现浏览器检测来解决此问题，确保只有真实的浏览器会收到 HTML 页面。

客户端流量模式

对 2025 年 7 月第一周的分析显示，有 164 个不同的客户端访问服务器。团队观察到每一次工具调用对应约 100 条控制消息的高比例。大量客户端使用 mcp-remote 作为桥接连接到远程服务器。

能力与使用场景

通过集成 Hugging Face Hub 和 Gradio Spaces，LLM 可以扩展最新的机器学习应用。目前的用户实现包括：

  • 视频制作编排
  • 图像编辑
  • 文档搜索
  • AI 应用开发
  • 为现有模型添加推理能力

Sources