Tích hợp Gradio với MCP · Khoá học MCP (Hugging Face)

Chúng ta đã tìm hiểu các khái niệm cốt lõi của giao thức MCP và cách hiện thực MCP server, client. Trong phần này, mọi thứ sẽ dễ hơn một chút: chúng ta dùng Gradio để tạo một MCP server!

Giới thiệu Gradio

Gradio cho phép lập trình viên tạo giao diện cho model chỉ với vài dòng code Python. Nó đặc biệt hữu ích để:

Tạo demo và bản mẫu (prototype)
Chia sẻ model với người dùng không chuyên kỹ thuật
Kiểm thử và gỡ lỗi hành vi của model

Với việc hỗ trợ thêm MCP, Gradio giờ cung cấp cách đơn giản để đưa các khả năng (capability) của model AI ra ngoài thông qua giao thức chuẩn MCP.

Kết hợp Gradio với MCP giúp bạn tạo được cả giao diện thân thiện với con người lẫn tool mà AI truy cập được, chỉ với rất ít code. Hơn hết, Gradio đã được cộng đồng AI dùng rộng rãi, nên bạn có thể dùng nó để chia sẻ MCP server của mình với người khác.

Chuẩn bị

Để dùng Gradio có hỗ trợ MCP, bạn cần cài Gradio kèm phần bổ sung MCP:

bash

uv pip install "gradio[mcp]"

Bạn cũng cần một ứng dụng LLM hỗ trợ gọi tool qua giao thức MCP, chẳng hạn Cursor (loại ứng dụng này được gọi là "MCP host").

Tạo MCP server bằng Gradio

Hãy cùng xem một ví dụ cơ bản tạo MCP server bằng Gradio:

python

import gradio as gr

def letter_counter(word: str, letter: str) -> int:
    """
    Count the number of occurrences of a letter in a word or text.

    Args:
        word (str): The input text to search through
        letter (str): The letter to search for

    Returns:
        int: The number of times the letter appears in the text
    """
    word = word.lower()
    letter = letter.lower()
    count = word.count(letter)
    return count

# Create a standard Gradio interface
demo = gr.Interface(
    fn=letter_counter,
    inputs=["textbox", "textbox"],
    outputs="number",
    title="Letter Counter",
    description="Enter text and a letter to count how many times the letter appears in the text."
)

# Launch both the Gradio web interface and the MCP server
if __name__ == "__main__":
    demo.launch(mcp_server=True)

Với thiết lập này, hàm đếm chữ cái của bạn giờ có thể được truy cập qua:

Giao diện web Gradio truyền thống để con người tương tác trực tiếp
Một MCP server mà các client tương thích có thể kết nối tới

MCP server sẽ có ở địa chỉ:

code

http://your-server:port/gradio_api/mcp/sse

Bản thân ứng dụng vẫn truy cập được bình thường và trông như sau:

Ứng dụng Gradio chạy kèm MCP server

Điều gì diễn ra phía sau

Khi bạn đặt mcp_server=True trong launch(), một số việc sẽ diễn ra:

Các hàm Gradio được tự động chuyển thành MCP tool
Các component đầu vào được ánh xạ thành schema tham số của tool
Các component đầu ra quyết định định dạng phản hồi
Server Gradio giờ cũng lắng nghe các thông điệp theo giao thức MCP
JSON-RPC qua HTTP+SSE được thiết lập cho giao tiếp client-server

Tính năng chính của tích hợp Gradio và MCP

Chuyển đổi thành tool: Mỗi API endpoint trong ứng dụng Gradio được tự động chuyển thành một MCP tool với tên, mô tả và schema đầu vào tương ứng. Để xem các tool và schema, truy cập http://your-server:port/gradio_api/mcp/schema hoặc bấm link "View API" ở chân trang ứng dụng Gradio, rồi chọn "MCP".
Hỗ trợ biến môi trường: Có hai cách bật chức năng MCP server:
- Dùng tham số mcp_server trong launch():
  python
```
demo.launch(mcp_server=True)
```
- Dùng biến môi trường:
  bash
```
export GRADIO_MCP_SERVER=True
```
Xử lý file: Server tự động xử lý việc chuyển đổi dữ liệu file, gồm:
- Chuyển chuỗi mã hoá base64 thành dữ liệu file
- Xử lý file ảnh và trả về đúng định dạng
- Quản lý bộ nhớ lưu file tạm
Rất nên truyền ảnh và file đầu vào dưới dạng URL đầy đủ ("http://..." hoặc "https://...") vì MCP client không phải lúc nào cũng xử lý đúng file cục bộ.
MCP server được host trên Hugging Face Spaces: Bạn có thể công bố ứng dụng Gradio miễn phí trên Hugging Face Spaces, nhờ đó có một MCP server được host miễn phí. Ví dụ một Space như vậy: https://huggingface.co/spaces/abidlabs/mcp-tools

Dùng các Space hỗ trợ MCP từ client

Bạn có thể kết nối bất kỳ Space nào hỗ trợ MCP với trợ lý của mình qua phần cài đặt MCP của Hugging Face:

Khám phá các Space hỗ trợ MCP: https://huggingface.co/spaces?search=mcp
Mở https://huggingface.co/settings/mcp (khi đã đăng nhập) và thêm Space.
Khởi động lại hoặc làm mới MCP client để nó phát hiện các tool mới.

Các Space này cung cấp hàm của chúng dưới dạng tool kèm tham số và mô tả, để trợ lý có thể gọi trực tiếp.

Mẹo xử lý sự cố

Type hint và docstring: Hãy chắc chắn bạn khai báo type hint và docstring hợp lệ cho các hàm. Docstring cần có khối "Args:" với tên tham số được thụt lề.
Đầu vào dạng chuỗi: Khi không chắc, hãy nhận tham số đầu vào kiểu str rồi chuyển sang kiểu mong muốn bên trong hàm.

Hỗ trợ SSE: Một số MCP host không hỗ trợ MCP server dựa trên SSE. Khi đó, bạn có thể dùng mcp-remote:

json

{
  "mcpServers": {
    "gradio": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://your-server:port/gradio_api/mcp/sse"
      ]
    }
  }
}

Khởi động lại: Nếu gặp lỗi kết nối, hãy thử khởi động lại cả MCP client lẫn MCP server.

Chia sẻ MCP server

Bạn có thể chia sẻ MCP server bằng cách công bố ứng dụng Gradio lên Hugging Face Spaces. Video này hướng dẫn cách tạo một Hugging Face Space.

Sau đó, bạn có thể chia sẻ MCP server với người khác bằng cách chia sẻ Hugging Face Space của mình.

Kết luận

Tích hợp Gradio với MCP là điểm khởi đầu dễ tiếp cận để bước vào hệ sinh thái MCP. Tận dụng sự đơn giản của Gradio cùng tính chuẩn hoá của MCP, lập trình viên có thể nhanh chóng tạo cả giao diện thân thiện với con người lẫn tool mà AI truy cập được, chỉ với rất ít code.

Trong suốt khoá học, chúng ta sẽ tìm hiểu các cách hiện thực MCP phức tạp hơn, nhưng Gradio là điểm khởi đầu tuyệt vời để hiểu và thử nghiệm giao thức này.

Ở unit tiếp theo, chúng ta sẽ đi sâu hơn vào việc xây dựng ứng dụng MCP, tập trung vào thiết lập môi trường phát triển, tìm hiểu SDK và hiện thực các MCP server, client nâng cao hơn.

Nguồn

Dịch và biên tập từ huggingface/mcp-course · units/en/unit1/gradio-mcp.mdx, giấy phép Apache-2.0.