FastMCP: khung Python dựng máy chủ MCP và kịch bản thí điểm cho sở cấp tỉnh
Đăng ngày 12/10/2026
Mục lục bài nghiên cứu
FastMCP trong một trang: khung Python biến hàm nghiệp vụ thành công cụ cho AI
FastMCP là khung (framework) Python để dựng máy chủ và máy khách theo Model Context Protocol (MCP, giao thức chuẩn để mô hình ngôn ngữ gọi công cụ và đọc dữ liệu bên ngoài). README mô tả nó là khung ứng dụng MCP đầy đủ với ba trụ cột: Servers để mở công cụ, tài nguyên và prompt cho mô hình; Clients để kết nối tới máy chủ MCP; và Apps để gắn giao diện tương tác vào kết quả công cụ. [1]
Khác với dự án cung cấp sẵn công cụ, FastMCP là vật liệu xây dựng: giá trị của nó phụ thuộc vào đội kỹ thuật sẽ viết hàm nghiệp vụ nào, bảo vệ chúng ra sao.
Khuyến nghị: nếu đơn vị đã có đội Python và muốn bộc lộ vài chức năng tra cứu nội bộ cho trợ lý AI, FastMCP đáng đưa vào thử nghiệm quy mô nhỏ, chỉ đọc, sau lớp xác thực. Nếu chưa có người lập trình hoặc chưa có nhà cung cấp danh tính nội bộ, hãy làm hai việc đó trước. Đây là đánh giá từ tài liệu, chưa kiểm chứng bằng cách chạy.
Vì sao cần một khung viết máy chủ MCP thay vì tự nối từng API
Giao thức MCP đòi hỏi nhiều chi tiết ngoài logic nghiệp vụ: công bố danh sách công cụ cùng lược đồ tham số, xác thực đầu vào, thương lượng phương thức truyền tải, quản lý vòng đời kết nối và xử lý lỗi. README mô tả cách FastMCP rút gọn việc này: khai báo công cụ bằng hàm Python thì lược đồ, kiểm tra hợp lệ và tài liệu được sinh tự động. [1]
Lý do thứ hai là chuẩn hóa. Khi nhiều phòng ban cùng muốn bộc lộ dữ liệu cho trợ lý AI, mỗi nơi tự viết một cầu nối riêng sẽ cho ra những cách xác thực và ghi nhật ký khác nhau. Một khung chung cho phép đặt cùng một lớp xác thực, middleware và quy ước đặt tên lên tất cả công cụ. Tài liệu cấu hình máy chủ nêu rõ middleware chặn mọi thông điệp MCP và thích hợp cho các việc cắt ngang như ghi nhật ký, xử lý lỗi, giới hạn tốc độ. [6]
Tuy nhiên, khung không giải quyết hộ câu hỏi quản trị. Hàm nào được phép bộc lộ, dữ liệu nào được trả về, ai được gọi, tất cả vẫn là quyết định của đơn vị. Số liệu về mức độ phổ biến trong README, như lượng tải hằng ngày, là tuyên bố của dự án và không được bài này dùng làm bằng chứng chất lượng. [1]
Bên trong FastMCP: máy chủ, thành phần, provider và transform
Lớp trung tâm là FastMCP, được tài liệu mô tả là bình chứa các tool, resource và prompt, đồng thời quản lý giao tiếp với máy khách. Tool là hàm mà máy khách gọi để thực hiện hành động; resource là nguồn dữ liệu đọc thụ động; prompt là mẫu thông điệp dùng lại. [6] Hàm tạo máy chủ nhận các tham số về danh tính, thành phần (tools, auth, middleware, providers, transforms, lifespan) và hành vi như kiểm tra đầu vào, che chi tiết lỗi, phân trang danh sách. [6]
Từ phiên bản 3 trở đi, kiến trúc xoay quanh provider, tức nguồn cung cấp thành phần được truy vấn lúc có yêu cầu. Ghi chú thiết kế cho biết lớp MountedProvider cũ bị tách thành FastMCPProvider, bọc một máy chủ FastMCP, và TransformingProvider, áp tiền tố không gian tên hoặc đổi tên công cụ; mount() hiện dùng hai lớp này bên trong. [4] Tài liệu ghép máy chủ giải thích cách lắp nhiều máy chủ nhỏ như thời tiết, lịch, quản trị vào một máy chủ cha, kể cả gắn máy chủ từ xa bằng create_proxy. [10]
Tầng Apps có đường ống riêng: thành phần Prefab bằng Python được tuần tự hóa thành cây JSON, trả về dưới dạng structuredContent rồi một bộ dựng giao diện trong iframe có sandbox hiển thị trong ứng dụng chủ. [5]
Dòng chảy dữ liệu: khai báo hàm, sinh lược đồ, gọi qua HTTP, kiểm tra quyền
Bắt đầu từ mã. Lập trình viên viết hàm Python với kiểu tham số rõ ràng và docstring, gắn decorator @mcp.tool. FastMCP sinh lược đồ đầu vào từ chữ ký hàm. [1] Theo mặc định, tài liệu cho biết kiểm tra đầu vào dùng cách nới của Pydantic và có thể ép kiểu, ví dụ chuỗi "10" thành số nguyên 10; đặt strict_input_validation thành True thì từ chối sai kiểu theo đúng lược đồ JSON. [6]
Khi máy chủ chạy qua HTTP, yêu cầu của máy khách đi vào endpoint mặc định /mcp. Nếu đã cấu hình nhà cung cấp xác thực, yêu cầu không mang token hợp lệ bị từ chối ở tầng truyền tải trước mọi kiểm tra quyền; sau đó các hàm kiểm tra quyền mới phân biệt người dùng theo phạm vi quyền (scope) và claim trong token. [7][9] Tài liệu còn nói nếu bật mask_error_details thì chi tiết lỗi nội bộ được thay bằng thông báo chung. [6]
Với triển khai sau cổng chuyển tiếp, tài liệu HTTP mô tả các tiêu đề định tuyến Mcp-Method, Mcp-Name và Mcp-Param-* chỉ có trên kết nối đã thương lượng giao thức 2026-07-28, và dặn coi chúng là gợi ý không đáng tin vì máy chủ vẫn phải kiểm tra thân yêu cầu. [7]
Đã xác minh trong tài liệu ở commit cố định
Về lõi máy chủ, các điểm đã đọc được gồm: ba loại thành phần tool, resource, prompt; truyền tải STDIO là mặc định, HTTP dùng giao thức Streamable HTTP, còn SSE được gọi là cũ và không còn khuyến khích; tùy chọn lọc theo thẻ (tag) để tạo các góc nhìn khác nhau cho từng môi trường hoặc nhóm người dùng. [6]
Về xác thực và phân quyền: lớp TokenVerifier và JWTVerifier kiểm tra token do hệ thống khác cấp; RemoteAuthProvider dành cho nhà cung cấp danh tính hỗ trợ đăng ký máy khách động; OAuthProxy làm cầu cho nhà cung cấp không hỗ trợ, với ví dụ GitHub, Google, Azure; còn triển khai OAuth đầy đủ được khuyên dùng khi cần kiểm soát hoàn toàn hoặc môi trường cách ly. [8] Hàm kiểm tra quyền kết hợp theo logic AND, có sẵn require_scopes, require_roles (từ 4.0.0) và restrict_tag. [9]
Về ghép nối: mount() gắn máy chủ con vào máy chủ cha, có thể kèm không gian tên, và create_proxy gắn máy chủ từ xa hoặc tiến trình con. [10] Về triển khai: chạy trực tiếp bằng run(transport="http") hoặc tạo ứng dụng ASGI bằng http_app() để chạy dưới Uvicorn với nhiều worker. [7] README còn đề cập một bản TypeScript riêng và dịch vụ thương mại Prefect Horizon, sẽ bàn ở phần giấy phép. [1]
Đơn vị nào hợp với một khung lập trình, đơn vị nào không
FastMCP phù hợp với đội có kỹ năng Python, vì mọi thứ được viết bằng mã. Ví dụ điển hình trong tài liệu là các hàm nhỏ trả về số liệu hoặc nội dung; việc gắn chúng với hệ thống thật như cơ sở dữ liệu, dịch vụ tra cứu, kho văn bản do đội phát triển tự thực hiện. [6] Đội có sẵn dịch vụ Python hoặc API nội bộ sẽ thấy việc bọc lại thành công cụ MCP tương đối tự nhiên.
Đối tượng thứ hai là đơn vị muốn quản trị tập trung nhiều công cụ. Cơ chế ghép máy chủ, không gian tên và lọc theo thẻ cho phép chia theo phòng ban rồi gộp thành một điểm truy cập. [6][10] Nếu nhu cầu lớn hơn, README giới thiệu Prefect Horizon như cổng MCP doanh nghiệp, nhưng đó là sản phẩm thương mại của cùng nhóm phát triển, không nằm trong phạm vi bài này. [1]
Đơn vị không nên chọn hướng này gồm những nơi không có lập trình viên, nơi muốn công cụ cắm-và-chạy không cần viết mã, và nơi dữ liệu quá nhạy cảm để cho trợ lý AI chạm vào dù có kiểm soát.
Đề xuất: thí điểm nội bộ tại một sở cấp tỉnh với ba công cụ tra cứu chỉ đọc
Tình huống sau là đề xuất giả định, không phải dự án đã diễn ra. Một sở cấp tỉnh muốn thử xem cán bộ có làm việc nhanh hơn không nếu trợ lý AI tra cứu giúp. Dự án chỉ chạy nội bộ, giới hạn trong một phòng chuyên môn, không mở cho người dân hay doanh nghiệp, và có tên rõ ràng là thí điểm.
Ba công cụ đề xuất đều chỉ đọc. Công cụ thứ nhất tra cứu văn bản đã ban hành trong kho văn bản nội bộ theo từ khóa. Công cụ thứ hai trả về trạng thái xử lý của một mã hồ sơ, chỉ khi hồ sơ thuộc phòng của người gọi. Công cụ thứ ba trả về danh mục thủ tục và biểu mẫu đã công bố. Không có công cụ tạo, sửa, xóa hay gửi. Cán bộ dùng trợ lý qua ứng dụng chủ đã được sở phê duyệt; máy chủ chạy trong mạng nội bộ.
Về quyền, đề xuất dùng JWTVerifier kiểm tra token do hệ thống đăng nhập một lần của sở cấp, và require_roles để chỉ vai trò phòng chuyên môn mới gọi công cụ hồ sơ; tài liệu có ví dụ trích vai trò từ token Keycloak và nhắc phải tự kiểm tra tên claim trên hệ thống thực. [8][9] Các công cụ gắn thẻ riêng để tắt nhanh khi cần. [6] Việc bộc lộ dữ liệu hồ sơ cho dịch vụ mô hình bên ngoài phải qua thẩm định an toàn thông tin của sở và quy định hiện hành về dữ liệu nhà nước; bài này không thay thế bước đó và không nêu số hiệu văn bản cụ thể.
Triển khai: từ python server.py tới ứng dụng ASGI sau cổng nội bộ
Tài liệu HTTP mô tả hai đường. Đường đơn giản là gọi run với transport http, host và port, chạy bằng lệnh python, phù hợp công cụ nội bộ hoặc môi trường phát triển. Đường dành cho sản xuất là tạo ứng dụng ASGI bằng http_app() rồi chạy dưới Uvicorn, Gunicorn hoặc Hypercorn, nhờ đó có nhiều worker, middleware riêng và hòa nhập vào quy trình triển khai sẵn có. [7] Endpoint mặc định là /mcp và có thể đổi đường dẫn.
Với thí điểm, đề xuất chạy ASGI trong một container hoặc máy ảo ở mạng nội bộ, đặt sau cổng chuyển tiếp của sở. Bật host_origin_protection và khai báo allowed_hosts; tài liệu nói mặc định là tắt, tức không có kiểm tra Host và Origin hay chống DNS rebinding. [7] Thêm một endpoint health bằng custom_route để giám sát, nhưng cần nhớ tài liệu ghi rõ route tùy chỉnh không đi qua middleware xác thực. [7]
Về quan sát, nên dùng middleware ghi nhật ký mỗi lần gọi công cụ cùng mã người dùng, tên công cụ, thời điểm và kết quả thành công hay thất bại, nhưng không ghi nội dung hồ sơ. Kho trạng thái phiên mặc định trong bộ nhớ; nếu chạy nhiều bản sao cần xem lại ảnh hưởng. [6]
An ninh: auth=None mặc định, OAuth, vai trò và những thứ không phải ranh giới
Điều quan trọng nhất tài liệu xác thực nói là máy chủ FastMCP mặc định có auth=None; với truyền tải HTTP, endpoint nhận yêu cầu mà không cần token, và những thành phần không có kiểm tra quyền thì ai truy cập được endpoint đều dùng được. [8] Cũng theo tài liệu, xác thực chỉ áp dụng cho HTTP và SSE; với STDIO, an ninh dựa vào môi trường chạy cục bộ và các kiểm tra quyền của thành phần bị bỏ qua. [8][9] Hệ quả cho thí điểm: nếu chạy HTTP thì phải cấu hình nhà cung cấp xác thực, và nếu chọn xác thực ở cổng chuyển tiếp thì trách nhiệm bảo vệ thuộc về cổng đó.
SECURITY.md bổ sung hai điểm. Thứ nhất, tính năng visibility của MCP Apps chỉ khai báo đối tượng dự kiến và không phải ranh giới bảo mật; gọi trực tiếp công cụ vẫn phải qua xác thực và phân quyền. Thứ hai, tắt require_authorization_consent hoặc đặt "external" làm mất các bảo vệ chống tấn công confused deputy của OAuth proxy, và FastMCP không kiểm tra việc thực thi bên ngoài. [3] Báo lỗ hổng bằng tính năng advisory riêng tư của GitHub, không dùng issue công khai. [3]
Ngoài ra có rủi ro mà khung không xử lý hộ: nội dung do công cụ trả về đi vào ngữ cảnh của mô hình, nên tài liệu nhạy cảm hoặc chứa chỉ dẫn độc hại có thể ảnh hưởng hành vi trợ lý.
Apache-2.0 cho mã trong kho; Prefect Horizon là sản phẩm khác
Tệp LICENSE tại commit nghiên cứu là văn bản Apache License 2.0 chuẩn, kèm phụ lục hướng dẫn áp dụng giấy phép với chỗ trống bản quyền chưa điền; README cũng gắn huy hiệu giấy phép theo tệp này. [1][2] Apache-2.0 cho phép sử dụng, sao chép, sửa đổi và phân phối, kể cả thương mại, kèm điều khoản cấp quyền sáng chế và yêu cầu giữ thông báo khi phân phối lại. [2]
Giấy phép chỉ phủ mã trong kho này tại commit đã chọn. Nó không phủ các phụ thuộc như SDK MCP và thư viện Pydantic, mỗi thứ có giấy phép riêng; không phủ mô hình ngôn ngữ, nhà cung cấp danh tính bên ngoài, hay dữ liệu của đơn vị. Bản TypeScript là kho khác với phát hành riêng, và README nói rõ nó do cùng nhóm duy trì nhưng nằm ngoài phạm vi kiểm tra của bài. [1]
Cần tách bạch dự án mã nguồn mở với dịch vụ thương mại. README giới thiệu Prefect Horizon là cổng MCP doanh nghiệp của cùng đội phát triển, với các năng lực như triển khai từ GitHub, sổ đăng ký riêng, SSO, RBAC cấp công cụ, nhật ký kiểm toán. [1] Đó là mô tả sản phẩm, không phải thứ có trong giấy phép Apache-2.0 của kho này; các điều khoản và giá của Horizon chưa được đọc và nằm ngoài kết luận.
Chi phí: lập trình viên, máy chủ nhỏ và thời gian bảo trì
Giấy phép không thu phí, nhưng chi phí chủ yếu là nhân lực. Cần ít nhất một lập trình viên Python hiểu HTTP và xác thực để viết ba công cụ, kiểm thử và cấu hình bảo vệ; một cán bộ an toàn thông tin để rà soát; một cán bộ nghiệp vụ để xác nhận kết quả tra cứu đúng.
Hạ tầng thuộc loại nhỏ: một máy ảo hoặc container chạy ứng dụng ASGI, một môi trường kiểm thử, kết nối tới hệ thống danh tính và kho văn bản nội bộ. [7] Nếu dùng nhiều worker để chịu tải, tài nguyên tăng theo số worker. Chi phí gọi mô hình do ứng dụng chủ và nhà cung cấp mô hình quyết định, nằm ngoài FastMCP; cần hỏi rõ trước khi thí điểm. Thời gian cán bộ đọc lại kết quả cũng là chi phí thật.
Chi phí tiềm ẩn nằm ở vòng đời: nâng cấp giữa các bản chính, theo dõi thay đổi giao thức MCP, vá lỗi phụ thuộc. [1][3]
Đặt cạnh các hướng đi khác: SDK chính thức, máy chủ có sẵn, tích hợp không mã
Hướng thứ nhất là dùng trực tiếp SDK MCP cấp thấp. README nói FastMCP 1.0 từng được đưa vào SDK Python chính thức năm 2024 và dự án độc lập hiện vẫn được duy trì riêng; hướng dẫn nâng cấp từ SDK cấp thấp cũng được liệt kê. [1] Dùng SDK cho kiểm soát chi tiết nhất nhưng đội phải tự viết nhiều phần lặp lại.
Hướng thứ hai là dùng máy chủ MCP dựng sẵn cho từng hệ thống, nếu nhà cung cấp hệ thống đó có. Cách này nhanh, nhưng công cụ và quyền do nhà cung cấp quyết định, khó tùy biến theo quy tắc nội bộ. FastMCP có thể ghép chúng bằng create_proxy rồi đặt chung một lớp xác thực và không gian tên. [10]
Hướng thứ ba là tích hợp không mã hoặc ít mã, ví dụ công cụ luồng công việc trực quan, để nối hệ thống mà không cần lập trình viên. Hướng này phù hợp tác vụ cố định, nhưng khả năng đáp ứng giao thức MCP và phân quyền theo từng công cụ tùy sản phẩm cụ thể, chưa được xét trong bài.
Hạn chế và điều kiện không nên dùng
Hạn chế đầu tiên là yêu cầu mã. FastMCP không phải sản phẩm dùng ngay: không có công cụ nghiệp vụ nào đi kèm cho cơ quan hành chính, và mọi chức năng đều do đội địa phương viết, kiểm thử, bảo trì. [6] Hạn chế thứ hai là các mặc định chưa bảo vệ: auth=None, host_origin_protection tắt, route tùy chỉnh không qua xác thực. [7][8] Người triển khai phải chủ động bật từng lớp.
Hạn chế thứ ba là biến động. Dự án đã có thay đổi phá vỡ giữa các bản chính, SECURITY.md chỉ hỗ trợ 4.x và 3.x, và tài liệu xác thực tự cảnh báo rằng xác thực trong MCP đang thay đổi nhanh. [3][4][8] Cố định phiên bản và có kế hoạch nâng cấp là điều bắt buộc.
Nên dừng hoặc không bắt đầu khi: không có nhà cung cấp danh tính để xác thực người gọi; công cụ cần ghi hoặc xóa dữ liệu hồ sơ trong giai đoạn đầu; không thể xác nhận nơi nội dung công cụ được gửi đến sau khi vào ngữ cảnh mô hình; hoặc cán bộ dùng kết quả của trợ lý làm căn cứ ra quyết định hành chính mà không đối chiếu nguồn.
Kế hoạch thí điểm tám tuần cho một phòng chuyên môn
Giai đoạn một, tuần một đến hai: chuẩn bị. Chốt danh sách dữ liệu được phép, xác định hệ thống danh tính, viết ba công cụ chỉ đọc trên dữ liệu thử đã loại thông tin cá nhân, cố định phiên bản FastMCP, bật xác thực, host_origin_protection và ghi nhật ký. Chỉ số nền cần đo: thời gian trung bình một cán bộ tra cứu thủ công cho từng loại việc, ghi bằng đồng hồ trong hai ngày.
Giai đoạn hai, tuần ba đến sáu: dùng thử với năm cán bộ tự nguyện. Mỗi lượt tra cứu được ghi lại. Tiêu chí đề xuất: ít nhất chín trên mười kết quả tra cứu đúng khi cán bộ kiểm tra đối chiếu nguồn; không có lượt gọi nào vượt phạm vi phòng; không có lần gọi thành công khi thiếu token trong bài kiểm thử xâm nhập nhỏ do bộ phận an toàn thông tin thực hiện; thời gian tra cứu trung bình giảm so với chỉ số nền. Các ngưỡng này là giả định để điều chỉnh, không rút ra từ nguồn.
Giai đoạn ba, tuần bảy đến tám: đánh giá và quyết định. Họp rà soát nhật ký, các ca sai, phản hồi của cán bộ và chi phí nhân lực. Tiêu chí thoát tích cực: đạt các ngưỡng trên và có kế hoạch bảo trì. Tiêu chí dừng: có truy cập trái phép, rò rỉ dữ liệu ngoài phạm vi, hoặc tỷ lệ sai vượt ngưỡng hai tuần liên tiếp. Nếu dừng, gỡ máy chủ, thu hồi khóa, lưu báo cáo bài học.
Kết luận: công cụ xây dựng tốt, nhưng an toàn nằm ở phần bạn tự viết
FastMCP là khung Apache-2.0 để dựng máy chủ, máy khách và giao diện MCP bằng Python, với tài liệu khá chi tiết về triển khai HTTP, xác thực, phân quyền và ghép nối. [1][2][7][8][9] Điểm mạnh là rút ngắn việc dựng hạ tầng giao thức; điểm cần cẩn trọng là các mặc định chưa bảo vệ và nhịp thay đổi phiên bản.
Với một sở cấp tỉnh, hướng đi hợp lý nhất là thí điểm nội bộ nhỏ: ba công cụ chỉ đọc, xác thực qua hệ thống danh tính của sở, phân quyền theo vai trò, theo dõi nhật ký và có điều kiện dừng rõ ràng. Đề xuất này chưa được chạy thử, mọi ngưỡng đo là giả định để đơn vị điều chỉnh.
Nếu người đọc xây hệ tri thức riêng như phamvanthu.com, nguyên tắc tương tự áp dụng: chỉ bộc lộ phần tri thức đã chọn lọc, chỉ đọc, có xác thực. Bài không khẳng định BDSG đang dùng FastMCP.
Nguồn, commit và cách nghiên cứu
FastMCP được chọn từ kho lưu độc lập các danh sách GitHub Trending theo ngôn ngữ: có hai lần quan sát, lần đầu ngày 22/04/2026 ở danh sách Python, vị trí 9, lần cuối ngày 21/07/2026. [11] Kho lưu chỉ bao phủ Python, Go, JavaScript và Swift, thiếu dữ liệu ngày 03/09 và 12/10, nên đây không phải bảng xếp hạng Top 100 chính thức hay thống kê đầy đủ của GitHub.
Bài đọc README, LICENSE, SECURITY.md, hai tài liệu kiến trúc (ghi chú nhà cung cấp phiên bản 3 và kiến trúc Apps) cùng năm tài liệu bổ sung về máy chủ, triển khai HTTP, xác thực, phân quyền và ghép máy chủ, tại commit e2fcc412001ff7414095c5dc282f94c70299a612, ngày commit 09/10/2026, kiểm tra ngày 12/10/2026. [1][2][3][4][5][6][7][8][9][10] Bản phát hành v4.1.0 lấy từ siêu dữ liệu GitHub API. Tài liệu trong kho có thể mô tả tính năng mới hơn bản đang cài, nên cần chọn bản phát hành cụ thể và kiểm tra lại.
Đây là nghiên cứu tài liệu có hỗ trợ AI, chưa phải thử nghiệm triển khai, đo hiệu năng hay bài báo khoa học được phản biện. Tình huống sở cấp tỉnh, chi phí, tiêu chí và khuyến nghị là phân tích đề xuất của người viết.
Xem mã nguồn FastMCP trên GitHub