Posted inAI

Xây dựng MCP Server ‘thần tốc’ với FastMCP: Kết nối AI vào dữ liệu nội bộ bằng Python

Artificial Intelligence tutorial - IT technology blog
Artificial Intelligence tutorial - IT technology blog

Nỗi khổ khi build MCP Server theo cách “cổ điển”

Tháng trước, mình nhận task gấp lúc 2 giờ sáng. Team cần kết nối Claude Desktop vào hệ thống log để tự động bắt bệnh khi server sập. Mình hùng hục dùng SDK tiêu chuẩn của Model Context Protocol (MCP). Kết quả? Mình mất hơn 1 tiếng chỉ để viết đống boilerplate code: định nghĩa schema JSON, quản lý kết nối và handle lỗi vặt.

Cảm giác lúc đó giống như bạn chỉ muốn đóng cái đinh nhưng phải tự đi đúc luôn cả cái búa. SDK gốc rất mạnh nhưng quá thấp cấp (low-level) cho nhu cầu triển khai nhanh. Đó là lý do mình chuyển sang FastMCP. Framework này giúp việc tạo MCP Server nhẹ nhàng y hệt cách FastAPI đã làm với Web API.

So sánh: SDK tiêu chuẩn vs. FastMCP

Trước khi bắt tay vào code, hãy nhìn qua sự khác biệt. Bạn sẽ hiểu tại sao FastMCP là lựa chọn hàng đầu cho các dự án thực tế hiện nay.

1. MCP Python SDK (Cách cũ)

Với cách này, bạn phải định nghĩa thủ công mọi thứ. Muốn thêm một công cụ (tool), bạn phải viết hàm, đăng ký vào danh sách và mô tả input/output bằng JSON Schema cực kỳ rườm rà. Chỉ cần thiếu một dấu phẩy trong schema, AI sẽ “ngẩn ngơ” không hiểu tool đó dùng làm gì.

2. FastMCP (Cách mới)

FastMCP sử dụng Python Decorators tương tự như FastAPI. Bạn chỉ cần viết hàm Python thuần túy và thêm decorator. Framework sẽ tự lo phần tạo JSON Schema, validate dữ liệu và đăng ký với MCP client. Việc này giảm tới 80% lượng code thừa thãi.

Tiêu chí Standard SDK FastMCP
Thời gian triển khai Vài tiếng Vài phút
Định nghĩa Tool JSON Schema thủ công Tự động qua Decorators
Độ phức tạp Cao, dễ sai sót Thấp, dễ bảo trì
Validation Phải tự viết logic Dựa trên Python Type Hints

Tại sao FastMCP lại đáng dùng?

Ưu điểm lớn nhất mình nhận thấy là Developer Experience (DX). Khi đang tập trung vào logic nghiệp vụ, bạn sẽ không muốn phải vật lộn với cấu trúc giao thức. FastMCP giúp mình trả lời câu hỏi: “Hàm này lấy dữ liệu gì cho AI?” thay vì “Làm sao để giải thích hàm này cho AI hiểu?”.

Dù vậy, nó vẫn có nhược điểm nhỏ là che giấu quá nhiều chi tiết bên dưới. Nếu bạn cần can thiệp cực sâu vào tầng transport, FastMCP có thể hơi gò bó. Nhưng với 95% nhu cầu thông thường, đây là lựa chọn tối ưu.

Hướng dẫn triển khai MCP Server thực tế

Chúng ta sẽ xây dựng một server cho phép AI đọc file log và kiểm tra tài nguyên hệ thống theo thời gian thực.

Bước 1: Cài đặt môi trường

Tạo môi trường ảo để tránh xung đột thư viện. Mình khuyến khích dùng uv để cài đặt nhanh hơn gấp 10 lần so với pip thông thường.

pip install fastmcp psutil

Bước 2: Viết mã nguồn cho MCP Server

Tạo file server.py. Bạn sẽ thấy nó gọn gàng đến mức bất ngờ:

from fastmcp import FastMCP
import psutil
import os

# Khởi tạo server với tên định danh
mcp = FastMCP("SystemMonitor")

# Tool để AI kiểm tra dung lượng ổ đĩa
@mcp.tool()
def get_disk_usage(path: str = "/") -> str:
    """Kiểm tra dung lượng ổ đĩa tại một đường dẫn cụ thể."""
    usage = psutil.disk_usage(path)
    free_gb = usage.free // (2**30)
    return f"Dung lượng trống: {free_gb}GB trên tổng số {usage.total // (2**30)}GB"

# Resource để AI đọc thông tin hệ thống (chỉ đọc)
@mcp.resource("config://system_info")
def get_system_info() -> str:
    """Cung cấp thông tin CPU và OS."""
    return f"OS: {os.name}, CPU: {os.cpu_count()} cores"

if __name__ == "__main__":
    mcp.run()

Giải mã đoạn code:

  • @mcp.tool(): Biến hàm Python thành công cụ AI có thể gọi. FastMCP tự soi (inspect) type hints (như path: str) để tạo schema.
  • Docstring: Đây là “cẩm nang” cho AI. Nó dựa vào đây để biết khi nào nên dùng tool.
  • @mcp.resource(): Cung cấp dữ liệu tĩnh hoặc trạng thái hệ thống cho AI tham khảo.

Bước 3: Kết nối với Claude Desktop

Để test, hãy thêm cấu hình vào file claude_desktop_config.json của bạn:

{
  "mcpServers": {
    "monitor-server": {
      "command": "python",
      "args": ["/đường/dẫn/tới/server.py"]
    }
  }
}

Khởi động lại Claude, bạn sẽ thấy icon hình tia sét xuất hiện. Giờ bạn có thể hỏi: “Ổ cứng của máy tôi còn trống bao nhiêu?” và AI sẽ tự gọi hàm Python bạn vừa viết.

Kinh nghiệm “xương máu” khi triển khai

Sau nhiều đêm debug, mình rút ra 3 lưu ý quan trọng để server chạy ổn định:

  1. Đầu tư vào Docstring: Đừng viết cho có. Hãy mô tả chi tiết: “Dùng tool này khi cần so sánh dung lượng ổ đĩa giữa các phân vùng”. AI sẽ thông minh hơn hẳn.
  2. Bọc Try-Except cẩn thận: Đừng để server crash. Hãy trả về lỗi dưới dạng string. Ví dụ: “Lỗi: Không tìm thấy đường dẫn /data”. AI sẽ đọc được và đề xuất giải pháp thay vì chết đứng.
  3. Kiểm soát quyền hạn: FastMCP chạy với quyền user hiện tại. Tuyệt đối không viết tool cho phép xóa file (os.remove) mà không có bước validate input kỹ càng.

FastMCP là con đường ngắn nhất để biến các script Python rời rạc thành một hệ thống AI Agent mạnh mẽ. Nó giúp bạn gạt bỏ rào cản kỹ thuật để tập trung vào thứ quan trọng nhất: Dữ liệu và Logic nghiệp vụ.

Share:
Tags: