Tự xây MCP server đầu tiên bằng Python, từng bước

Trả lời nhanh: MCP server là chương trình phơi tools (hàm mà AI gọi được) theo chuẩn Model Context Protocol. Với SDK Python chính thức (gói mcp, lớp FastMCP), một server hello world chỉ ~15 dòng: định nghĩa hàm Python có docstring, gắn decorator, khai vào cấu hình Claude Code, AI của bạn lập tức biết dùng công cụ mới. Bài này đi từ đó đến một server thật: tra cứu dữ liệu nội bộ cho cả đội.

Blog TND đã có loạt bài dùng MCP server có sẵn, kết nối Postgres, GitHub, trình duyệt. Bài này lấp mảnh cuối và thú vị nhất: tự viết. Vì sức mạnh thật của MCP lộ ra khi AI chạm được thứ chỉ bạn có, bảng giá nội bộ, tồn kho, API riêng của công ty. Với từ khóa mcp server tăng 160 lần trong 4 năm, biết viết một server là kỹ năng đang lên giá nhanh, và nó dễ hơn bạn nghĩ rất nhiều.

MCP server gồm gì, nói bằng code

# pip install "mcp[cli]"   (Python 3.10+)
# file: server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("tra-cuu-noi-bo")

@mcp.tool()
def tra_gia(ten_san_pham: str) -> str:
    """Tra giá bán lẻ hiện tại của một sản phẩm theo tên."""
    bang_gia = {"vps 8gb": "599.000đ/tháng", "vps nvme 16gb": "1.099.000đ/tháng"}
    return bang_gia.get(ten_san_pham.lower(), "Không tìm thấy sản phẩm này")

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

Ba điều đáng ngộ ra từ 15 dòng này: tool là hàm Python thường, type hint và docstring không phải trang trí, chúng chính là cách model hiểu tool làm gì và truyền tham số gì; SDK lo trọn giao thức, bạn không đụng JSON-RPC; và server có thể phơi thêm resources (dữ liệu đọc) lẫn prompts (mẫu lệnh), nhưng 90% giá trị nằm ở tools, cứ tools trước.

Cắm vào Claude Code và thấy phép màu

Khai server vào Claude Code bằng một lệnh: claude mcp add tra-cuu -- python /duong-dan/server.py (hoặc thêm tay vào file cấu hình MCP của dự án). Mở phiên mới, hỏi giá VPS NVMe 16GB là bao nhiêu? Claude tự thấy tool tra_gia, tự gọi, trả về số từ dữ liệu của bạn. Khoảnh khắc đó là toàn bộ ý nghĩa của MCP: model không cần biết trước dữ liệu, nó biết cách hỏi. Debug khi không chạy: lệnh mcp dev server.py mở Inspector web cho bạn gọi tool bằng tay xem lỗi, quen thuộc như Postman của REST.

Nâng cấp thành server thật: đọc từ Google Sheet

Đổi dict cứng thành nguồn dữ liệu sống, ví dụ bảng giá + tồn kho của đội nằm trên Sheet:

import csv, urllib.request

SHEET_CSV = "https://docs.google.com/spreadsheets/d/ID/export?format=csv"

def _doc_bang_gia():
    with urllib.request.urlopen(SHEET_CSV) as r:
        return list(csv.DictReader(r.read().decode().splitlines()))

@mcp.tool()
def tra_gia(ten_san_pham: str) -> str:
    """Tra giá và tồn kho một sản phẩm theo tên (khớp gần đúng)."""
    for row in _doc_bang_gia():
        if ten_san_pham.lower() in row["ten"].lower():
            return f"{row['ten']}: {row['gia']}, tồn: {row['ton_kho']}"
    return "Không thấy. Thử tên khác?"

Mẫu này nhân bản cho mọi dữ liệu nội bộ: API công ty, database (dùng thư viện DB thay urllib), file tài liệu. Nguyên tắc an toàn khắc cốt: bắt đầu bằng tool chỉ-đọc, tool ghi/xóa (tạo đơn, sửa giá) chỉ thêm khi đã chạy tin cậy và hiểu rõ AI sẽ được phép làm gì nhân danh bạn.

Từ máy mình lên VPS: server cho cả đội

Chạy stdio như trên là server sống trong máy bạn. Muốn cả đội (và các agent trên máy khác) dùng chung: chuyển transport sang HTTP, FastMCP hỗ trợ sẵn (chạy dạng streamable HTTP trên một cổng), đặt lên VPS, và đúng bài bản của blog này: sống trong tailnet, cả đội trỏ Claude Code vào URL nội bộ, dữ liệu công ty không phơi ra internet. Chi tiết dựng hạ tầng, ngốn tài nguyên bao nhiêu và chạy nhiều server song song đã có ở bài MCP tự host trên VPS + bài chạy nhiều MCP, bài này cho bạn phần chưa có: chính con server để đặt lên đó.

Ý tưởng đáng viết tiếp, xếp theo độ thực dụng

Sau server đầu tiên, các server đáng tiền theo kinh nghiệm thật: tra cứu nghiệp vụ (bảng giá, chính sách, tồn kho, như bài); đọc hệ thống nội bộ (trạng thái đơn từ database, log lỗi gần nhất từ server, AI debug cùng bạn có dữ liệu thật); công cụ đặc thù ngành (tra mã vận đơn qua API hãng ship, tra thông tin doanh nghiệp từ MST); cầu nối tool cũ (script bash/Python sẵn có của đội bọc thành tool cho AI gọi). Mỗi con vài chục dòng theo đúng khung của bài, và mỗi con làm AI của đội bạn khôn thêm một bậc theo cách không model nào ngoài kia có.

Kiểm dịch vụ đã chạy đúng chưa

# 1. Chay thu tai cho, xem no khai bao nhung cong cu gi
python may_chu.py

# 2. Kiem cong cu duoc liet ke dung ten va dung mo ta
#    Mo ta la thu tro ly doc de quyet dinh goi cong cu nao,
#    viet mo ta cau tha la tro ly goi sai cong cu

# 3. Ghi nhat ky moi lan cong cu duoc goi, kem tham so
#    Day la cach duy nhat de go loi khi ket qua sai

# 4. Kiem xu ly loi: cong cu that bai phai tra ve thong bao ro rang,
#    khong duoc de ngoai le lam chet ca dich vu

Bốn nguyên tắc viết công cụ tốt

• Mỗi công cụ làm đúng một việc, tên và mô tả nói rõ việc đó. Công cụ ôm nhiều việc là công cụ hay bị gọi sai.
• Mô tả tham số phải nói rõ định dạng mong đợi, ví dụ ngày theo dạng nào, đơn vị là gì. Đây là chỗ quyết định trợ lý gọi đúng hay sai.
• Kiểm dữ liệu đầu vào trước khi làm gì, và trả về lỗi có nội dung thay vì để ngoại lệ làm chết dịch vụ.
• Công cụ có tác dụng ghi hoặc xóa phải nói rõ trong mô tả, và nên có bước xác nhận. Trợ lý gọi nhầm một công cụ xóa là mất dữ liệu thật.

Từ máy cá nhân lên máy chủ cho cả đội

Điểm quan trọng nhất khi lên máy chủ dùng chung: dịch vụ này thường có quyền đọc dữ liệu thật của công ty. Mở nó ra internet mà không có lớp xác thực là mở cửa kho dữ liệu. Đặt sau mạng riêng, hoặc sau một lớp xác thực, là việc bắt buộc chứ không phải tùy chọn.

Câu hỏi thường gặp

Viết MCP server bằng TypeScript có được không?

Được, SDK TypeScript chính thức song hành với Python, khái niệm y hệt (tool = hàm + mô tả). Chọn ngôn ngữ đội bạn quen; Python thường ngắn hơn cho server tra cứu dữ liệu.

MCP server tự viết có dùng được với các AI khác ngoài Claude không?

Được, MCP là chuẩn mở, các client hỗ trợ ngày càng nhiều (những công cụ như Codex CLI, và các nền tảng đã có bài trên blog). Viết một lần, client nào nói chuẩn MCP đều gọi được.

Tool bị AI gọi sai tham số liên tục thì sửa gì?

Sửa docstring và type hint, đó là 'tài liệu' duy nhất model đọc: mô tả rõ tham số nhận gì, ví dụ giá trị hợp lệ, đổi tên tham số cho tự mô tả. Inspector (mcp dev) giúp thấy model đang truyền gì.

Server đọc dữ liệu nhạy cảm, lỡ AI bị dụ (prompt injection) thì sao?

Nguyên tắc phòng thủ: tool chỉ-đọc với dữ liệu đã cân nhắc phơi, không nhét secret vào kết quả trả về, server sống trong tailnet, và tool ghi (nếu có) yêu cầu xác nhận người thật. Quyền của AI = quyền của tool bạn phơi, phơi ít, ngủ ngon.

Bài viết liên quan

• MCP là gì? Chuẩn cắm công cụ cho AI agent, nói dễ hiểu
• MCP server tự host trên VPS: cấu hình và độ trễ thực tế
• Claude Code là gì? AI viết code trong terminal thay bạn