Danh sách Kiểm tra Tích hợp MCP Server

TL;DR

Một máy chủ Model Context Protocol (MCP server) chỉ phát huy hiệu quả khi các agent có thể tiếp nhận và sử dụng nó một cách tự chủ. Cần áp dụng danh sách kiểm tra 40 điểm dưới đây trước khi phát hành: đặt tên công cụ (tool) dưới dạng động từ mệnh lệnh, cung cấp JSON Schema nghiêm ngặt cho dữ liệu đầu vào (input) và đầu ra (output), đính kèm một ví dụ khả thi cho mỗi công cụ, bảo mật máy chủ bằng OAuth 2.1, cung cấp một môi trường hộp cát (sandbox), lập tài liệu cho các giới hạn tốc độ (rate limit) và tính lũy đẳng (idempotency), đồng thời khai báo các chú thích an toàn (safety annotation) đối với các hành động mang tính phá hủy. Đặc tả Model Context Protocol (modelcontextprotocol.io) là nguồn chân lý; trong khi đó, danh sách kiểm tra này đóng vai trò là cửa ngõ vận hành.

Cách sử dụng danh sách kiểm tra này

Cần tiến hành qua bảy giai đoạn theo trình tự trước khi chuyển máy chủ MCP sang trạng thái sẵn sàng phát hành rộng rãi (general availability). Tính 1 điểm cho mỗi tiêu chí được đáp ứng. Tổng số điểm tuyệt đối là 40.

Danh sách kiểm tra này giả định rằng giao thức cơ sở MCP (phương thức truyền tải JSON-RPC 2.0, đàm phán khả năng, các nguyên hàm công cụ / tài nguyên / lời nhắc) đã được triển khai tuân thủ nghiêm ngặt Đặc tả Model Context Protocol.

Giai đoạn 1: Nhận dạng và khám phá (5 điểm)

• [ ] Máy chủ sở hữu một định danh ổn định, thân thiện với người đọc và phiên bản được trả về trong tiến trình initialize.
• [ ] serverInfo.title mô tả tích hợp bằng một câu súc tích.
• [ ] Trường instructions cung cấp định hướng độ dài một đoạn văn cho agent.
• [ ] Tệp README hoặc trang đích công khai cung cấp tài liệu về lệnh cài đặt (install command) và các client được hỗ trợ.
• [ ] Máy chủ công bố một định danh ổn định (URL hoặc tên gói phần mềm) được sử dụng trong các sổ đăng ký của agent client.

Giai đoạn 2: Thiết kế công cụ (8 điểm)

• [ ] Tên các công cụ (tool) là các cụm động từ mang tính mệnh lệnh (create_invoice, thay vì invoice hoặc invoiceTool).
• [ ] Định danh công cụ phải là duy nhất trong phạm vi máy chủ và tuân thủ định dạng snake_case.
• [ ] Mỗi công cụ sở hữu một mô tả súc tích độ dài một câu bằng tiếng Anh rõ ràng, chuẩn mực.
• [ ] Không có công cụ nào đảm nhiệm vượt quá một khả năng logic duy nhất — cần phân tách các công cụ đa chức năng (umbrella tool).
• [ ] Các công cụ có chức năng thay đổi trạng thái (mutate state) phải được định danh rõ ràng (create_*, update_*, delete_*).
• [ ] Các công cụ chuyên dụng cho việc đọc dữ liệu (read) được định danh với tiền tố get_*, list_*, hoặc search_*.
• [ ] Tổng số công cụ trên mỗi máy chủ nên được giới hạn ở mức tối đa ~30 (vượt quá ngưỡng này, các agent sẽ suy giảm độ chính xác trong việc lựa chọn).
• [ ] Các công cụ đã bị ngừng hỗ trợ (deprecated) được chú thích với deprecated: true và bắt buộc duy trì hoạt động trong ít nhất một phiên bản minor tiếp theo.

Giai đoạn 3: Schemas và các giao kèo (7 điểm)

• [ ] Mỗi công cụ đều tích hợp một inputSchema hoàn chỉnh (tuân thủ JSON Schema draft 2020-12).
• [ ] Mỗi công cụ đều cung cấp một outputSchema mô tả dữ liệu trả về có cấu trúc.
• [ ] Các trường dữ liệu bắt buộc (required field) được khai báo rõ ràng; các trường tùy chọn (optional) phải được lập tài liệu về hành vi mặc định.
• [ ] Kiểu dữ liệu Enum (liệt kê) được áp dụng cho bất kỳ trường nào có tập hợp giá trị hữu hạn.
• [ ] Các lược đồ (schema) vượt qua quá trình xác thực dựa trên một trình xác thực JSON Schema tiêu chuẩn một cách liền mạch.
• [ ] Mô tả trường dữ liệu cần cung cấp ngữ cảnh lý do (tại sao) thay vì chỉ đơn thuần là định nghĩa (cái gì) ("customer_id: ID khách hàng để lập hóa đơn; khách hàng phải tồn tại trên hệ thống").
• [ ] Mọi thay đổi về lược đồ mà không đảm bảo tính tương thích ngược (backward-incompatible) bắt buộc phải gia tăng phiên bản máy chủ (semver minor hoặc major).

Giai đoạn 4: Ví dụ và tài liệu (5 điểm)

• [ ] Đính kèm tối thiểu một ví dụ thực tế về lượt gọi cho mỗi công cụ, bao gồm đầy đủ dữ liệu đầu vào (input) và kết quả dự kiến (expected output).
• [ ] Các ví dụ bao gồm ít nhất một tình huống báo lỗi (error case) cho mỗi công cụ (ví dụ: "customer not found").
• [ ] Các luồng công việc đa bước (multi-step workflow) được lập tài liệu thông qua một chuỗi các lệnh gọi công cụ liên tục.
• [ ] Cung cấp tài liệu khởi sự nhanh (quickstart) minh họa quy trình cài đặt → xác thực → lượt gọi đầu tiên với thời gian thực thi ước tính dưới 10 phút.
• [ ] Toàn bộ ví dụ được lưu trữ trong hệ thống quản lý phiên bản (version control) song hiểu với mã nguồn của máy chủ.

Giai đoạn 5: Xác thực và bảo mật (6 điểm)

• [ ] Máy chủ triển khai xác thực OAuth 2.1 theo quy chuẩn của đặc tả ủy quyền MCP (MCP authorization spec).
• [ ] Siêu dữ liệu máy chủ ủy quyền (Authorization Server Metadata) được cung cấp tại /.well-known/oauth-authorization-server (RFC 8414).
• [ ] Hỗ trợ đăng ký client động (dynamic client registration) tuân thủ RFC 7591, hoặc cung cấp tài liệu cho giải pháp thay thế.
• [ ] Cơ chế xoay vòng token làm mới (refresh token rotation) được kích hoạt kết hợp với tính năng phát hiện tái sử dụng.
• [ ] Các chuỗi khai báo phạm vi (scope string) được phân hoạch chi tiết (granular) và được mô tả bằng ngôn ngữ tự nhiên.
• [ ] Điểm cuối thu hồi (revocation endpoint) được phát hành và đã qua quy trình kiểm thử.

Giai đoạn 6: An toàn, giới hạn tốc độ và tính khả quan sát (6 điểm)

• [ ] Các công cụ có tính chất phá hủy (destructive tool) phải được chú thích rõ ràng bằng destructiveHint: true và requiresConfirmation: true.
• [ ] Các công cụ chỉ đọc (read-only tool) được chú thích bằng readOnlyHint: true và idempotent: true.
• [ ] Giới hạn tốc độ (rate limit) được lập tài liệu chi tiết theo từng phạm vi và từng công cụ, kèm theo các tiêu đề Retry-After đối với mã phản hồi 429.
• [ ] Các ngoại lệ trả về đối tượng lỗi JSON-RPC (JSON-RPC error object) với các giá trị mã định danh lỗi ổn định.
• [ ] Nhật ký máy chủ (server log) bao gồm mã định danh của client khởi tạo yêu cầu và tên công cụ (tuyệt đối không ghi nhận vật liệu token).
• [ ] Điểm cuối kiểm tra sức khỏe (health check endpoint) hoặc công cụ ping được thiết lập sẵn phục vụ mục đích giám sát (monitoring).

Giai đoạn 7: Hộp cát (Sandbox) và tung ra (rollout) (3 điểm)

• [ ] Môi trường hộp cát (sandbox) công khai cung cấp dữ liệu được cách ly, cho phép truy cập mà không yêu cầu thanh toán.
• [ ] Hộp cát trả về các lược đồ và mã lỗi tương đồng hoàn toàn với môi trường sản xuất (production).
• [ ] Nhật ký cập nhật (changelog) và chính sách ngừng hỗ trợ (deprecation policy) được công bố với một URL tĩnh.

Ví dụ thực tế: Đặc tả công cụ tối thiểu khả thi

[[CODE_FENCE_LANG=json]]

{

"name": "create_invoice",

"description": "Create a draft invoice for an existing customer.",

"inputSchema": {

"type": "object",

"required": ["customer_id", "line_items"],

"properties": {

"customer_id": {

"type": "string",

"description": "ID of an existing customer. Use list_customers to find one."

},

"line_items": {

"type": "array",

"minItems": 1,

"items": {

"type": "object",

"required": ["description", "amount_cents"],

"properties": {

"description": {"type": "string"},

"amount_cents": {"type": "integer", "minimum": 1}

}

}

},

"currency": {"type": "string", "enum": ["USD", "EUR", "GBP"], "default": "USD"}

}

},

"outputSchema": {

"type": "object",

"required": ["invoice_id", "status"],

"properties": {

"invoice_id": {"type": "string"},

"status": {"type": "string", "enum": ["draft", "open", "paid"]},

"total_cents": {"type": "integer"}

}

},

"annotations": {

"readOnlyHint": false,

"destructiveHint": false,

"requiresConfirmation": false,

"idempotent": false

}

}

[[/CODE_FENCE]]

Các lỗi thực thi phổ biến

1. Định danh công cụ chung chung ví dụ như do_thing hoặc helper_v2. Agent gặp khó khăn hoặc thất bại trong việc phân biệt và lựa chọn.
2. Thiếu outputSchema. Buộc các agent phải phân tích văn bản định dạng tự do (free-form text), làm giảm tính tất định (determinism).
3. Công cụ đa chức năng (overloaded tool) chuyển đổi hành vi dựa trên một tham số chuỗi (string parameter). Yêu cầu cấp thiết là phân tách thành các công cụ chuyên biệt.
4. Thiếu môi trường hộp cát. Các agent buộc phải tương tác trực tiếp với môi trường sản xuất để lập bản đồ API.
5. Token xác thực định tuyến qua một API key duy nhất. Thiết kế này triệt tiêu khả năng ủy quyền người dùng và sự đồng thuận minh bạch.
6. Thiếu cờ requiresConfirmation trên các công cụ phá hủy. Làm gia tăng đáng kể bán kính nổ (blast radius) đối với các lỗi suy luận do agent gây ra.
7. Thay đổi lược đồ không tương thích ngược mà không gia tăng phiên bản. Gây ra sự cố ngầm định cho toàn bộ các agent client đang kết nối.

Các câu hỏi thường gặp (FAQ)

Q: Việc hỗ trợ toàn bộ các nguyên hàm MCP (công cụ, tài nguyên, lời nhắc) có bắt buộc không?

A: Không. Đa số các máy chủ chỉ tập trung triển khai công cụ (tool). Các tài nguyên (resource) mang lại giá trị cao đối với loại dữ liệu read-mostly (hầu như chỉ đọc) được định danh qua URI; lời nhắc (prompt) tối ưu cho việc cung cấp các prompt template tái sử dụng. Cần tiến hành triển khai tập con (subset) tương thích với use case thực tế và khai báo minh bạch trong quá trình đàm phán khả năng (capability negotiation).

Q: Mức độ chi tiết (granularity) của các phạm vi (scope) nên được thiết kế như thế nào?

A: Nguyên tắc là một scope tương ứng với một khả năng logic, phản chiếu (mirroring) cấu trúc phân nhóm công cụ. Ví dụ: invoices.read, invoices.write, customers.read. Cần nghiêm ngặt tránh các phạm vi bao trùm (umbrella scope) như admin vì chúng vô hiệu hóa khả năng của agent trong việc yêu cầu các đặc quyền tối thiểu (least privilege).

Q: OAuth 2.1 có phải là tiêu chuẩn bắt buộc cho mọi máy chủ MCP không?

A: Đặc tả ủy quyền của MCP được kiến trúc dựa trên OAuth 2.1, và toàn bộ các client tham chiếu từ Anthropic đều mặc định hỗ trợ chuẩn này. Các máy chủ hoạt động độc lập cục bộ (stdio transport) có thể linh động bỏ qua OAuth, tuy nhiên, bất kỳ máy chủ MCP nào có kết nối mạng (networked) đều bắt buộc phải triển khai OAuth 2.1.

Q: Khối lượng công cụ tối ưu mà một máy chủ duy nhất nên cung cấp là bao nhiêu?

A: Ngưỡng 10-30 công cụ được xác định là điểm rơi hiệu quả tối ưu nhất. Quy mô dưới 10 công cụ vẫn đảm bảo hiệu suất. Tuy nhiên, nếu vượt quá ngưỡng ~30 công cụ, độ chính xác trong thuật toán lựa chọn của agent sẽ suy giảm rõ rệt; trong trường hợp này, cần ưu tiên chiến lược phân tách thành nhiều máy chủ chuyên biệt theo từng chủ đề.

Q: Đâu là điểm phân biệt giữa destructiveHint và requiresConfirmation?

A: destructiveHint: true là một thuộc tính tĩnh định nghĩa bản chất của công cụ (khả năng xóa bỏ hoặc sửa đổi trạng thái). Trái lại, requiresConfirmation: true là một chỉ thị thực thi, buộc client phải hiển thị hộp thoại xác nhận từ người dùng trước khi tiến hành lệnh gọi. Các công cụ phá hủy bắt buộc phải yêu cầu xác nhận; các công cụ phi phá hủy (non-destructive) trong một số ngữ cảnh đặc thù cũng có thể áp dụng yêu cầu xác nhận (ví dụ: các giao dịch tài chính).

Q: Chiến lược đánh phiên bản (versioning) máy chủ nào đảm bảo không gây gián đoạn (breaking) cho các agent?

A: Hệ thống phiên bản ngữ nghĩa (Semver) là giải pháp tiêu chuẩn. Bắt buộc gia tăng phiên bản major khi loại bỏ công cụ hoặc thực hiện các thay đổi phá vỡ lược đồ (breaking schema). Gia tăng phiên bản minor đối với các thao tác bổ sung công cụ hoặc mở rộng trường dữ liệu (non-breaking field). Đồng thời, cần duy trì một giai đoạn chuyển tiếp (overlap) kéo dài ít nhất một phiên bản minor để hỗ trợ các công cụ đã bị ngừng sử dụng nhưng được gắn cờ deprecated: true.