Building the Hugging Face MCP Server

Hugging Face has launched an official Model Context Protocol (MCP) server (hf.co/mcp) that enables AI assistants to interact with the Hugging Face Hub and access thousands of AI applications on Spaces. This integration allows users to customize their available tools on the fly and simplifies the connection process by providing a remotely accessible URL.

Technical Design and Customization

The Hugging Face MCP server is designed to be dynamic, allowing users to configure their specific tools via a dedicated MCP Settings Page. This approach ensures that the server can adapt to the specific research, development, or content creation needs of the user. To eliminate the complexity of local downloads and configuration, the server is hosted remotely, making it accessible to AI clients through a simple URL.

Remote Transport Options and Trade-offs

When implementing a remote MCP server, developers must choose between several transport mechanisms. While the Hugging Face open-source implementation supports multiple variants, the production environment utilizes Streamable HTTP.

Transport Comparison

Transport Use Case
STDIO Local servers running on the same machine as the client; allows access to local files.
HTTP with SSE Remote connections over HTTP; deprecated as of the March 26, 2025 version of MCP.
Streamable HTTP Modern, flexible remote HTTP transport with superior deployment options.

Streamable HTTP Communication Patterns

Developers using Streamable HTTP can implement three primary communication patterns:

  1. Direct Response: A standard request/response pattern (similar to REST APIs) ideal for stateless, simple operations like searches.
  2. Request Scoped Streams: Temporary SSE streams tied to a single request. These are used for progress updates (e.g., during video generation) or when the server needs to elicit information from the user.
  3. Server Push Streams: Long-lived SSE connections that allow the server to initiate messages, such as notifications for changes to tool or prompt lists. These require keep-alive and resumption mechanics.

State Management

MCP servers can be configured as either Stateless or Stateful. Stateless servers treat each request independently, enabling simple horizontal scaling. Stateful servers respond with an mcp-session-id and maintain client context, which is necessary for features like Sampling and Elicitation requests within Request Scoped streams.

Production Deployment Strategy

For its production deployment, Hugging Face opted for a Stateless, Direct Response configuration using Streamable HTTP for the following reasons:

  • Statelessness: User state (selected tools, Gradio applications, and ZeroGPU quotas) is managed via HF_TOKEN or OAuth credentials looked up per request, removing the need to maintain session state between requests.
  • Direct Response: This provides the lowest resource overhead and is sufficient because the current toolset does not require Sampling or Elicitation during execution.

Implementation Insights and Client Behavior

Tool List Change Notifications

Hugging Face determined that implementing real-time "Tool List Changed" notifications via Server Push Streams would add excessive complexity. Because many clients disconnect after inactivity or remain connected without active usage, it is more efficient for the client to refresh the connection and tool list as needed rather than maintaining thousands of open connections.

User Experience and Browser Detection

To improve user experience, Hugging Face added a friendly instructions page at hf.co/mcp. However, this led to an issue where VSCode polled the endpoint multiple times per second when it received a web page instead of an HTTP 405 error. The team resolved this by implementing browser detection to ensure only actual browsers receive the HTML page.

Client Traffic Patterns

Analysis of the first week of July 2025 showed 164 different clients accessing the server. The team observed a high ratio of control messages (approximately 100) for every single tool call. A significant portion of clients use mcp-remote as a bridge to connect to the remote server.

Capabilities and Use Cases

By integrating the Hugging Face Hub and Gradio Spaces, LLMs can be extended with the latest machine learning applications. Current user implementations include:

  • Orchestrating video production
  • Image editing
  • Document searching
  • AI application development
  • Adding reasoning capabilities to existing models

Sources