Viết MCP server - host, client, server, ba primitive và hai cách giao tiếp

Một tool viết riêng cho một ứng dụng thì chỉ ứng dụng đó dùng được. Khi nhiều ứng dụng Claude cùng cần một năng lực, như tra danh mục sách hay tồn kho, cách chuẩn là đóng gói nó thành một MCP server: viết một lần, bảo trì một chỗ, ứng dụng nào nói được giao thức MCP cũng kết nối được.

Bài này giúp bạn trả lời: một MCP server gồm những gì, chạy theo cách nào, và đưa nó tới các ứng dụng Claude ra sao?

Ví dụ xuyên suốt: MCP server của mạng lưới thư viện tỉnh

Mười thư viện công cộng của một tỉnh dùng chung một hệ thống quản lý sách có REST API nội bộ. Ba nơi muốn dùng dữ liệu này với Claude:

1. Chatbot trên website giúp bạn đọc tìm sách, chạy bằng Claude API.
2. Đội phát triển dùng Claude Code để viết báo cáo mượn trả.
3. Thủ thư dùng ứng dụng desktop của Claude để soạn danh sách sách gợi ý theo chủ đề.

Thay vì mỗi nơi tự viết tool gọi REST API, đội làm một MCP server thu-vien.

Host, client và server

Đặc tả MCP mô tả ba vai trò:

MCP dùng JSON-RPC. Hai bên khai báo năng lực (capabilities) mình hỗ trợ: server cho biết có tool, resource, prompt nào, có gửi thông báo khi danh sách đổi không. Theo đặc tả phiên bản 2026-07-28, mỗi yêu cầu mang theo phiên bản giao thức và năng lực của client, và client có thể gọi server/discover trước để biết năng lực của server.

Ba thứ một server cung cấp

Một tool khai báo inputSchema (JSON Schema của tham số) và có thể có outputSchema; kết quả có cấu trúc trả trong structuredContent.

{
  "name": "tim_sach",
  "description": "Tìm sách theo từ khoá trong danh mục của một hoặc mọi thư viện. Trả tối đa 20 kết quả kèm số bản còn trên kệ.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tu_khoa": { "type": "string" },
      "thu_vien": { "type": "string", "description": "Mã thư viện, bỏ trống để tìm tất cả" }
    },
    "required": ["tu_khoa"]
  }
}

Resource có thể là tĩnh (một URI cụ thể) hoặc theo mẫu (resource template, URI có biến như sach://{ma_sach}), liệt kê qua resources/list và resources/templates/list, đọc qua resources/read. Prompt liệt kê qua prompts/list, lấy nội dung kèm tham số qua prompts/get.

Đặc tả chia lỗi của tool làm hai loại:

• Lỗi giao thức: tool không tồn tại, yêu cầu sai cấu trúc, lỗi server. Trả về như lỗi JSON-RPC chuẩn; model khó tự sửa.
• Lỗi khi chạy tool: API phía sau lỗi, tham số sai định dạng hay ngoài khoảng, lỗi nghiệp vụ. Trả trong kết quả tool với isError: true, để model đọc và thử cách khác.

Hai cách giao tiếp: stdio và Streamable HTTP

Lỗi hay gặp với stdio: một câu print để gỡ lỗi ghi ra stdout và làm hỏng luồng thông điệp. Mọi log phải đi ra stderr.

Triển khai và tích hợp

Trong ví dụ, ba host cần ba cách kết nối:

• Claude Code (đội phát triển): lúc viết server, chạy cục bộ bằng stdio; sau đó kết nối bản đã triển khai bằng claude mcp add --transport http thu-vien <url>. Thêm --scope project để ghi vào .mcp.json ở gốc repo cho cả đội dùng; mặc định là phạm vi local, chỉ riêng bạn trong dự án đó. Docs Claude Code nói transport SSE đã bị bỏ dần, nên dùng HTTP.
• Chatbot trên website (Claude API): dùng MCP connector của Messages API, khai server trong mcp_servers và một mcp_toolset tương ứng trong tools (đang beta). Connector chỉ kết nối được server công khai qua HTTP, không kết nối thẳng server stdio cục bộ, và hiện chỉ hỗ trợ gọi tool.
• Ứng dụng desktop: kết nối tới cùng server HTTP.

Vậy để ba nơi dùng chung, server phải được triển khai lên một nơi cả ba truy cập được, bằng Streamable HTTP, có xác thực.