Xây dựng Máy chủ Hugging Face MCP

Bài viết này trình bày quá trình xây dựng máy chủ Hugging Face MCP.

July 10, 2025
11 min read

Xây dựng Máy Chủ Hugging Face MCP

TL;DR: Máy Chủ MCP Chính Thức của Hugging Face cung cấp các tùy chọn tùy chỉnh độc đáo cho Trợ lý AI truy cập Hub, cùng với quyền truy cập vào hàng nghìn ứng dụng AI thông qua một URL đơn giản. Chúng tôi đã sử dụng phương thức truyền tải “HTTP có thể phát trực tuyến” của MCP để triển khai và xem xét chi tiết các đánh đổi mà Nhà phát triển Máy chủ phải đối mặt.

Chúng tôi đã học được nhiều điều về việc xây dựng một máy chủ MCP hữu ích trong tháng qua - chúng tôi sẽ mô tả hành trình của mình ở đây.

Giới thiệu

Giao thức Ngữ cảnh Mô hình (MCP) đang thực hiện lời hứa của mình là tiêu chuẩn để kết nối Trợ lý AI với thế giới bên ngoài.

Tại Hugging Face, việc cung cấp quyền truy cập vào Hub thông qua MCP là một lựa chọn hiển nhiên và bài viết này chia sẻ kinh nghiệm của chúng tôi trong việc phát triển Máy chủ MCP <https://hf.co/mcp>.

Lựa chọn Thiết kế

Cộng đồng sử dụng Hub để nghiên cứu, phát triển, tạo nội dung và hơn thế nữa. Chúng tôi muốn cho phép mọi người tùy chỉnh máy chủ cho nhu cầu riêng của họ, cũng như dễ dàng truy cập hàng nghìn ứng dụng AI có sẵn trên Spaces. Điều này có nghĩa là làm cho Máy chủ MCP trở nên động bằng cách điều chỉnh các công cụ của người dùng một cách nhanh chóng.

Chúng tôi cũng muốn đơn giản hóa quyền truy cập bằng cách tránh các cấu hình và tải xuống phức tạp, vì vậy việc có thể truy cập từ xa thông qua một URL đơn giản là điều bắt buộc.

Máy Chủ Từ Xa

Khi xây dựng Máy chủ MCP từ xa, quyết định đầu tiên là quyết định cách khách hàng sẽ kết nối với nó. MCP cung cấp một số tùy chọn truyền tải, với các đánh đổi khác nhau. TL;DR: mã nguồn mở của chúng tôi hỗ trợ tất cả các biến thể, nhưng để sản xuất, chúng tôi đã chọn sử dụng biến thể hiện đại nhất. Phần này đi qua các tùy chọn khác nhau một cách chi tiết.

Kể từ khi ra mắt vào tháng 11 năm 2024, MCP đã trải qua quá trình phát triển nhanh chóng với 3 bản sửa đổi giao thức trong 9 tháng. Điều này đã chứng kiến sự thay thế của Phương thức truyền tải SSE bằng HTTP có thể phát trực tuyến, cũng như giới thiệu và làm lại ủy quyền.

Những thay đổi nhanh chóng này có nghĩa là hỗ trợ cho các Tính năng và bản sửa đổi MCP khác nhau trong các ứng dụng Khách hàng khác nhau, mang đến những thách thức bổ sung cho các lựa chọn thiết kế của chúng tôi.

Dưới đây là tóm tắt ngắn gọn về các Tùy chọn Truyền tải do Giao thức Ngữ cảnh Mô hình và SDK liên quan cung cấp:

Cả STDIO và HTTP with SSE đều hoàn toàn hai chiều theo mặc định - có nghĩa là Khách hàng và Máy chủ duy trì kết nối mở và có thể gửi tin nhắn cho nhau bất kỳ lúc nào.

SSE đề cập đến “Sự kiện do Máy chủ gửi” - một cách để Máy chủ HTTP duy trì kết nối mở và gửi các sự kiện để đáp ứng yêu cầu.

Hiểu về HTTP Có Thể Phát Trực Tuyến

Các nhà phát triển Máy chủ MCP phải đối mặt với rất nhiều lựa chọn khi thiết lập phương thức truyền tải HTTP có thể phát trực tuyến.

Có 3 mẫu giao tiếp chính để lựa chọn:

Phản hồi Trực tiếp - Yêu cầu/Phản hồi Đơn giản (giống như API REST tiêu chuẩn). Điều này là hoàn hảo cho các hoạt động đơn giản, không trạng thái như tìm kiếm đơn giản.
Luồng Phạm vi Yêu cầu - Luồng SSE tạm thời liên quan đến một Yêu cầu duy nhất. Điều này rất hữu ích để gửi Cập nhật Tiến trình nếu Lời gọi Công cụ mất nhiều thời gian - chẳng hạn như Tạo Video. Ngoài ra, Máy chủ có thể cần yêu cầu thông tin từ người dùng bằng một Gợi ý hoặc tiến hành yêu cầu Lấy mẫu.
Luồng Đẩy Máy Chủ - Kết nối SSE tồn tại lâu dài hỗ trợ tin nhắn do máy chủ khởi tạo. Điều này cho phép thông báo thay đổi Danh sách Tài nguyên, Công cụ và Lời nhắc hoặc Lấy mẫu và Gợi ý đặc biệt. Các kết nối này cần quản lý bổ sung như giữ kết nối và cơ chế tiếp tục khi kết nối lại.

Khi sử dụng Luồng Phạm vi Yêu cầu với SDK chính thức, hãy sử dụng các phương thức sendNotification() và sendRequest() được cung cấp trong tham số RequestHandlerExtra (TypeScript) hoặc đặt related_request_id (Python) để gửi tin nhắn đến đúng luồng.

Một yếu tố bổ sung cần xem xét là liệu bản thân Máy chủ MCP có cần duy trì trạng thái cho từng kết nối hay không. Điều này được Máy chủ quyết định khi Khách hàng gửi yêu cầu Khởi tạo của nó:

Bảng dưới đây tóm tắt các Tính năng MCP và mẫu giao tiếp được hỗ trợ của chúng:

Với luồng có phạm vi yêu cầu, các yêu cầu Lấy mẫu và Gợi ý cần một kết nối có trạng thái để mcp-session-id có thể được sử dụng để liên kết phản hồi.

Máy chủ Hugging Face MCP là Mã Nguồn Mở - và hỗ trợ STDIO, SSE và HTTP có thể phát trực tuyến ở cả chế độ Phản hồi Trực tiếp và Đẩy Máy chủ. Bạn có thể định cấu hình thời gian chờ hoạt động cuối cùng và giữ kết nối khi sử dụng Luồng Đẩy Máy chủ. Ngoài ra, còn có một bảng điều khiển khả năng quan sát tích hợp mà bạn có thể sử dụng để hiểu cách các Khách hàng khác nhau quản lý kết nối và xử lý thông báo thay đổi Danh sách Công cụ.

Hình ảnh sau đây cho thấy bảng điều khiển kết nối Máy chủ MCP của chúng tôi đang chạy ở chế độ HTTP có thể phát trực tuyến “Đẩy Máy chủ”:

Triển Khai Sản Xuất

Để sản xuất, chúng tôi quyết định khởi chạy Máy chủ MCP của mình bằng HTTP có thể phát trực tuyến trong cấu hình Phản hồi Trực tiếp, Không Trạng Thái vì những lý do sau:

Không Trạng Thái Đối với người dùng ẩn danh, chúng tôi cung cấp một bộ Công cụ tiêu chuẩn để sử dụng Hub cùng với một Trình tạo Hình ảnh. Đối với người dùng được xác thực, trạng thái của chúng tôi bao gồm các công cụ đã chọn của họ và các ứng dụng Gradio đã chọn. Chúng tôi cũng đảm bảo rằng hạn ngạch ZeroGPU của người dùng được áp dụng chính xác cho tài khoản của họ. Điều này được quản lý bằng cách sử dụng HF_TOKEN hoặc thông tin xác thực OAuth được cung cấp mà chúng tôi tra cứu theo yêu cầu. Không có công cụ hiện tại nào của chúng tôi yêu cầu chúng tôi duy trì bất kỳ trạng thái nào khác giữa các yêu cầu.

Bạn có thể sử dụng đăng nhập OAuth bằng cách thêm ?login vào url Máy chủ MCP - ví dụ: <https://huggingface.co/mcp?login>. Chúng tôi có thể biến điều này thành mặc định sau khi tích hợp từ xa claude.ai hỗ trợ thông số kỹ thuật OAuth mới nhất.

Phản hồi Trực tiếp cung cấp chi phí tài nguyên triển khai thấp nhất - và hiện tại chúng tôi không có bất kỳ Công cụ nào yêu cầu Lấy mẫu hoặc Gợi ý trong quá trình thực thi.

Hỗ trợ Trong Tương Lai Khi ra mắt, phương thức truyền tải “HTTP với SSE” vẫn là mặc định từ xa trong rất nhiều Khách hàng MCP. Tuy nhiên, chúng tôi không muốn đầu tư nhiều vào việc quản lý nó do sự ngừng hoạt động sắp xảy ra. May mắn thay, các khách hàng phổ biến đã bắt đầu chuyển đổi (VSCode và Cursor) và trong vòng một tuần sau khi ra mắt, claude.ai cũng đã thêm hỗ trợ. Nếu bạn cần kết nối với SSE, vui lòng triển khai một bản sao Máy chủ của chúng tôi trên Không Gian Hugging Face FreeCPU.

Thông Báo Thay Đổi Danh Sách Công Cụ

Trong tương lai, chúng tôi muốn hỗ trợ thông báo Thay đổi Danh sách Công cụ theo thời gian thực khi người dùng cập nhật cài đặt của họ trên Hub. Tuy nhiên, điều này đặt ra một vài vấn đề thực tế:

Đầu tiên, người dùng có xu hướng định cấu hình Máy chủ MCP yêu thích của họ trong Khách hàng của họ và để chúng được bật. Điều này có nghĩa là Khách hàng vẫn được kết nối trong khi ứng dụng đang mở. Gửi thông báo có nghĩa là duy trì số lượng kết nối mở tương đương với số lượng Khách hàng đang hoạt động - bất kể việc sử dụng tích cực - trong trường hợp người dùng cập nhật cấu hình công cụ của họ.

Thứ hai, hầu hết các Máy chủ và Khách hàng MCP ngắt kết nối sau một khoảng thời gian không hoạt động và tiếp tục khi cần thiết. Điều này chắc chắn có nghĩa là các thông báo đẩy tức thì sẽ bị bỏ lỡ - vì kênh thông báo sẽ bị đóng. Trong thực tế, việc Khách hàng làm mới kết nối và Danh sách Công cụ khi cần là đơn giản hơn nhiều.

Trừ khi bạn có khả năng kiểm soát hợp lý cặp Khách hàng/Máy chủ, việc sử dụng Luồng Đẩy Máy Chủ sẽ làm tăng thêm rất nhiều độ phức tạp cho việc triển khai công khai, khi các giải pháp tài nguyên thấp hơn để làm mới Danh sách Công cụ tồn tại.

Trải Nghiệm Người Dùng URL

Ngay trước khi ra mắt, @julien-c đã gửi một PR để bao gồm các hướng dẫn thân thiện cho người dùng truy cập hf.co/mcp. Điều này cải thiện đáng kể Trải nghiệm Người dùng - phản hồi mặc định nếu không sẽ là một chút JSON không thân thiện.

Ban đầu, chúng tôi thấy điều này tạo ra một lượng lưu lượng truy cập khổng lồ. Sau một chút điều tra, chúng tôi phát hiện ra rằng khi trả về một trang web thay vì lỗi HTTP 405, VSCode sẽ thăm dò điểm cuối nhiều lần mỗi giây!

Bản sửa lỗi được đề xuất bởi @coyotte508 là phát hiện đúng trình duyệt và chỉ trả về trang trong trường hợp đó. Cũng xin cảm ơn nhóm VSCode đã nhanh chóng sửa nó.

Mặc dù không được nêu cụ thể - việc trả lại một trang theo cách này có vẻ chấp nhận được trong Thông số kỹ thuật MCP.

Hành Vi Khách Hàng MCP

Giao thức MCP gửi một số yêu cầu trong quá trình khởi tạo. Một chuỗi kết nối điển hình là: Khởi tạo, Thông báo/Khởi tạo, tools/list và sau đó là prompts/list.

Với việc Khách hàng MCP sẽ kết nối và kết nối lại khi đang mở và thực tế là người dùng thực hiện các lệnh gọi định kỳ, chúng tôi thấy có tỷ lệ khoảng 100 tin nhắn Điều khiển MCP cho mỗi Lệnh gọi Công cụ.

Một số khách hàng cũng gửi các yêu cầu không có ý nghĩa gì đối với cấu hình Phản hồi Trực tiếp, Không Trạng Thái của chúng tôi - ví dụ: Ping, Hủy hoặc cố gắng liệt kê Tài nguyên (đây không phải là khả năng mà chúng tôi hiện đang quảng cáo).

Tuần đầu tiên của tháng 7 năm 2025 đã chứng kiến 164 Khách hàng khác nhau đáng kinh ngạc truy cập Máy chủ của chúng tôi. Điều thú vị là một trong những công cụ phổ biến nhất là mcp-remote. Khoảng một nửa số Khách hàng sử dụng nó như một cầu nối để kết nối với máy chủ từ xa của chúng tôi.

Kết luận

MCP đang phát triển nhanh chóng và chúng tôi rất hào hứng với những gì đã đạt được trên các Ứng dụng Chat, IDE, Agent và Máy chủ MCP trong vài tháng qua.

Chúng tôi đã có thể thấy việc tích hợp Hugging Face Hub mạnh mẽ như thế nào và hỗ trợ cho Gradio Spaces hiện giúp các LLM có thể dễ dàng mở rộng với các ứng dụng Máy học mới nhất.

Dưới đây là một số ví dụ tuyệt vời về những điều mà mọi người đã làm với Máy chủ MCP của chúng tôi cho đến nay:

Chúng tôi hy vọng rằng bài đăng này đã cung cấp những hiểu biết sâu sắc về các quyết định cần đưa ra khi xây dựng Máy chủ MCP Từ Xa và khuyến khích bạn thử một số ví dụ trong Khách hàng MCP yêu thích của mình.

Hãy xem Máy chủ MCP Nguồn Mở của chúng tôi và thử một số tùy chọn truyền tải khác nhau với Khách hàng của bạn hoặc mở một Vấn đề hoặc Yêu cầu Kéo để cải thiện hoặc đề xuất chức năng mới.

Hãy cho chúng tôi biết suy nghĩ, phản hồi và câu hỏi của bạn về luồng thảo luận này.

AI Today - SkyAI