Model Context Protocol (MCP): Kiến Trúc & Tự Xây Server
Tìm hiểu Model Context Protocol (MCP): kiến trúc JSON-RPC, stdio/SSE, tools, resources và cách tự viết một MCP server hoàn chỉnh bằng TypeScript.
Trong làn sóng bùng nổ của AI Agent và trợ lý lập trình, một bài toán nan giải luôn xuất hiện: làm thế nào để LLM (Large Language Model) kết nối an toàn với kho dữ liệu nội bộ, hệ thống tệp và các API bên ngoài mà không cần viết lại mã tích hợp cho từng mô hình?
Câu trả lời mang tính cách mạng từ Anthropic chính là Model Context Protocol (MCP) — một giao thức mở chuẩn hóa cách các mô hình AI tương tác với thế giới dữ liệu bên ngoài.
Tại sao MCP lại quan trọng?#
Trước khi có MCP, hệ sinh thái AI gặp phải bài toán M × N Integration:
- Nếu có ứng dụng AI (Claude Desktop, Cursor, VS Code, terminal agents…)
- Và nguồn dữ liệu / công cụ (PostgreSQL, GitHub, Slack, file system, Jira…)
- Các kỹ sư phải viết và duy trì kết nối riêng lẻ.
Mỗi khi một LLM mới ra mắt hoặc một API cập nhật schema, toàn bộ plugin phải được viết lại.
[!NOTE] MCP giải quyết triệt để vấn đề này: Thay vì , hệ thống chuyển thành . MCP đóng vai trò như chuẩn USB-C cho các ứng dụng AI. Bất kỳ AI Client nào hỗ trợ MCP đều có thể cắm vào bất kỳ MCP Server nào ngay lập tức.
Giải thích MCP đơn giản (ELI5)#
Hãy tưởng tượng AI Agent như một vị giáo sư thông thái nhưng bị nhốt trong phòng kín không có cửa sổ (mô hình LLM thuần túy):
- Host & Client (Cửa giao tiếp): Ứng dụng như Claude Desktop hay IDE đóng vai trò là trợ lý ngồi bên cạnh giáo sư.
- MCP Server (Các ngăn kéo chuyên dụng): Mỗi MCP Server là một ngăn kéo kết nối ra thế giới bên ngoài. Một ngăn chứa tài liệu nội bộ, một ngăn chứa máy tính tính toán, một ngăn kết nối vào kho mã nguồn GitHub.
- JSON-RPC (Ngôn ngữ chuẩn): Khi giáo sư muốn đọc dữ liệu hay thực hiện thao tác, ông gửi một phiếu yêu cầu chuẩn hóa. Ngăn kéo trả lời đúng định dạng đã thỏa thuận.
Ba thành phần cốt lõi của MCP#
Giao thức MCP định nghĩa 3 thành phần (primitives) cơ bản mà một Server có thể cung cấp cho Client:
1. Tools (Hành động do mô hình điều khiển)#
Là các hàm mà mô hình ngôn ngữ có thể chủ động gọi để thực thi tác vụ (ví dụ: truy vấn cơ sở dữ liệu, chạy lệnh bash, gửi tin nhắn Slack). Mô hình tự quyết định khi nào cần gọi tool và cung cấp tham số dựa trên JSON Schema.
2. Resources (Dữ liệu do ứng dụng kiểm soát)#
Là các tài nguyên chỉ đọc có URI xác định (ví dụ: file:///logs/app.log, postgres://users/schema). Client hoặc người dùng có thể đính kèm resources vào context để cung cấp tài liệu tham khảo cho LLM.
3. Prompts (Mẫu tương tác chuẩn)#
Là các prompt template có tham số giúp người dùng thực hiện nhanh các workflow định sẵn (ví dụ: prompt mẫu “Review pull request” hoặc “Debug crash log”).
Các phương thức truyền tải (Transports)#
MCP hỗ trợ 2 giao thức truyền tải chính:
- stdio (Standard Input / Output): Giao tiếp trực tiếp qua tiến trình cục bộ (local process). Client khởi chạy Server như một tiến trình con (child process), gửi tin nhắn qua
stdinvà nhận quastdout. Cực kỳ nhanh, bảo mật và phù hợp cho môi trường desktop/CLI. - SSE (Server-Sent Events) qua HTTP: Phù hợp cho MCP Server triển khai từ xa trên cloud. Client gửi request qua HTTP POST và nhận luồng dữ liệu liên tục qua SSE.
Hướng dẫn tự xây dựng một MCP Server hoàn chỉnh#
Dưới đây là ví dụ xây dựng một MCP Server bằng TypeScript sử dụng thư viện chính thức @modelcontextprotocol/sdk. Server này cung cấp:
- Một Resource đọc cấu hình dự án (
config://app-info) - Một Tool phân tích số liệu mã nguồn (
analyze_workspace)
1. Khởi tạo dự án#
mkdir my-custom-mcp-server
cd my-custom-mcp-server
bun init -y
bun add @modelcontextprotocol/sdk zodbash2. Mã nguồn MCP Server#
Tạo file src/index.ts:
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
CallToolRequestSchema,
ListResourcesRequestSchema,
ListToolsRequestSchema,
ReadResourceRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import { z } from 'zod';
// Khởi tạo MCP Server với metadata
const server = new Server(
{
name: 'project-analytics-server',
version: '1.0.0',
},
{
capabilities: {
resources: {},
tools: {},
},
},
);
// 1. Khai báo danh sách Resources
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: 'config://app-info',
name: 'Thông tin cấu hình dự án',
mimeType: 'application/json',
},
],
};
});
// Xử lý khi Client đọc Resource
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
if (request.params.uri === 'config://app-info') {
return {
contents: [
{
uri: 'config://app-info',
mimeType: 'application/json',
text: JSON.stringify(
{
projectName: 'Dopana Engineering Hub',
environment: 'production',
supportedEngines: ['Bun', 'Node.js', 'Rust'],
},
null,
2,
),
},
],
};
}
throw new Error(`Resource không tồn tại: ${request.params.uri}`);
});
// 2. Khai báo danh sách Tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: 'analyze_workspace',
description: 'Phân tích số dòng mã và thống kê file trong dự án',
inputSchema: {
type: 'object',
properties: {
fileExtension: {
type: 'string',
description: 'Định dạng file cần phân tích (ví dụ: ts, rs, py)',
},
},
required: ['fileExtension'],
},
},
],
};
});
// Xử lý khi mô hình gọi Tool
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === 'analyze_workspace') {
const ext = String(request.params.arguments?.fileExtension || 'ts');
return {
content: [
{
type: 'text',
text: JSON.stringify({
targetExtension: ext,
totalFilesFound: 42,
status: 'healthy',
summary: `Đã hoàn tất phân tích cho các tệp đuôi .${ext}`,
}),
},
],
};
}
throw new Error(`Không tìm thấy công cụ: ${request.params.name}`);
});
// Kết nối Server qua chuẩn stdio
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('MCP Server đã khởi động thành công qua stdio transport.');
}
main().catch((err) => {
console.error('Lỗi khởi động server:', err);
process.exit(1);
});typescript[!TIP] Lưu ý quan trọng khi dùng Stdio Transport: Luôn ghi log debug ra
stderr(console.error) thay vìstdout(console.log).stdoutđược dành riêng cho các gói tin JSON-RPC chuẩn của giao thức; nếu in text lạ rastdout, client sẽ báo lỗi cú pháp JSON.
3. Tích hợp vào Claude Desktop hoặc Cursor#
Thêm cấu hình sau vào tệp claude_desktop_config.json:
{
"mcpServers": {
"project-analytics": {
"command": "bun",
"args": ["run", "/absolute/path/to/my-custom-mcp-server/src/index.ts"]
}
}
}jsonKhởi động lại Claude Desktop, bạn sẽ thấy biểu tượng công cụ mới xuất hiện và AI có thể chủ động kích hoạt analyze_workspace theo ngữ cảnh người dùng.
Kết luận#
Model Context Protocol (MCP) không chỉ là một công nghệ mới mà là nền tảng mở cho thế hệ AI Agents tiếp theo. Bằng cách tách biệt việc huấn luyện mô hình khỏi việc kết nối dữ liệu thông qua kiến trúc Client-Server chuẩn hóa, MCP giúp nhà phát triển xây dựng các công cụ bền vững, an toàn và tái sử dụng cho bất kỳ nền tảng AI nào.