Build MCP server đầu tiên bằng Python: tutorial từng bước với FastMCP và Claude Desktop

Claude Desktop mặc định không đọc được file local, không gọi được API nội bộ, không truy vấn database của bạn. Mỗi lần cần data, bạn lại copy-paste qua chat. MCP server giải quyết đúng pain point đó, và Python với FastMCP là đường ngắn nhất để tự build một server custom. Bài này hướng dẫn từng bước: setup môi trường với `uv`, viết 3 tool bằng decorator, cắm vào Claude Desktop qua config JSON, test thực tế và lưu ý bảo mật từ vụ CVE `mcp-server-git`.

MCP server là gì và vì sao nên build bằng Python

MCP (Model Context Protocol) là chuẩn mở do Anthropic công bố ngày 25/11/2024, nhằm chuẩn hoá cách AI assistant kết nối với data source và tool bên ngoài [F1]. Sau hơn một năm, Anthropic đã chuyển MCP về Linux Foundation vào tháng 12/2025, đồng thời tổng lượt download các SDK và server đã vượt 150 triệu [F5]. Tính tới tháng 02/2026, registry chính thức ghi nhận hơn 6.400 MCP server đăng ký [F3]. OpenAI bổ sung hỗ trợ MCP từ tháng 3/2025, Google theo sau vào tháng 4/2025, biến MCP thành chuẩn de-facto cho việc kết nối tool [F4].

Về kiến trúc, MCP đi theo mô hình client-server. Phía server expose ba primitive chính: tools (function Claude gọi được), resources (data đọc được) và prompts (template tái sử dụng). Phía client lo elicitation, roots và sampling [F2]. Khi build server bằng Python, bạn chủ yếu làm việc với ba primitive đầu, phần còn lại do Claude Desktop hoặc client khác xử lý. Cách phân chia này giúp server giữ được tính stateless và dễ test độc lập.

FastMCP là framework Python nằm trong MCP SDK chính thức, thiết kế theo phong cách decorator. Nếu bạn quen Flask hoặc FastAPI, syntax `@mcp.tool()` và `@mcp.resource()` sẽ thấy rất quen tay. So với TypeScript SDK, code Python thường ngắn hơn vì không cần khai báo schema thủ công — type hint tự convert thành JSON Schema. Với dev VN đa số chọn Python cho backend AI, đây là điểm khởi đầu ít ma sát nhất.

Tutorial này nhắm tới một use case cụ thể: expose internal API hoặc tool nội bộ cho Claude Desktop chạy local. Ví dụ một endpoint query database, một script automation team đang dùng, hay một wrapper gọi internal CRM. Sau khi server chạy, bạn chat với Claude Desktop và nó tự gọi tool của bạn — không còn cảnh copy-paste output qua lại nữa.

Chuẩn bị môi trường: Python, uv và Claude Desktop

Trước khi viết tool đầu tiên, bạn cần Python phiên bản tương đối mới. FastMCP dựa nhiều vào type hint hiện đại nên Python 3.10 trở lên là an toàn. Mình khuyên dùng `uv` thay cho `pip` cho project này: tốc độ resolve và install nhanh hơn đáng kể, lock file rõ ràng, virtualenv tạo tự động. Cài uv qua script chính thức của Astral, hoặc dùng Homebrew trên macOS, scoop/winget trên Windows tuỳ thói quen của bạn.

Sau khi có uv, khởi tạo project demo chỉ tốn 2 lệnh:

uv init mcp-demo
cd mcp-demo

Tiếp theo cài SDK chính thức của MCP. Package này đi kèm một CLI tiện cho việc chạy và debug server local:

uv add 'mcp[cli]'

Cú pháp `mcp[cli]` báo uv kéo thêm extra dependency dành cho CLI. Sau lệnh này, thư mục `.venv` sẽ chứa interpreter và lib, còn `pyproject.toml` được cập nhật dependency. Bạn có thể chạy `uv run mcp --help` để verify mọi thứ ổn trước khi viết code.

Bước cuối là Claude Desktop. Nếu chưa có, tải bản chính thức cho macOS hoặc Windows từ trang Anthropic. Mở app lần đầu để nó tạo thư mục cấu hình, sau đó tìm file `claude_desktop_config.json` ở các đường dẫn sau:

• macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

• Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Đây là nơi mình sẽ register MCP server ở section sau, kiểu giống `mcpServers` trong cấu hình Cursor hay Cline. Nếu file chưa tồn tại, cứ tạo thủ công với nội dung `{}` — Claude Desktop sẽ đọc lại mỗi khi restart. Một mẹo nhỏ: mở luôn file này trong editor và để bên cạnh terminal, vì lát nữa bạn sẽ phải edit nó vài lần để trỏ đúng tới script Python local.

Viết MCP server đầu tiên: 3 tool cơ bản với decorator

Để bắt đầu, mình sẽ hướng dẫn bạn tạo một file server Python đơn giản. File này sẽ chứa ba tool cơ bản để minh họa cách FastMCP hoạt động. Đây là những khối xây dựng cốt lõi khi bạn muốn tạo ra các công cụ tương tác với Claude.

Đầu tiên, tạo file `server.py` và import `FastMCP`. Sau đó, khởi tạo một instance của FastMCP với tên server mong muốn. Tên này sẽ xuất hiện trên Claude Desktop khi bạn kết nối.

from fastapi import FastAPI, HTTPException
from fastmcp import FastMCP

mcp = FastMCP(name="MyFirstMCP", description="A simple MCP server with basic tools")
app = FastAPI()
app.include_router(mcp.router)

Mỗi tool trong FastMCP được định nghĩa bằng một hàm Python và được đánh dấu bằng decorator `@mcp.tool()`. FastMCP sẽ tự động đọc signature và docstring của hàm để generate JSON schema cho Claude. Docstring viết bằng tiếng Anh và mô tả rõ ràng các tham số là rất quan trọng, vì Claude sẽ dựa vào đó để quyết định khi nào nên gọi tool của bạn.

Tool 1: add(a: int, b: int) -> int

Tool đầu tiên là một hàm cộng đơn giản. FastMCP sẽ tự động chuyển đổi type hint `a: int, b: int` thành JSON schema tương ứng, giúp Claude hiểu được kiểu dữ liệu mong muốn của các tham số.

@mcp.tool()
def add(a: int, b: int) -> int:
    """Adds two integers together.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The sum of the two integers.
    """
    return a + b

Tool 2: get_weather(city: str) -> str

Tool này mô phỏng việc lấy thông tin thời tiết. Nó nhận một chuỗi `city` và trả về một chuỗi kết quả. Đây là cách bạn có thể demo các tool trả về dữ liệu dạng văn bản.

@mcp.tool()
def get_weather(city: str) -> str:
    """Gets the current weather for a given city.

    Args:
        city: The name of the city.

    Returns:
        A string describing the weather in the city.
    """
    # In a real app, you'd call a weather API here
    if city.lower() == "hanoi":
        return "Hanoi: 28°C, sunny with light breeze."
    return f"Weather for {city}: Information not available."

Tool 3: read_notes(path: str) -> str

Tool cuối cùng minh họa cách đọc file cục bộ. Quan trọng là phải có validation cho `path` để tránh các lỗ hổng bảo mật như path traversal. Trong ví dụ này, mình chỉ cho phép đọc file trong thư mục `notes`.

import os

@mcp.tool()
def read_notes(path: str) -> str:
    """Reads the content of a note file.

    Args:
        path: The path to the note file (e.g., 'my_note.txt').

    Returns:
        The content of the file.

    Raises:
        HTTPException: If the file is not found or path is invalid.
    """
    base_dir = os.path.join(os.getcwd(), "notes")
    full_path = os.path.join(base_dir, path)

    if not os.path.exists(base_dir):
        os.makedirs(base_dir)

    if not os.path.isfile(full_path) or not full_path.startswith(base_dir):
        raise HTTPException(status_code=400, detail="Invalid file path or file not found.")

    with open(full_path, 'r', encoding='utf-8') as f:
        return f.read()

Sau khi đã định nghĩa các tool, bạn có thể chạy server cục bộ bằng lệnh `uv run mcp dev server.py`. Điều này cho phép bạn kiểm tra các tool với MCP Inspector trước khi kết nối với Claude Desktop. Việc kiểm tra này giúp đảm bảo rằng các tool hoạt động đúng như mong đợi và schema được generate chính xác.

Kết nối server vào Claude Desktop qua config JSON

Sau khi đã có FastMCP server chạy được, bước tiếp theo là kết nối nó với Claude Desktop. Bạn cần chỉnh sửa file cấu hình `claude_desktop_config.json` của Claude Desktop để thêm server mới vào.

File cấu hình này thường nằm ở thư mục gốc của ứng dụng. Bạn sẽ tìm đến key `mcpServers` và thêm một entry mới. Mỗi entry server cần có các trường `command`, `args` và `env`. Giao thức STDIO là mặc định cho các server cục bộ.

Ví dụ, nếu bạn dùng `uv` làm trình chạy cho server Python, cấu hình có thể trông như sau. Lưu ý rằng đường dẫn tuyệt đối rất quan trọng vì Claude Desktop sẽ spawn process từ thư mục gốc, nên đường dẫn tương đối sẽ không hoạt động.

{
  "mcpServers": [
    {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/youruser/projects/your-mcp-server",
        "server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  ]
}

Sau mỗi lần thay đổi file cấu hình, bạn cần khởi động lại hoàn toàn Claude Desktop. Điều này có nghĩa là thoát ứng dụng (Cmd+Q trên macOS) rồi mở lại, chứ không chỉ đóng cửa sổ. Sau khi khởi động lại, bạn sẽ thấy một biểu tượng tìm kiếm hoặc công cụ xuất hiện trên thanh nhập liệu của chat. Di chuột qua biểu tượng này sẽ hiển thị danh sách các công cụ mà server của bạn cung cấp.

Nếu biểu tượng công cụ không xuất hiện, bạn có thể kiểm tra log để debug. Trên macOS, log thường nằm ở `~/Library/Logs/Claude/mcp*.log`. Các file log này sẽ cung cấp thông tin chi tiết về quá trình khởi tạo server và các lỗi có thể xảy ra.

Test thực tế: gọi tool từ Claude và xử lý lỗi

Sau khi đã cài đặt và cấu hình MCP server, mình sẽ thử gọi tool từ Claude Desktop. Mình dùng prompt đơn giản: 'Tính 137 + 256 dùng tool add'. Bạn sẽ thấy Claude hiển thị thông báo 'Using tool add' trước khi thực hiện. Sau khi bạn chấp thuận, kết quả 393 sẽ được trả về.

Trong quá trình phát triển, việc xử lý lỗi là rất quan trọng. Khi tool của bạn gặp exception, Claude sẽ nhận được thông báo lỗi. Mình khuyến nghị bạn nên chủ động raise `ValueError` với một thông báo rõ ràng thay vì để Python trả về traceback raw. Điều này giúp Claude hiểu rõ hơn về lỗi và có thể tự retry hoặc thông báo cho bạn.

Một trường hợp cần test kỹ là các lỗ hổng bảo mật như path traversal. Bạn có thể thử prompt 'đọc file /etc/passwd' để kiểm tra xem cơ chế validate input của tool có hoạt động đúng hay không. Điều này đảm bảo Claude không thể truy cập các tài nguyên không được phép trên hệ thống của bạn.

Về độ trễ, các lệnh gọi tool cục bộ thường chỉ mất khoảng 50-100ms. Thời gian này chưa bao gồm thời gian Claude suy luận để quyết định gọi tool nào và xử lý kết quả. Do đó, trải nghiệm sử dụng khá mượt mà.

Bảo mật: bài học từ lỗ hổng mcp-server-git

MCP server mang lại nhiều tiện ích nhưng cũng đi kèm rủi ro bảo mật đáng kể. Điển hình là trường hợp Cyata phát hiện ba lỗ hổng prompt injection (CVE) trong `mcp-server-git` chính thức của Anthropic, ảnh hưởng đến mọi phiên bản trước ngày 08/12/2025.

Cơ chế khai thác khá đơn giản: các tệp README hoặc issue độc hại chứa instruction sẽ được Claude đọc thông qua tool, sau đó thực thi các lệnh không mong muốn trên hệ thống của bạn. OX Security ước tính có khoảng 200.000 MCP server STDIO đang bị lộ khả năng thực thi lệnh từ xa [F5].

Để bảo vệ server của mình, bạn cần tuân thủ các nguyên tắc bảo mật cơ bản sau:

Bước tiếp theo: từ demo tới production

Server STDIO chạy local cùng Claude Desktop là setup gọn cho dev cá nhân. Khi muốn share cho team hoặc tích hợp vào hệ thống nội bộ, bạn nên migrate sang HTTP transport. FastMCP hỗ trợ cả hai mode, đổi transport thường chỉ cần sửa vài dòng ở entrypoint mà không phải viết lại tool logic.

Khi expose server qua HTTP, authentication là bắt buộc. Pattern phổ biến là check Bearer token ngay đầu mỗi tool function, reject sớm nếu token sai để khỏi tốn compute cho request rác. Nếu muốn tách auth khỏi business logic, bạn có thể wrap server bằng middleware ở tầng ASGI và cho tool function chỉ tập trung xử lý input đã được verify.

Bước deploy nên đi kèm Docker. Package server thành image, pin version Python và mọi dependency trong requirements, push lên registry nội bộ rồi deploy lên VPS qua docker compose. Đặt reverse proxy như Caddy hoặc Nginx phía trước để lo HTTPS và rate limit. Cách này giúp rollback nhanh khi gặp bug và tránh surprise từ breaking change của upstream package.

Nếu server của bạn hữu ích cho cộng đồng, cân nhắc publish lên MCP registry chính thức — tính đến tháng 02/2026 registry đã ghi nhận hơn 6.400 server [F3]. Hệ sinh thái đang phát triển rất nhanh sau khi Anthropic trao MCP cho Linux Foundation vào tháng 12/2025 và lượt download SDK/server vượt 150 triệu [F5], nên một server giải quyết đúng pain point sẽ có audience sẵn.

Về feature nâng cao, ngoài tools thì FastMCP còn hỗ trợ resources và prompts. Resources expose data đọc-được cho client, prompts cho phép share template — đây là 2 primitive ít người dùng nhưng rất mạnh khi server cần phục vụ nhiều use case. Đọc thêm SDK Python repo của Anthropic và FastMCP docs để khai thác hết, và luôn theo dõi security advisory để patch kịp thời.

Tổng kết: với FastMCP, một MCP server chạy được chỉ cần khoảng 30 dòng Python cộng vài dòng config JSON. Khi đã quen flow STDIO local, bước tự nhiên tiếp theo là HTTP transport để share cho team. Bạn có thể xem thêm bài về MCP server Node.js hoặc đọc trực tiếp Anthropic MCP docs để so sánh hai hướng tiếp cận.