MCP server là gì? Tự viết MCP server đầu tiên bằng Python

Nếu bạn đã dùng ChatGPT, Claude hay Gemini một thời gian, chắc bạn từng gặp cảnh này: hỏi AI về một file trên máy, về dữ liệu trong hệ thống của công ty, hay nhờ nó tạo một công việc trên phần mềm quản lý dự án, và câu trả lời là "tôi không truy cập được". AI biết rất nhiều, nhưng lại bị tách khỏi chính những nơi chứa dữ liệu và công cụ bạn dùng hằng ngày.

MCP (Model Context Protocol) ra đời để nối hai thế giới đó lại. Bài viết này giải thích MCP là gì, MCP server làm việc như thế nào, và cuối bài bạn sẽ tự viết được một MCP server nhỏ bằng Python chỉ với vài chục dòng code.

MCP là gì?

MCP là một giao thức mở, do Anthropic (công ty phát triển Claude) công bố cuối năm 2024. Giao thức này quy định một cách chung để ứng dụng AI kết nối với nguồn dữ liệu và công cụ bên ngoài.

Cách hình dung dễ nhất là cổng USB-C. Trước đây mỗi thiết bị một loại sạc, mỗi hãng một kiểu cổng. Khi có chuẩn chung, một sợi cáp cắm được vào laptop, điện thoại, màn hình. MCP làm điều tương tự cho AI: thay vì mỗi ứng dụng AI phải viết riêng một bộ kết nối cho Google Drive, GitHub, Slack hay cơ sở dữ liệu, chỉ cần viết một MCP server cho mỗi hệ thống, và mọi ứng dụng AI hỗ trợ MCP đều dùng được.

Đến nay MCP đã được nhiều ứng dụng hỗ trợ, từ Claude, ChatGPT đến các trình soạn code như VS Code hay Cursor. Vì vậy một MCP server bạn viết hôm nay có thể dùng ngay trên nhiều công cụ khác nhau.

Ba vai trong một kết nối MCP

Một kết nối MCP có ba thành phần:

• Host: ứng dụng AI mà người dùng làm việc trực tiếp, ví dụ Claude Desktop hay VS Code.

• Client: phần nằm bên trong host, giữ kết nối với từng server và chuyển yêu cầu qua lại.

• Server: chương trình nhỏ đứng giữa AI và một hệ thống cụ thể (file trên máy, cơ sở dữ liệu, một API). Server cho AI biết nó làm được những gì và thực hiện công việc khi được gọi.

Khi bạn hỏi AI một câu cần đến dữ liệu bên ngoài, host sẽ xem các server đang kết nối có công cụ nào phù hợp, mô hình AI quyết định gọi công cụ đó, server thực hiện rồi trả kết quả về để AI viết câu trả lời cho bạn.

MCP server cung cấp những gì?

Một MCP server có thể cung cấp ba loại năng lực:

Trong thực tế, tools là phần được dùng nhiều nhất, vì đó là thứ biến AI từ chỗ chỉ biết trả lời thành chỗ làm được việc.

Server giao tiếp với AI bằng cách nào?

MCP hỗ trợ hai cách truyền dữ liệu chính:

• stdio: host chạy server như một chương trình con trên cùng máy và trao đổi qua đầu vào, đầu ra chuẩn. Cách này đơn giản, phù hợp với server chạy cục bộ, đọc file trên máy bạn.

• Streamable HTTP: server chạy như một dịch vụ web, có thể đặt trên máy chủ từ xa để nhiều người cùng kết nối. Các connector bạn thấy trong Claude hay ChatGPT thường thuộc loại này.

Khi mới học, bạn nên bắt đầu với stdio vì không cần cấu hình mạng gì cả.

Thực hành: viết MCP server đầu tiên bằng Python

Chúng ta sẽ viết một server quản lý sổ ghi chú đơn giản. AI sẽ thêm được ghi chú mới và đọc lại các ghi chú đã lưu.

Bước 1: Cài thư viện

MCP có bộ thư viện chính thức cho Python. Bạn cần Python 3.10 trở lên, sau đó cài bằng pip:

pip install "mcp[cli]"

Bước 2: Viết server

Tạo file server.py với nội dung sau:

from pathlib import Path
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("notes")
NOTES_FILE = Path(__file__).parent / "notes.txt"


@mcp.tool()
def add_note(text: str) -> str:
    """Thêm một ghi chú mới vào sổ."""
    with NOTES_FILE.open("a", encoding="utf-8") as f:
        f.write(text + "\n")
    return "Đã lưu ghi chú."


@mcp.tool()
def list_notes() -> list[str]:
    """Trả về danh sách tất cả ghi chú đang có."""
    if not NOTES_FILE.exists():
        return []
    return NOTES_FILE.read_text(encoding="utf-8").splitlines()


@mcp.resource("notes://all")
def all_notes() -> str:
    """Toàn bộ sổ ghi chú dưới dạng văn bản."""
    if not NOTES_FILE.exists():
        return ""
    return NOTES_FILE.read_text(encoding="utf-8")


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

Có vài điểm đáng chú ý trong đoạn code trên:

• FastMCP lo hết phần giao thức phía sau, bạn chỉ cần viết hàm Python bình thường.

• Decorator @mcp.tool() biến một hàm thành công cụ cho AI gọi. @mcp.resource() biến một hàm thành tài nguyên để AI đọc.

• Gợi ý kiểu (type hint) và docstring rất quan trọng. Thư viện dùng chúng để mô tả công cụ cho AI: công cụ này làm gì, cần tham số gì, kiểu dữ liệu ra sao. Docstring viết càng rõ, AI càng biết khi nào nên gọi công cụ nào.

Bước 3: Chạy thử với MCP Inspector

Trước khi gắn vào ứng dụng AI, bạn nên kiểm tra server bằng MCP Inspector, một công cụ có giao diện web để gọi thử từng tool:

mcp dev server.py

Lệnh này mở Inspector trên trình duyệt. Bạn chọn tool add_note, nhập nội dung, bấm chạy và xem kết quả trả về. Cách này giúp tìm lỗi nhanh hơn nhiều so với thử trực tiếp qua AI.

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

Mở file cấu hình của Claude Desktop (trong ứng dụng, vào Settings, chọn mục Developer rồi Edit Config) và thêm đoạn sau:

{
  "mcpServers": {
    "notes": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

Thay /path/to/server.py bằng đường dẫn đầy đủ tới file của bạn, lưu lại rồi khởi động lại Claude Desktop. Giờ bạn có thể nói "Ghi lại giúp mình: thứ Sáu nộp bài tập Python", rồi lát sau hỏi "Mình có những ghi chú nào?". Claude sẽ tự gọi đúng công cụ trong server bạn vừa viết.

Các ứng dụng khác như VS Code hay Cursor cũng có file cấu hình tương tự, chỉ khác vị trí đặt file.

Những lỗi người mới hay gặp

• Dùng print() trong server chạy bằng stdio. Với stdio, đầu ra chuẩn là kênh trao đổi dữ liệu giữa server và host. Một lệnh print() lạc vào đó sẽ làm hỏng kết nối. Muốn ghi log thì dùng module logging và ghi ra stderr hoặc ra file.

• Dùng đường dẫn tương đối trong file cấu hình. Host có thể chạy server từ một thư mục khác, nên hãy dùng đường dẫn đầy đủ.

• Docstring sơ sài. Viết """Hàm 1.""" thì AI không biết công cụ dùng để làm gì và sẽ bỏ qua nó.

• Quên khởi động lại ứng dụng sau khi sửa file cấu hình hoặc sửa code server.

Đừng quên chuyện an toàn

MCP server có quyền làm những việc thật: đọc file, ghi dữ liệu, gọi API. Vì vậy:

• Chỉ cài MCP server từ nguồn bạn tin tưởng, và nên đọc qua code nếu có thể.

• Cấp quyền ở mức tối thiểu. Server chỉ cần đọc một thư mục thì đừng cho nó quyền truy cập cả ổ đĩa.

• Cẩn thận với các công cụ có thể xóa hoặc gửi dữ liệu ra ngoài. Hầu hết ứng dụng AI đều hỏi xác nhận trước khi gọi tool, bạn nên đọc kỹ trước khi đồng ý.

• Nội dung AI đọc được từ web hay email có thể chứa câu lệnh cài cắm nhằm điều khiển AI. Server càng nhiều quyền thì rủi ro này càng lớn.

Tóm lại

MCP là chuẩn chung giúp AI kết nối với dữ liệu và công cụ bên ngoài. MCP server là chương trình đứng giữa, cho AI biết nó được phép làm gì và thực hiện công việc khi được gọi. Với Python và thư viện mcp, viết một server chỉ đơn giản là viết hàm, thêm decorator và một docstring rõ ràng.

Nếu bạn đã nắm được hàm, kiểu dữ liệu và làm việc với file trong Python, bạn hoàn toàn có thể bắt tay vào làm ngay. Hãy thử mở rộng ví dụ trên: thêm công cụ xóa ghi chú, tìm ghi chú theo từ khóa, hoặc thay file văn bản bằng cơ sở dữ liệu SQLite. Đó cũng là cách tốt để luyện Python qua một dự án có ích thật sự.

Tài liệu chính thức để tìm hiểu sâu hơn: https://modelcontextprotocol.io