modelcontextprotocol/typescript-sdk: xây MCP server và client — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về modelcontextprotocol/typescript-sdk — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: modelcontextprotocol/typescript-sdk: xây MCP server và client — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
modelcontextprotocol/typescript-sdk là SDK TypeScript chính thức cho Model Context Protocol, giúp bạn xây MCP server cung cấp tools, resources, prompts và MCP client để kết nối chúng với ứng dụng LLM. SDK chạy trên Node.js, Bun và Deno; cách cài khá thẳng bằng npm, nhưng bạn cần biết TypeScript cơ bản.
modelcontextprotocol/typescript-sdk là SDK TypeScript chính thức để xây dựng MCP server và MCP client. MCP giúp ứng dụng cung cấp context cho mô hình ngôn ngữ theo một chuẩn chung, tách phần cung cấp dữ liệu và công cụ khỏi phần giao tiếp với LLM.
Repo phù hợp với dev TypeScript muốn đưa dữ liệu hoặc thao tác của ứng dụng vào một hệ thống AI, chẳng hạn cho phép AI gọi API nội bộ, đọc tài liệu, truy vấn dữ liệu hoặc thực hiện một quy trình có kiểm soát. Điểm đáng giá nhất là SDK đã có sẵn các thư viện server, client, transport và helper xác thực thay vì bạn phải tự thiết kế toàn bộ giao thức kết nối.
Hiện repo có khoảng 13758 sao và 2383 fork. Đây là một monorepo TypeScript, phát hành thành các gói tách riêng như @modelcontextprotocol/server và @modelcontextprotocol/client. Bạn cũng có thể dùng các middleware tùy chọn cho Node.js HTTP, Express, Fastify hoặc Hono.
modelcontextprotocol/typescript-sdk
SDK TypeScript chính thức để xây MCP server, MCP client và kết nối LLM với tools, resources, prompts chuẩn hóa.
I.modelcontextprotocol/typescript-sdk làm được gì
A.Xây MCP server có tool cho AI gọi
Gói server cho phép bạn đăng ký các tool mà ứng dụng LLM có thể gọi. Mỗi tool có tên, mô tả, schema đầu vào và hàm xử lý. Ví dụ trong README là tool greet, nhận tên người dùng rồi trả về lời chào.
Với cách này, một hệ thống AI có thể gọi các chức năng thật của ứng dụng theo cấu trúc rõ ràng. Bạn có thể biến một API nội bộ, một thao tác nghiệp vụ hoặc một quy trình hỗ trợ khách hàng thành tool MCP, miễn là phần xử lý được bạn triển khai trong server.
B.Cung cấp resources và prompts
SDK server hỗ trợ tools, resources và prompts. Resources phù hợp để cung cấp context cho ứng dụng, còn prompts giúp chuẩn hóa những mẫu hướng dẫn mà client có thể sử dụng.
Điều này hữu ích khi bạn muốn AI làm việc với dữ liệu có cấu trúc thay vì chỉ nhận một đoạn văn bản tùy ý. Ví dụ, một ứng dụng nội bộ có thể cung cấp tài liệu hoặc dữ liệu nghiệp vụ qua resource, rồi cung cấp prompt để nhân viên sử dụng theo cùng một quy trình.
C.Kết nối qua stdio hoặc Streamable HTTP
SDK có transport stdio và Streamable HTTP. Stdio phù hợp cho các chương trình chạy cục bộ, nơi một ứng dụng khởi chạy MCP server và giao tiếp với server qua input/output chuẩn.
Streamable HTTP phù hợp khi server cần chạy như một dịch vụ HTTP. README cũng nêu các helper cho Node.js HTTP, Express, Fastify và Hono, giúp bạn gắn MCP vào runtime hoặc web framework đang dùng.
D.Xây MCP client
Gói client cung cấp transport, high-level helpers và OAuth helpers. Client có thể kết nối đến MCP server, liệt kê tools rồi gọi tool.
Bạn có thể dùng phần này để xây một ứng dụng trung gian hoặc một tác nhân AI có khả năng sử dụng nhiều MCP server. Client đảm nhận phần kết nối theo MCP, còn ứng dụng của bạn quyết định khi nào cần gọi tool và xử lý kết quả ra sao.
E.Dùng schema quen thuộc
Schema của tool và prompt dùng Standard Schema. Bạn có thể chọn Zod v4, Valibot, ArkType hoặc thư viện tương thích.
Trong ví dụ tối giản, README dùng Zod v4 để khai báo name là chuỗi. Cách khai báo schema giúp đầu vào của tool có cấu trúc rõ ràng, dễ kiểm tra và dễ hiểu hơn khi tích hợp với ứng dụng khác.
F.Chọn middleware theo runtime
Các gói middleware là adapter mỏng, không thêm tính năng MCP hoặc business logic mới. Bạn có thể chọn @modelcontextprotocol/node cho Node.js HTTP, hoặc các gói Express, Fastify, Hono khi ứng dụng đang dùng framework tương ứng.
Điểm này giúp phần MCP hòa vào web server hiện có mà không buộc bạn viết lại lớp xử lý nghiệp vụ.
II.Cần chuẩn bị gì
- Máy có Node.js phiên bản 20 trở lên.
package.jsoncủa repo yêu cầu Node>=20. - Kiến thức cơ bản về TypeScript và JavaScript để đọc ví dụ, khai báo server, đăng ký tool và viết hàm xử lý.
- Một môi trường chạy JavaScript được SDK hỗ trợ: Node.js, Bun hoặc Deno.
- Nếu xây server, bạn cần chọn gói
@modelcontextprotocol/server. - Nếu xây client, bạn cần chọn gói
@modelcontextprotocol/client. - Nếu tích hợp với web framework, bạn cần framework tương ứng. README đưa ra các lựa chọn Express, Fastify, Hono hoặc Node.js HTTP.
- Nếu dùng schema trong ví dụ, cần cài thêm Zod v4 hoặc một thư viện Standard Schema tương thích.
README không yêu cầu API key, tài khoản dịch vụ, GPU hay phần cứng đặc biệt cho ví dụ tối giản. Việc có cần API key hay quyền truy cập hay không sẽ phụ thuộc vào tool, resource và hệ thống thật mà bạn tự kết nối.
Repo có hỗ trợ Node.js, Bun và Deno. README không mô tả chi tiết yêu cầu riêng cho từng hệ điều hành, nên phần chuẩn bị an toàn nhất là dùng một trong các runtime này và bảo đảm phiên bản Node.js đạt yêu cầu khi cài bằng npm.
III.Cài đặt từng bước
- Chọn kiểu tích hợpQuyết định bạn xây MCP server, MCP client hay dùng cả hai
- Cài gói SDKCài package server hoặc client bằng npm, Bun hoặc Deno
- Cài schema và middleware nếu cầnThêm Zod v4 hoặc adapter cho web framework
- Tạo server tối giảnĐăng ký một tool và kết nối bằng stdio
- Mở tài liệu và ví dụDựa trên tutorials và thư mục examples để xây ứng dụng thật
A.Chọn gói cần dùng
Nếu chương trình của bạn cung cấp chức năng cho ứng dụng AI gọi, hãy bắt đầu với gói server. Nếu chương trình của bạn kết nối đến MCP server và gọi các tool, hãy bắt đầu với gói client. Một ứng dụng phức tạp có thể cần cả hai, nhưng README tách chúng thành hai package để bạn chỉ cài phần cần thiết.
Tên package v2 trong README là @modelcontextprotocol/server và @modelcontextprotocol/client. Đừng tự đổi sang tên package v1 nếu bạn đang dùng nhánh chính của repo. README nói rõ package v1 là @modelcontextprotocol/sdk và nằm trên nhánh v1.x.
B.Cài MCP server
Mở terminal tại thư mục dự án TypeScript của bạn rồi chạy một trong các lựa chọn sau:
npm install @modelcontextprotocol/server
# or
bun add @modelcontextprotocol/server
# or
deno add npm:@modelcontextprotocol/servernpm install thêm package server vào dự án npm. bun add làm việc tương tự trong dự án Bun. Với Deno, lệnh deno add thêm package thông qua định danh npm.
Nếu terminal báo không tìm thấy npm, bun hoặc deno, bạn đang thiếu runtime tương ứng hoặc runtime chưa có trong PATH. Với npm, trước hết kiểm tra Node.js đã đạt phiên bản 20 trở lên. README không đưa ra lệnh cài Node.js cụ thể, nên bạn nên cài Node.js theo cách phù hợp với hệ điều hành của mình.
C.Cài MCP client
Nếu bạn viết ứng dụng kết nối đến server, chạy:
npm install @modelcontextprotocol/client
# or
bun add @modelcontextprotocol/client
# or
deno add npm:@modelcontextprotocol/clientChỉ cài client không tự tạo ra một MCP server. Bạn vẫn cần có server đang chạy hoặc một server do bạn xây bằng gói server. Client sẽ đảm nhận transport và các helper ở phía kết nối.
D.Cài middleware tùy chọn
Chỉ cài middleware khi bạn thực sự dùng runtime hoặc framework tương ứng:
# Node.js HTTP (IncomingMessage/ServerResponse) Streamable HTTP transport:
npm install @modelcontextprotocol/node
# Express integration:
npm install @modelcontextprotocol/express express
# Fastify integration:
npm install @modelcontextprotocol/fastify fastify
# Hono integration:
npm install @modelcontextprotocol/hono honoGói middleware không thay thế package server hoặc client. Chúng là adapter mỏng để nối MCP vào Node.js HTTP, Express, Fastify hoặc Hono. Nếu bạn chỉ đang thử server stdio trong ví dụ tối giản, chưa cần cài các gói này.
E.Thêm schema và tạo server tối giản
Ví dụ trong README dùng Zod v4. README không đưa ra lệnh cài Zod riêng, nhưng mã ví dụ cho biết server cần import zod/v4. Vì vậy, trước khi chạy đúng ví dụ này, bạn cần bảo đảm dự án đã có Zod v4 theo cách quản lý dependency của dự án.
Tạo một file TypeScript trong dự án, sau đó đặt đoạn mã sau vào file đó:
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
const server = new McpServer({ name: 'greeting-server', version: '1.0.0' });
server.registerTool(
'greet',
{
description: 'Greet someone by name',
inputSchema: z.object({ name: z.string() })
},
async ({ name }) => ({
content: [{ type: 'text', text: `Hello, ${name}!` }]
})
);
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
}
main();Dòng import đầu tiên lấy McpServer để tạo server. Dòng thứ hai lấy transport stdio. Dòng thứ ba lấy Zod v4 để mô tả dữ liệu đầu vào.
new McpServer đặt tên và phiên bản cho server. registerTool đăng ký tool có tên greet. Trong schema, name bắt buộc là chuỗi. Hàm xử lý nhận object đã được mô tả bởi schema rồi trả về một content dạng văn bản.
Trong main, StdioServerTransport tạo kết nối qua stdio và server.connect bắt đầu phục vụ. Đây là server tối giản nên chưa có HTTP endpoint, OAuth hoặc cơ sở dữ liệu. Bạn có thể dùng nó để kiểm tra luồng MCP căn bản trước.
Không đưa API key, token hoặc thông tin bí mật trực tiếp vào mã nguồn. README không yêu cầu key cho ví dụ greet, nhưng tool thật có thể truy cập hệ thống nội bộ hoặc dịch vụ tính phí. Hãy giới hạn quyền của credential và kiểm tra dữ liệu đầu vào trước khi cho AI gọi thao tác có tác động thật.
F.Xem tutorial và ví dụ có thể chạy
Sau khi cài package, hãy mở phần tutorials trong tài liệu của repo. README hướng dẫn xây server đầu tiên là một weather-alert server qua stdio, bắt đầu từ npm init đến lúc gọi tool. Tutorial client hướng dẫn kết nối đến server, liệt kê tools và gọi tool.
Nếu muốn xem ví dụ end-to-end, mở examples/README.md. README mô tả đây là các cặp client/server có thể chạy và tự kiểm tra, mỗi thư mục thể hiện một câu chuyện sử dụng. Đây là nơi phù hợp để đối chiếu cấu trúc file, transport và cách hai phía giao tiếp trước khi áp dụng vào dự án của bạn.
Nếu bạn đang làm chính repo SDK thay vì chỉ dùng package, file package.json là nơi khai báo cách chạy của repo. Repo cũng có pnpm-lock.yaml, pnpm-workspace.yaml, thư mục packages/, docs/, examples/, scripts/ và test/. README cung cấp các lệnh làm tài liệu cục bộ, nhưng không mô tả một quy trình đầy đủ để build toàn bộ SDK từ source. Hãy xem package.json và các hướng dẫn trong repo trước khi làm việc ở cấp monorepo.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra đơn giản nhất là chạy server tối giản và kết nối nó với một MCP client theo tutorial client. Server cần khởi động thành công, không lỗi import package và không lỗi schema. Khi client liệt kê tools, bạn cần thấy tool có tên greet.
Sau đó, gọi tool với đầu vào có dạng tên chuỗi. Kết quả mong đợi theo README là một content văn bản có nội dung tương đương Hello, <tên>!. Nếu bạn truyền dữ liệu không phù hợp với schema, hãy kiểm tra phần z.object({ name: z.string() }) và dữ liệu client gửi lên.
Bạn cũng có thể kiểm tra theo các dấu hiệu sau:
- Package
@modelcontextprotocol/serverhoặc@modelcontextprotocol/clientxuất hiện trong dependency của dự án. - Server khởi tạo được với
new McpServervà kết nối được bằngStdioServerTransport. - Client kết nối được đến server, liệt kê được tools và gọi được tool.
- Khi dùng HTTP, transport và middleware tương ứng được gắn vào runtime hoặc framework của bạn.
README không cung cấp một màn hình kết quả duy nhất hoặc một lệnh test ngắn áp dụng cho mọi dự án người dùng. Vì vậy, kết quả xác nhận đáng tin cậy nhất là client gọi được tool và nhận về content đúng như logic bạn viết.
V.Dùng vào việc thật
A.Chủ shop muốn AI tra cứu tình trạng đơn hàng
Chủ shop có thể xây một MCP server cung cấp tool tra cứu đơn hàng. Tool nhận mã đơn dưới dạng chuỗi, kiểm tra hệ thống quản lý đơn hàng mà bạn kết nối, rồi trả về trạng thái, sản phẩm và thông tin giao nhận phù hợp với quyền được cấp.
Cách làm bám theo ví dụ greet: tạo McpServer, dùng registerTool, khai báo input schema bằng Zod v4 và trả về content dạng text. Một câu lệnh mẫu cho người dùng AI có thể là: “Kiểm tra đơn hàng DH001 và cho biết đơn đang ở trạng thái nào.”
Kết quả nhận được là dữ liệu do hàm xử lý của tool trả về. SDK lo phần mô tả tool, schema và giao tiếp MCP; bạn vẫn phải tự viết phần gọi hệ thống đơn hàng và kiểm soát quyền truy cập.
B.Nhân viên văn phòng muốn hỏi tài liệu nội bộ
Một nhóm có thể xây MCP server cung cấp tài liệu hoặc dữ liệu nội bộ dưới dạng resources. Client kết nối đến server để lấy context cần thiết, sau đó ứng dụng AI dùng context đó khi trả lời câu hỏi.
Ví dụ, nhân viên hỏi: “Quy trình duyệt chi phí công tác của công ty là gì?” Server có thể cung cấp resource chứa tài liệu quy trình. README xác nhận SDK hỗ trợ resources, nhưng không đưa ra mã triển khai cụ thể cho hệ thống tài liệu, nên cấu trúc resource và cách phân quyền cần xem trong tài liệu đầy đủ của SDK.
Kết quả tốt là câu trả lời dựa trên nguồn dữ liệu mà server cung cấp, thay vì mỗi nhân viên tự tải tài liệu lên theo cách khác nhau. Bạn cần đặc biệt kiểm soát ai được phép đọc resource nào.
C.Dev xây một client gọi nhiều tool
Dev có thể dùng @modelcontextprotocol/client để tạo ứng dụng kết nối đến MCP server, liệt kê tools rồi gọi tool theo nhu cầu. Đây là nền tảng phù hợp cho một client trung gian hoặc ứng dụng AI có nhiều khả năng nghiệp vụ.
Luồng sử dụng mẫu là: kết nối đến server, lấy danh sách tool, chọn tool phù hợp với yêu cầu, gửi input đúng schema và xử lý content trả về. Một yêu cầu mẫu là: “Liệt kê các tool hiện có, sau đó gọi tool kiểm tra tồn kho cho mã SP001.”
README xác nhận client có transports, high-level helpers và OAuth helpers. Phần chọn transport, xác thực và điều phối lời gọi cụ thể cần dựa vào tutorial client và tài liệu tương ứng.
D.Nhóm kỹ thuật đưa MCP vào web server hiện có
Nếu hệ thống đang chạy Express, Fastify, Hono hoặc Node.js HTTP, nhóm có thể chọn middleware tương ứng để nối Streamable HTTP vào runtime hiện có. Ví dụ, một API nội bộ có thể dùng Express để nhận request, còn MCP middleware hỗ trợ phần kết nối MCP.
Bạn cài đúng adapter theo framework, chẳng hạn @modelcontextprotocol/express cùng express, rồi xem packages/middleware/README.md để biết cách tích hợp. Đừng đặt business logic vào middleware; README nói rõ middleware chỉ là adapter mỏng và không nên thêm tính năng MCP hoặc logic nghiệp vụ.
Kết quả là ứng dụng giữ được framework hiện tại nhưng có thêm đường tích hợp MCP. Phần xác thực, phân quyền và xử lý nghiệp vụ vẫn cần được thiết kế trong ứng dụng của bạn.
Giá trị của MCP nằm ở việc biến khả năng thật của ứng dụng thành những công cụ AI có thể gọi theo một chuẩn rõ ràng.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Node.js thấp hơn phiên bản yêu cầu
package.json yêu cầu Node >=20. Nếu npm báo lỗi engine hoặc package không cài/chạy đúng, hãy kiểm tra phiên bản Node.js rồi nâng lên phiên bản đáp ứng yêu cầu. Không nên bỏ qua cảnh báo engine khi bạn đang xây hệ thống cần ổn định.
B.Cài nhầm package v1 và v2
Nhánh chính của README dùng v2 với các package @modelcontextprotocol/server và @modelcontextprotocol/client. Package @modelcontextprotocol/sdk thuộc v1.x. Nếu ví dụ import không khớp với package đã cài, hãy kiểm tra bạn đang theo tài liệu v2 hay tài liệu v1 và giữ nhất quán giữa package, import và hướng dẫn.
C.Không tìm thấy zod/v4
Ví dụ server import zod/v4 nhưng schema library không nằm trong các lệnh cài server được README nêu. Hãy kiểm tra dự án đã có Zod v4 hoặc một lựa chọn Standard Schema tương thích chưa. Nếu đổi sang thư viện khác, bạn cần viết lại phần schema theo API của thư viện đó.
D.Server chạy nhưng client không thấy tool
Kiểm tra server có gọi server.registerTool trước khi server.connect hay không. Kiểm tra client đang kết nối đúng transport và đúng tiến trình server. Với server stdio, hãy xem lại cách bạn khởi chạy chương trình theo tutorial client; README không mô tả một câu lệnh chung cho mọi cấu trúc dự án.
E.Đưa quyền truy cập quá rộng cho tool
MCP server có thể mở đường cho AI gọi chức năng thật. Nếu tool truy cập đơn hàng, tài liệu hoặc dịch vụ bên ngoài, hãy giới hạn credential, kiểm tra input theo schema và chỉ cho phép thao tác cần thiết. README không quy định chính sách quyền riêng cho ứng dụng của bạn, nên đây là trách nhiệm của phần triển khai.
VII.Có nên dùng không
Nên dùng nếu bạn muốn xây MCP server hoặc client bằng TypeScript và cần một SDK chính thức có sẵn transport, helper, ví dụ và các gói middleware. Repo có cấu trúc rõ cho cả server lẫn client, hỗ trợ Node.js, Bun và Deno, đồng thời có tài liệu về tools, resources, prompts, HTTP, stdio, client, OAuth và migration.
SDK cũng phù hợp khi nhóm muốn giữ business logic trong ứng dụng nhưng cung cấp nó cho các ứng dụng AI qua một chuẩn chung. Các package tách riêng giúp bạn cài phần cần thiết, còn middleware giúp tích hợp vào web framework quen thuộc.
Giới hạn là SDK không tự cung cấp LLM, cơ sở dữ liệu, hệ thống phân quyền hay logic nghiệp vụ. Ví dụ greet chỉ cho thấy cách đăng ký và kết nối một tool; một hệ thống thật vẫn cần tự xử lý xác thực, logging, giới hạn quyền, lỗi mạng và dữ liệu nhạy cảm. README cũng không đưa ra yêu cầu API key hay chi phí vận hành chung, vì các phần này phụ thuộc vào dịch vụ mà tool của bạn kết nối.
Nếu bạn chỉ cần một script gọi API đơn giản và không cần khả năng tool/resource/prompt theo MCP, SDK này có thể là phần phụ thuộc lớn hơn mức cần thiết. Nếu bạn đang dùng Python hoặc một runtime khác, hãy chọn SDK MCP phù hợp với ngôn ngữ đó. Còn nếu mục tiêu là chuẩn hóa việc để ứng dụng AI dùng các khả năng thật của hệ thống TypeScript, đây là lựa chọn đáng bắt đầu từ tutorial server và client trong repo.
Câu hỏi thường gặp
Repo này có miễn phí không?
README cho biết dự án có mã nguồn với giấy phép Apache License 2.0 cho đóng góp mới và mã hiện có dưới MIT. README không nêu chi phí sử dụng dịch vụ bên ngoài mà các tool hoặc resource của bạn có thể kết nối.
Có cần GPU để chạy không?
README không yêu cầu GPU. SDK chạy trên Node.js, Bun và Deno; ví dụ server tối giản chỉ tạo MCP server, đăng ký tool và kết nối qua stdio.
Có chạy được trên Windows không?
README xác nhận SDK chạy trên Node.js, Bun và Deno nhưng không nêu chi tiết riêng cho Windows. Vì vậy, tài liệu được cung cấp chưa đủ để khẳng định các bước Windows-specific; bạn cần bảo đảm runtime phù hợp và Node.js đạt phiên bản 20 trở lên.
Có cần API key hoặc tài khoản riêng không?
Ví dụ `greet` trong README không yêu cầu API key hay tài khoản. Khi tool của bạn kết nối đến API, dữ liệu nội bộ hoặc dịch vụ tính phí, yêu cầu credential sẽ phụ thuộc vào hệ thống đó.
Dùng package nào để xây MCP server?
Dùng `@modelcontextprotocol/server` cho server. README v2 cũng nêu `@modelcontextprotocol/client` cho client; đừng nhầm với `@modelcontextprotocol/sdk`, package thuộc dòng v1.x.
SDK khác gì một thư viện gọi LLM?
SDK này triển khai Model Context Protocol để ứng dụng cung cấp context, tools, resources và prompts, đồng thời kết nối client với server. README không mô tả đây là thư viện gọi một nhà cung cấp LLM cụ thể.
Có thể tích hợp Express hoặc Fastify không?
Có. README nêu các package middleware tùy chọn cho Express, Fastify, Hono và Node.js HTTP, nhưng các package này chỉ là adapter mỏng để nối MCP vào runtime hoặc framework.


