Hướng dẫn Gradio MCP Server: Xây dựng, Kiểm thử, Triển khai & Tích hợp

Model Context Protocol (MCP) là một tiêu chuẩn mở để kết nối các mô hình AI với công cụ, API và nguồn dữ liệu bên ngoài. Nó cung cấp một cách chuẩn hóa để các mô hình ngôn ngữ lớn (LLM) tương tác với hệ thống bên ngoài. 

Khi thế giới chuyển sang các quy trình tác tử, nơi hệ thống AI hoạt động như các tác tử tự chủ, việc học MCP ngày càng trở nên quan trọng. Hệ sinh thái Gradio cung cấp cách đơn giản và hiệu quả nhất để xây dựng máy chủ MCP, giúp nhà phát triển tạo công cụ AI mạnh mẽ với nỗ lực tối thiểu.

Trong hướng dẫn này, chúng ta sẽ:

1. Thiết lập một máy chủ Gradio MCP đơn giản trên máy và kiểm thử.
2. Xây dựng máy chủ MCP sẵn sàng cho sản xuất với nhiều công cụ.
3. Triển khai lên Hugging Face Spaces.
4. Kiểm thử với Cursor AI và Claude Desktop.

Nếu bạn muốn thực hành với Thiết kế hệ thống tác tử với LangChain, tôi khuyên bạn nên xem khóa học của chúng tôi. 

Bắt đầu với Gradio MCP

Phiên bản mới nhất của Gradio (5.32.0) hiện hỗ trợ MCP nguyên bản, giúp việc xây dựng và chạy máy chủ MCP trở nên cực kỳ dễ dàng. Bạn chỉ cần bật hỗ trợ MCP qua một tham số mã đơn giản hoặc biến môi trường. 

Máy chủ Gradio MCP sử dụng giao thức Server-Sent Events (SSE), cung cấp liên lạc thời gian thực một chiều từ máy chủ đến khách hàng — rất phù hợp để stream phản hồi từ LLM.

1. Cài đặt phiên bản Gradio mới nhất có hỗ trợ MCP.

pip install -U "gradio[mcp]"

2. Xây dựng một ứng dụng Gradio nhận tên thành phố làm đầu vào và trả về dữ liệu thời tiết (dữ liệu giả lập trong ví dụ này). Đây là điểm khởi đầu tuyệt vời, đặc biệt nếu bạn đã quen với Gradio.

import gradio as gr


def check_weather(city):
    """
    Simple weather checker function (mock data for demonstration).

    Args:
        city (str): The city name to check weather for

    Returns:
        str: Weather information for the city
    """
    # Mock weather data for demonstration
    weather_data = {
        "london": "Cloudy, 15°C",
        "paris": "Sunny, 22°C",
        "tokyo": "Rainy, 18°C",
        "new york": "Partly cloudy, 20°C",
        "sydney": "Sunny, 25°C",
    }

    city_lower = city.lower().strip()

    if city_lower in weather_data:
        return f"Weather in {city.title()}: {weather_data[city_lower]}"
    else:
        return f"Weather data not available for {city}. Try: London, Paris, Tokyo, New York, or Sydney"


demo = gr.Interface(
    fn=check_weather,
    inputs=[gr.Textbox("London", label="Enter city name")],
    outputs=[gr.Textbox(label="Weather Info")],
    title="Simple Weather Checker",
    description="Enter a city name to check the weather (demo with mock data).",
)

if __name__ == "__main__":
    demo.launch(mcp_server=True)

3. Có hai cách để bật hỗ trợ MCP trong Gradio:

• Dùng tham số mcp_server: demo.launch(mcp_server=True)
• Dùng biến môi trường: export GRADIO_MCP_SERVER=True

4. Lưu file Python test.py và chạy nó. 

$ python test.py                                            
* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set `share=True` in `launch()`.

🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sse

Bạn sẽ thấy hai URL trong đầu ra của terminal:

• App URL: http://127.0.0.1:7860 (mở ứng dụng Gradio trên trình duyệt của bạn).
• MCP Server URL: http://127.0.0.1:7860/gradio_api/mcp/sse (được dùng bởi các client tương thích MCP).

5. Mở app URL (http://127.0.0.1:7860) trong trình duyệt. Nhập tên thành phố (ví dụ: Tokyo) và kiểm tra thời tiết.

6. Ở cuối ứng dụng, nhấp nút "Use via API or MCP". Thao tác này sẽ hiển thị thêm thông tin về API của ứng dụng và máy chủ MCP.

7. Để kiểm thử máy chủ MCP với Cursor AI, mở Cài đặt Cursor, vào tab “MCP”, và nhấp nút “+ Add new global MCP server”.

8. Thêm cấu hình JSON sau vào file cài đặt MCP:

{
  "mcpServers": {
    "gradio": {
      "url": "http://127.0.0.1:7860/gradio_api/mcp/sse"
    }
  }
}

9. Lưu file. Giờ bạn sẽ thấy một máy chủ MCP hoạt động tên là gradio với công cụ check_weather.

Để kiểm thử máy chủ MCP này, chúng ta sẽ tạo cuộc trò chuyện mới ở chế độ agent của Cursor (CTRL + T) và hỏi về thời tiết ở Tokyo. Cursor sẽ xin quyền chạy công cụ MCP. Hãy chấp thuận.

Kết quả là máy chủ MCP sẽ lấy dữ liệu thời tiết và trả về kết quả:

Xây dựng máy chủ MCP đa công cụ với Gradio

Hãy tạo thứ gì đó thực tiễn và sẵn sàng cho sản xuất. Trong dự án này, chúng ta sẽ xây dựng một máy chủ MCP đa công cụ bằng Gradio. 

Máy chủ sẽ bao gồm hai công cụ:

1. Công cụ thời tiết trực tiếp: Lấy dữ liệu thời tiết thời gian thực bằng Tavily API.
2. Công cụ tin tức thành phố: Truy xuất 5 tiêu đề tin tức mới nhất về một thành phố bằng Tavily API.

Máy chủ này sẽ giúp người dùng lên kế hoạch du lịch bằng cách cung cấp cả cập nhật thời tiết và tin tức liên quan. 

Chúng ta sẽ thiết lập máy chủ MCP, kiểm thử cục bộ, triển khai lên Hugging Face Spaces và kiểm thử máy chủ đã triển khai bằng Cursor AI và Claude Desktop.

1. Thiết lập

Chúng ta cần tạo Space mới bằng cách truy cập https://huggingface.co/new-space, thêm tên ứng dụng, mô tả ngắn và chọn Gradio làm mẫu.

Nguồn: new-space

Sau khi tạo, bạn sẽ được chuyển hướng đến Space mới. Hãy làm theo hướng dẫn để thiết lập.

Clone repository về thư mục dự án cục bộ của bạn

git clone https://huggingface.co/spaces/kingabzpro/live-city-mcp

Trong dự án này, chúng ta sẽ dùng Tavily API cho khả năng tìm kiếm web, vui lòng tạo tài khoản trên Tavily AI và tạo khóa API.

Nguồn: Tavily AI

Sau đó, lưu khóa API thành biến môi trường trên hệ thống của bạn

TAVILY_API_KEY="API-KEY"

Tiếp theo, cài đặt Tavily Python SDK

pip install tavily-python

2. Tạo máy chủ MCP

Máy chủ MCP này có hai công cụ, cả hai đều dùng Tavily API để truy cập thông tin mới nhất từ web. Công cụ đầu nhận tên thành phố và tạo báo cáo thời tiết chi tiết, công cụ thứ hai nhận tên thành phố và liệt kê tiêu đề của năm câu chuyện thời sự hàng đầu trong khu vực. Chúng tôi đã tạo giao diện đồ họa cho từng công cụ và kết hợp chúng bằng Tabbed Interface.

app.py:

import gradio as gr
from tavily import TavilyClient


def get_city_weather_info(city_name):
    """
    Search for current weather information about a city using Tavily search API

    Args:
        city_name (str): Name of the city
        api_key (str): Your Tavily API key

    Returns:
        dict: Search results containing weather information
    """
    # Initialize Tavily client
    client = TavilyClient()

    # Search for current weather information
    search_query = f"current weather in {city_name} temperature humidity conditions"

    try:
        # Perform the search
        response = client.search(
            query=search_query, search_depth="basic", max_results=5
        )

        # Extract relevant information from search results
        weather_info = {"city": city_name, "search_query": search_query, "results": []}

        # Process each search result
        for result in response.get("results", []):
            weather_info["results"].append(
                {
                    "title": result.get("title", ""),
                    "content": result.get("content", ""),
                    "url": result.get("url", ""),
                }
            )

        # Add the answer if available
        if "answer" in response:
            weather_info["summary"] = response["answer"]

        return weather_info

    except Exception as e:
        return {
            "city": city_name,
            "error": f"Failed to fetch weather information: {str(e)}",
        }


def get_city_news(city_name):
    """
    Fetches the top 5 news articles for a given city using the Tavily API.

    Args:
        city_name (str): Name of the city

    Returns:
        dict: News results containing the top 5 articles or an error message
    """
    # Initialize Tavily client
    client = TavilyClient()

    # Search query for news about the city
    search_query = f"Top 5 latest news articles about {city_name}, including major events, politics, economy, and local updates."

    try:
        # Perform the search
        response = client.search(
            query=search_query,
            search_depth="advanced",
            max_results=5,
        )

        # Extract relevant information from search results
        news_info = {"city": city_name, "search_query": search_query, "articles": []}

        # Process each search result
        for result in response.get("results", []):
            news_info["articles"].append(
                {
                    "title": result.get("title", ""),
                    "content": result.get("content", ""),
                    "url": result.get("url", ""),
                }
            )

        # Add the answer if available
        if "answer" in response:
            news_info["summary"] = response["answer"]

        return news_info

    except Exception as e:
        return {"city": city_name, "error": f"Failed to fetch news: {str(e)}"}


# Create Gradio interfaces
weather_demo = gr.Interface(
    fn=get_city_weather_info,
    inputs=gr.Textbox(label="Enter City Name", placeholder="e.g., New York"),
    outputs=gr.JSON(label="Weather Information"),
    description="Get current weather details for a city.",
)

news_demo = gr.Interface(
    fn=get_city_news,
    inputs=gr.Textbox(label="Enter City Name", placeholder="e.g., London"),
    outputs=gr.JSON(label="News Articles"),
    description="Get the latest news articles for a city.",
)

# Create tabbed interface
demo = gr.TabbedInterface(
    [weather_demo, news_demo], ["Weather", "News"], title="City Information Hub"
)

if __name__ == "__main__":
    # Launch without MCP server to avoid initialization issues
    demo.launch(share=False, mcp_server=True, debug=True)

3. Kiểm thử máy chủ MCP cục bộ

Trước khi triển khai máy chủ MCP, cần kiểm thử cục bộ. Khởi động máy chủ bằng cách chạy lệnh sau trong terminal: 

python app.py

Đầu ra:

* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set `share=True` in `launch()`.

🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sse

Mở trình duyệt và truy cập http://127.0.0.1:7860 rồi nhập tên thành phố vào ô nhập. Máy chủ sẽ trả về thông tin thời tiết chi tiết ở định dạng JSON.

Ứng dụng sẽ hoạt động trơn tru, cung cấp dữ liệu thời tiết và tin tức chính xác cho thành phố đã nhập.

4. Triển khai máy chủ MCP lên Hugging Face Spaces

Để triển khai máy chủ, hãy làm theo các bước:

1. Tạo file requirements.txt và thêm phụ thuộc sau:

tavily-python==0.7.3

2. Commit thay đổi và đẩy lên Hugging Face Space.

git add .                                                                                                
live-city-mcp  git commit -m "weather and news MCP"                                                                     
git push  

Sau khi đẩy, Hugging Face Space sẽ bắt đầu build. 

Nguồn: Live City Mcp

Sau khoảng một phút, máy chủ MCP sẽ hoạt động trực tuyến và truy cập được tại Live City Mcp.

Nguồn: Live City Mcp

3. Trước khi dùng như máy chủ MCP, chúng ta cần đặt biến môi trường với token truy cập Tavily. Để làm điều này, vào phần cài đặt của Spaces, cuộn xuống và nhấp nút "New Secret". Sau đó, thêm khóa API và tên API Tavily.

Nguồn: live-city-mcp/settings

5. Kiểm thử máy chủ MCP đã triển khai với Cursor AI

MCP của chúng ta đã được triển khai và hoạt động ổn định. Giờ chúng ta sẽ thiết lập client MCP. Đầu tiên, cấu hình Cursor AI. Vào Cài đặt Cursor, nhấp tab MCP, rồi bấm nút "+Add new global MCP server." Nhập đoạn mã sau:

{
  "mcpServers": {
    "weather-news": {
      "url": "https://kingabzpro-live-city-mcp.hf.space/gradio_api/mcp/sse"
    }
  }
}

Bạn sẽ thấy weather-news MCP đang chạy tốt với hai công cụ. Hãy hỏi về thời tiết ở Islamabad. 

Như ta thấy, phản hồi nhanh và chính xác.

Chúng ta có thể kiểm chứng độ chính xác bằng cách tìm kiếm trực tuyến và xem thời tiết trên AccuWeather. 

Nguồn: AccuWeather

Tiếp theo, hãy kiểm thử công cụ thứ hai bằng cách hỏi về tin tức xung quanh Islamabad.

Kết quả là chúng ta nhận được danh sách bốn tiêu đề tin tức về Pakistan. Nếu Tavily API không tìm được tin mới liên quan đến Islamabad, nó sẽ chuyển sang tin cấp quốc gia.

6. Kiểm thử máy chủ MCP đã triển khai với Claude Desktop

Hãy thiết lập Claude Desktop bằng cách vào phần cài đặt, nhấp “Developer”, rồi nhấp nút “Edit Config”. Thao tác này sẽ đưa bạn đến thư mục cần chỉnh sửa file claude_desktop_config.json.

Hiện tại Claude Desktop chưa hỗ trợ máy chủ MCP dựa trên SSE. Trong trường hợp này, bạn có thể dùng công cụ mcp-remote. 

Để chạy mcp-remote, trước tiên bạn phải cài đặt Node.js bằng cách truy cập trang Download Node.js®. Sau đó, thêm đoạn mã sau vào file claude_desktop_config.json của bạn:

 "Live City MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://kingabzpro-live-city-mcp.hf.space/gradio_api/mcp/sse",
        "--transport",
        "sse-only"
      ]
    }

Dưới đây là ví dụ thêm cấu hình máy chủ MCP.

Sau khi hoàn tất, vui lòng thoát ứng dụng Claude Desktop và mở lại. Bạn sẽ thấy quyền truy cập vào máy chủ MCP mới có tên “Live City MCP”, kèm hai công cụ sẵn có.

Tôi sắp đi Ireland, nên tôi đã hỏi về thời tiết ở Dublin và nhận được kết quả rất tốt.

Cách tốt nhất để truy cập máy chủ MCP là qua Claude Desktop. Nó tương tác tốt và cung cấp thêm khả năng dùng công cụ cũng như hiển thị thông tin rõ ràng.

Kết luận

Nếu bạn đã quen tạo ứng dụng Gradio cho các dự án machine learning, việc chuyển ứng dụng hiện có thành máy chủ MCP chưa bao giờ dễ đến thế. Chỉ với một tham số (mcp_server=True), ứng dụng Gradio của bạn cũng có thể hoạt động như máy chủ MCP, cho phép tích hợp liền mạch với các công cụ như Cursor AI và Claude Desktop. Điều này mở ra nhiều khả năng thú vị để kết nối ứng dụng AI của bạn với hệ thống và quy trình bên ngoài.

Trong hướng dẫn thú vị này, chúng ta đã khám phá những điều cơ bản về Gradio MCP, học cách xây dựng và kiểm thử máy chủ MCP, và thực hiện một dự án thực tế dùng Tavily API để lấy dữ liệu thời tiết trực tiếp và tin tức thành phố. Cuối cùng, chúng ta triển khai dự án lên Hugging Face Spaces và kiểm thử với các client tương thích MCP phổ biến.

Nếu bạn muốn tìm hiểu thêm về AI tác tử và các khái niệm đã đề cập trong hướng dẫn này, tôi khuyên bạn xem các tài nguyên dưới đây: 

• Tìm hiểu AI Agents: Tương lai của hệ thống tự chủ
• Claude Code: Hướng dẫn với ví dụ thực tiễn
• Làm việc với Hugging Face | Hướng dẫn về Hub
• Xây dựng tác tử LangChain động
• Chrome DevTools MCP: Tự động hóa và gỡ lỗi trình duyệt bằng AI