MCP là gì?

• Tools (Công cụ): Các hàm mà Agent có thể gọi (ví dụ: search_documents, create_issue).
• Resources (Tài nguyên): Dữ liệu mà Agent có thể đọc (tệp tin, bản ghi cơ sở dữ liệu).
• Prompts (Gợi ý): Các luồng công việc được xây dựng sẵn mà người dùng hoặc Agent có thể kích hoạt.
• Ý tưởng đằng sau MCP là: xây dựng MCP server một lần và sử dụng với bất kỳ Agent nào.

MCP KHÔNG PHẢI là gì

Ví dụ thực tế: Theo dõi đơn hàng

Cách xây dựng một MCP Server tốt (Các thực hành tốt nhất)

1. Tập trung vào Kết quả, không phải Thao tác

• Sai lầm (Trap): Chuyển đổi các endpoint của REST API sang MCP tool theo tỷ lệ 1:1.
• Giải pháp (Fix): Thiết kế công cụ xoay quanh mục tiêu mà người dùng hoặc Agent muốn đạt được.

2. Làm phẳng các tham số (Flatten Your Arguments)

• Sai lầm: Sử dụng các từ điển lồng nhau (nested dictionaries) phức tạp hoặc các đối tượng cấu hình làm đối số.
• Giải pháp: Sử dụng các kiểu dữ liệu cơ bản ở cấp cao nhất và các kiểu dữ liệu bị ràng buộc.

3. Chỉ dẫn chính là Ngữ cảnh

• Sai lầm: Để trống docstring (phần mô tả hàm), thông báo lỗi chung chung.
• Giải pháp: Mọi đoạn văn bản đều là một phần ngữ cảnh của Agent.

• Khi nào nên dùng công cụ: ("Sử dụng khi người dùng hỏi về trạng thái đơn hàng")
• Cách định dạng đối số: ("Email phải được viết thường")
• Kết quả trả về là gì: ("Trả về ID đơn hàng và trạng thái hiện tại")

4. Sàng lọc quyết liệt (Curate Ruthlessly)

• Sai lầm: Phơi bày mọi thứ mà API có thể làm. Trả về mọi thứ mà API trả về.
• Giải pháp: Thiết kế để dễ khám phá, không phải để phơi bày cạn kiệt.

• Chỉ nên có 5–15 công cụ trên mỗi server.
• Một server, một nhiệm vụ duy nhất.
• Xóa bỏ các công cụ không sử dụng.
• Chia nhỏ theo vai trò (Admin/Người dùng).

5. Đặt tên công cụ để dễ khám phá

• Sai lầm: Tên chung chung như create_issue hoặc send_message.
• Giải pháp: Tên có tiền tố dịch vụ và hướng hành động.

6. Phân trang cho các kết quả lớn

• Sai lầm: Trả về hàng trăm bản ghi cùng lúc.
• Giải pháp: Phân trang kèm theo siêu dữ liệu (metadata).
• Tôn trọng tham số limit (mặc định nên là 20–50).
• Trả về các thông tin như has_more, next_offset, total_count.
• Tuyệt đối không tải tất cả kết quả vào bộ nhớ.

Ví dụ thực tế: Gmail MCP Server

Trước khi tối ưu (Cách làm cũ)

# Việc đọc một email yêu cầu 2 công cụ + phải hiểu các kiểu dữ liệu lồng nhau
def messages_list(query: str, max_results: int) -> {"messages": [{"id": str, "threadId": str}], "nextPageToken": str}: ...
def messages_get(message_id: str, format: str) -> {"id": str, "snippet": str, "payload": {"headers": list, "body": {"data": str}}}: ...
 
# Việc gửi một email yêu cầu mã hóa base64 cho một tin nhắn MIME
def messages_send(message: {"raw": str}) -> {"id": str, "threadId": str}: ...  # raw = base64url RFC 2822
 
# Việc tạo bản nháp có đối tượng tin nhắn lồng nhau phức tạp
def drafts_create(draft: {"message": {"raw": str}}) -> {"id": str, "message": {"id": str}}: ...

Sau khi tối ưu (Thiết kế ưu tiên Agent)

# Việc đọc: 2 công cụ với tham số phẳng và dữ liệu trả về đã được sàng lọc
def gmail_search(query: str, limit: int = 10) -> [{"id": str, "subject": str, "sender": str, "date": str, "snippet": str}]: ...
def gmail_read(message_id: str) -> {"subject": str, "sender": str, "body": str, "attachments": [str]}: ...
 
# Việc viết: Các ví dụ đơn giản, không bao gồm cc, bcc để giảm độ phức tạp.
def gmail_send(to: List[str], subject: str, body: str, reply_to_id: str = None) -> {"success": bool, "message_id": str}: ...

Skills và MCP: Bổ trợ chứ không phải Đối đầu

• MCP đóng vai trò là "đường ống" kỹ thuật để kết nối dữ liệu và công cụ.
• Skills đóng vai trò là "trí thông minh" và "quy trình" để hướng dẫn Agent cách sử dụng những đường ống đó một cách hiệu quả.

Kết luận

• Kết quả quan trọng hơn thao tác: Thiết kế xoay quanh mục tiêu của Agent.
• Làm phẳng các tham số: Sử dụng các kiểu dữ liệu cơ bản (primitives) và enum.
• Chỉ dẫn chính là ngữ cảnh: Docstring và thông báo lỗi rất quan trọng.
• Sàng lọc quyết liệt: Ít công cụ hơn, phản hồi gọn gàng hơn.
• Đặt tên để dễ khám phá: Sử dụng tên có tiền tố dịch vụ.
• Phân trang kết quả: Cung cấp siêu dữ liệu cho các danh sách lớn.