Bỏ qua tới nội dung
Ông T.vn

typescript-sdk: viết MCP server và client bằng TypeScript — hướng dẫn cài đặt và dùng

10 phút đọcCập nhật

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 →

typescript-sdk: viết MCP server và client bằng TypeScript — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

typescript-sdk là bộ thư viện TypeScript chính thức của Model Context Protocol (MCP), dùng để viết MCP server (đưa công cụ, dữ liệu cho AI) và MCP client (kết nối tới server). Cài bằng một lệnh npm install, nhưng bạn cần biết lập trình TypeScript cơ bản và có Node.js từ phiên bản 20 trở lên.

typescript-sdk là bộ thư viện TypeScript chính thức của Model Context Protocol (MCP), dùng để bạn tự viết MCP server (đưa công cụ, dữ liệu cho AI dùng) và MCP client (kết nối tới các server đó). Đây là repo do chính tổ chức đứng sau MCP duy trì, hiện có khoảng 13.754 sao và 2.382 fork.

MCP là một chuẩn chung để ứng dụng cung cấp ngữ cảnh cho mô hình AI. Thay vì mỗi ứng dụng tự nghĩ một cách nối với AI, MCP quy định một cách thống nhất. Bạn viết server một lần, các ứng dụng AI hỗ trợ MCP đều có thể dùng. SDK này lo phần giao thức, để bạn chỉ tập trung vào việc server của mình làm gì.

Repo hợp với lập trình viên (kể cả người mới đã biết chút TypeScript) muốn đưa dữ liệu hoặc nghiệp vụ của công ty cho AI dùng. Nếu bạn chỉ muốn dùng một MCP server có sẵn mà không viết code thì repo này chưa phải thứ bạn cần. Điểm đáng giá nhất: ví dụ nhỏ nhất chỉ khoảng 20 dòng code là đã có một server có công cụ chạy được.

Thư viện

modelcontextprotocol/typescript-sdk

Bộ SDK TypeScript chính thức của Model Context Protocol, giúp bạn tự viết MCP server và client chạy trên Node.js, Bun hoặc Deno.

★ 14kTypeScript
Xem repo trên GitHub

I.typescript-sdk làm được gì

Repo là một monorepo, chia thành các gói nhỏ. Mỗi gói lo một việc, bạn chỉ cài cái mình cần.

  • Viết MCP server. Gói @modelcontextprotocol/server cho phép bạn khai báo tool (công cụ AI có thể gọi), resource (dữ liệu AI có thể đọc) và prompt (mẫu câu lệnh dựng sẵn). Ví dụ: một tool tra tồn kho, một resource chứa bảng giá nội bộ.
  • Viết MCP client. Gói @modelcontextprotocol/client giúp ứng dụng của bạn kết nối tới một MCP server, liệt kê các tool nó có và gọi thử. Hữu ích khi bạn muốn xây ứng dụng riêng thay vì dùng ứng dụng AI có sẵn.
  • Nhiều cách kết nối. README nhắc tới stdio (chạy server như một chương trình cục bộ) và Streamable HTTP (chạy server qua mạng). Có cả các hàm hỗ trợ xác thực (auth, OAuth) cho cả server lẫn client.
  • Chạy trên nhiều môi trường. Node.js, Bun và Deno đều được hỗ trợ. Bạn dùng công cụ nào quen thì dùng cái đó.
  • Gói middleware tuỳ chọn. Có các adapter mỏng cho Node.js HTTP, Express, Fastify và Hono. Nếu web của bạn đã dùng một trong các framework này, bạn gắn MCP vào mà không phải viết lại từ đầu. Các gói này không thêm tính năng MCP mới, chỉ làm nhiệm vụ nối dây.
  • Tự chọn thư viện khai báo kiểu dữ liệu. Schema của tool và prompt dùng chuẩn Standard Schema, nên bạn có thể dùng Zod v4, Valibot, ArkType hoặc thư viện nào tương thích.
  • Có ví dụ chạy được. Thư mục examples/ có các cặp client/server tự kiểm tra, mỗi thư mục kể một câu chuyện riêng.

II.Cần chuẩn bị gì

  • Node.js từ phiên bản 20 trở lên. Đây là yêu cầu ghi trong package.json của repo. Nếu bạn dùng Bun hoặc Deno thì README cũng có lệnh cài riêng cho hai môi trường này.
  • Kiến thức TypeScript cơ bản. Đây là thư viện để viết code, không phải ứng dụng bấm là chạy.
  • Một thư viện khai báo schema. Ví dụ trong README dùng Zod v4 (import * as z from 'zod/v4'). README không ghi riêng lệnh cài Zod, nên nếu làm theo ví dụ, bạn cần tự cài thêm Zod.
  • Terminal. Trên Windows bạn có thể dùng PowerShell hoặc Terminal; trên macOS và Linux dùng Terminal sẵn có.
  • Tư liệu không nói gì về yêu cầu tài khoản, API key hay phần cứng đặc biệt (như GPU) cho chính SDK. Phần này chưa có thông tin.

Lưu ý về phiên bản: nhánh main của repo là v2, gồm hai gói `@modelcontextprotocol/server` và `@modelcontextprotocol/client`. Gói cũ tên `@modelcontextprotocol/sdk` thuộc dòng v1, nằm ở nhánh v1.x. Bài này hướng dẫn theo v2. Nếu dự án của bạn đang dùng v1, hãy xem hướng dẫn nâng cấp (migration guide) trên trang tài liệu của dự án trước khi đổi.

III.Cài đặt từng bước

  1. Kiểm tra Node.jsĐảm bảo máy có Node.js từ phiên bản 20 trở lên
  2. Tạo thư mục dự ánMở terminal ở một thư mục trống dành cho dự án của bạn
  3. Cài gói server hoặc clientChạy npm install cho gói bạn cần
  4. Cài thêm middleware (nếu cần)Chỉ cài khi bạn dùng Express, Fastify, Hono hoặc Node.js HTTP
  5. Chép ví dụ greetDán đoạn code mẫu của README vào file TypeScript của bạn

A.Kiểm tra Node.js

Mở terminal và gõ lệnh dưới đây. Kết quả phải là số phiên bản từ 20 trở lên. Nếu thấp hơn, bạn cần cập nhật Node.js trước.

Terminal
node --version

B.Tạo thư mục dự án

Bạn cần một thư mục riêng cho dự án, và phải mở terminal đúng trong thư mục đó. Đây là chỗ người mới hay vấp nhất: lệnh cài sẽ ghi vào thư mục mà terminal đang đứng. README nhắc tới việc dùng npm init để bắt đầu một dự án mới, từ đó bạn có file package.json.

Terminal
npm init

C.Cài gói server hoặc client

Nếu bạn muốn viết MCP server, cài gói server. README có lệnh cho cả npm, Bun và Deno, bạn chọn một dòng phù hợp với công cụ mình dùng:

Terminal
npm install @modelcontextprotocol/server
# or
bun add @modelcontextprotocol/server
# or
deno add npm:@modelcontextprotocol/server

Nếu muốn viết MCP client (ứng dụng kết nối tới server), cài gói client:

Terminal
npm install @modelcontextprotocol/client
# or
bun add @modelcontextprotocol/client
# or
deno add npm:@modelcontextprotocol/client

Hai gói này độc lập. Bạn có thể cài một trong hai hoặc cả hai tuỳ nhu cầu.

D.Cài thêm middleware (nếu cần)

Bước này không bắt buộc. Chỉ làm khi bạn muốn gắn MCP vào một web server có sẵn. Hãy chọn đúng một dòng theo framework bạn đang dùng. Với Express, Fastify và Hono, lệnh cài luôn kèm cả framework đó:

Terminal
# 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 hono

E.Chép ví dụ greet

Đây là server nhỏ nhất trong README: một tool tên greet, nhận một cái tên và trả về lời chào, giao tiếp qua stdio. Bạn lưu đoạn này vào một file TypeScript trong dự án:

TypeScript
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();

Cách đọc đoạn code này cho dễ hiểu:

  • McpServer là chiếc server, bạn đặt tên và số phiên bản cho nó.
  • registerTool đăng ký một công cụ. Có tên (greet), mô tả để AI biết khi nào nên gọi, và inputSchema cho biết công cụ cần đầu vào gì (ở đây là một chuỗi name).
  • Hàm async ở cuối là phần việc thật sự: nhận tên, trả lại nội dung chữ.
  • StdioServerTransport là đường kết nối qua stdio. Lệnh server.connect nối server vào đường đó.

README chưa ghi cụ thể lệnh để biên dịch và chạy file này. Cách làm từng bước từ npm init tới lúc gọi được tool nằm trong hướng dẫn "Build your first server" (xây server đầu tiên, một server cảnh báo thời tiết qua stdio) trong thư mục docs/ của repo và trên trang tài liệu của dự án.

IV.Kiểm tra đã chạy được chưa

Vì đây là thư viện, "cài thành công" nghĩa là hai việc. Một là lệnh npm install kết thúc không báo lỗi. Hai là code của bạn import được các gói mà không bị báo "không tìm thấy module".

Cách kiểm tra đầy đủ nhất là làm theo cặp hướng dẫn trong README: dựng server, rồi dựng client để kết nối vào server, liệt kê các tool và gọi thử. Nếu client in ra được tool greet hoặc tool của hướng dẫn thời tiết và nhận về kết quả, nghĩa là mọi thứ đã chạy đúng.

Bạn cũng có thể xem thư mục examples/. README mô tả đây là các cặp client/server "tự kiểm tra" (self-verifying), nên chạy một cặp là biết ngay môi trường của bạn ổn chưa. Lệnh chạy chi tiết nằm trong examples/README.md, README chính không chép lại.

V.Dùng vào việc thật

A.Lập trình viên đưa dữ liệu nội bộ cho AI

Bạn là dev ở một công ty nhỏ, có file hoặc hệ thống chứa danh sách sản phẩm và tồn kho. Bạn muốn đồng nghiệp hỏi AI "mặt hàng này còn bao nhiêu" mà không phải mở hệ thống.

Cách làm: cài @modelcontextprotocol/server, copy ví dụ greet, đổi tên tool thành tra_ton_kho, đổi inputSchema thành mã sản phẩm, và trong hàm xử lý thì đọc dữ liệu thật rồi trả về dạng chữ. Cấu trúc code giữ nguyên như ví dụ. Kết quả: một MCP server mà các ứng dụng AI hỗ trợ MCP có thể gọi.

Viết server MCP đầu tiên ngắn hơn bạn tưởng: một tool, một schema, một hàm trả chữ.

Ông T

B.Dev web muốn gắn MCP vào ứng dụng Express có sẵn

Bạn đã có một web app chạy Express và muốn nó vừa phục vụ web, vừa phục vụ MCP qua HTTP. Không cần dựng hệ thống riêng.

Cách làm: cài thêm gói middleware tương ứng bằng lệnh có trong README:

Terminal
npm install @modelcontextprotocol/express express

Gói này cung cấp phần thiết lập mặc định cho app và kiểm tra Host header (README mô tả như vậy). Cách gắn cụ thể xem trong packages/middleware/README.md. Kết quả: MCP và web chạy chung một dự án, bạn không phải viết lại phần web.

C.Người làm nội bộ viết client để thử server

Bạn đã có (hoặc ai đó đã viết) một MCP server, và muốn kiểm tra nó có những công cụ gì trước khi đưa cho cả phòng dùng. Cài gói client:

Terminal
npm install @modelcontextprotocol/client

Rồi làm theo hướng dẫn "Build your first client" trong tài liệu: kết nối tới server, liệt kê tool, gọi thử một tool. Kết quả: bạn biết chắc server trả lời đúng trước khi giao cho người khác dùng.

D.Người mới học MCP tự thực hành

Bạn chưa viết MCP bao giờ và muốn hiểu nó chạy ra sao. Hãy làm theo thứ tự: chép ví dụ greet trong README, sau đó làm hướng dẫn thời tiết, rồi mở examples/ xem từng cặp client/server. Mỗi thư mục trong examples/ kể một câu chuyện riêng, nên bạn học dần từ đơn giản tới phức tạp. Kết quả sau một buổi: bạn hiểu server, client, tool và transport khác nhau thế nào.

VI.Lỗi hay gặp và cách xử lý

README có trỏ tới một mục Troubleshooting (các lỗi thường gặp và cách sửa) trong tài liệu của repo. Dưới đây là những lỗi rất dễ xảy ra với loại thư viện này.

  • Báo thiếu module hoặc "Cannot find module". Thường do bạn chạy npm install ở sai thư mục, hoặc chưa cài gói Zod mà ví dụ đang import. Hãy mở terminal đúng thư mục dự án (nơi có package.json) và cài lại gói còn thiếu.
  • Node.js quá cũ. package.json yêu cầu Node từ phiên bản 20. Gõ node --version để kiểm tra. Nếu thấp hơn thì cập nhật Node.js rồi cài lại.
  • Cài nhầm gói theo hướng dẫn cũ. Nhiều bài trên mạng nhắc @modelcontextprotocol/sdk, đó là dòng v1. Nhánh main hiện là v2 với hai gói server và client. Code viết cho v1 có thể không chạy nguyên xi trên v2, hãy xem hướng dẫn nâng cấp của dự án.
  • Server chạy qua stdio mà không thấy in gì. Đây thường là bình thường. Với stdio, server chờ một ứng dụng hoặc client nói chuyện với nó, nên nó không tự in lời chào ra màn hình. Hãy kiểm tra bằng client như hướng dẫn thay vì chờ thông báo.
  • Lỗi khi gắn vào Express, Fastify hoặc Hono. Các gói middleware có kiểm tra Host header (README nhắc như vậy), nên truy cập bằng tên miền hoặc địa chỉ lạ có thể bị từ chối. Hãy đọc packages/middleware/README.md và mục Troubleshooting để biết cách cấu hình.

VII.Có nên dùng không

Điểm mạnh:

  • Là SDK chính thức, do chính nhóm làm ra chuẩn MCP duy trì, nên bám sát đặc tả.
  • Có đủ cả server lẫn client, nhiều transport, có hỗ trợ xác thực.
  • Chạy được trên Node.js, Bun và Deno.
  • Có sẵn nhiều ví dụ chạy được và hướng dẫn từng bước.
  • Repo vẫn được cập nhật trong vài tháng gần đây.

Giới hạn:

  • Đây là thư viện cho người viết code. Bạn không viết TypeScript thì khó dùng.
  • Dự án đang chuyển từ v1 sang v2, nên tài liệu và bài hướng dẫn cũ trên mạng dễ gây nhầm lẫn.
  • README chính khá ngắn: lệnh chạy chi tiết nằm ở tài liệu và thư mục examples/, bạn phải đọc thêm.

Khi nào chọn cách khác: nếu bạn chỉ muốn dùng các MCP server làm sẵn thì không cần cài SDK này, chỉ cần cấu hình trong ứng dụng AI của bạn. Nếu nhóm bạn viết bằng ngôn ngữ khác, hãy tìm SDK cho ngôn ngữ đó. Còn nếu bạn dùng TypeScript và muốn tự làm công cụ cho AI, đây là điểm bắt đầu hợp lý nhất.

4.1/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

Câu hỏi thường gặp

typescript-sdk có miễn phí không?

README ghi dự án dùng giấy phép Apache License 2.0 cho các đóng góp mới, còn phần code cũ theo giấy phép MIT. Chi tiết xem file LICENSE trong repo. Tư liệu không nhắc tới phí sử dụng, và việc cài thư viện bằng npm không cần tài khoản trả phí theo những gì README nói.

Dùng typescript-sdk có cần GPU hay máy mạnh không?

Tư liệu không nêu yêu cầu phần cứng đặc biệt nào, và cũng không nhắc tới GPU. Điều kiện duy nhất ghi rõ là Node.js từ phiên bản 20 trở lên. SDK này lo phần giao thức kết nối chứ không chạy mô hình AI.

Chạy trên Windows được không?

README nói SDK chạy trên Node.js, Bun và Deno, nhưng không liệt kê hệ điều hành cụ thể. Tư liệu chưa có thông tin riêng về Windows. Bạn cứ cài Node.js từ phiên bản 20 trở lên rồi thử các lệnh npm install như hướng dẫn.

Khác gì giữa gói server, gói client và gói sdk?

Nhánh main (v2) tách làm hai gói: `@modelcontextprotocol/server` để xây server và `@modelcontextprotocol/client` để xây client. Gói `@modelcontextprotocol/sdk` là của dòng v1 ở nhánh v1.x, vẫn nhận sửa lỗi và vá bảo mật trong ít nhất sáu tháng sau khi v2 phát hành. Nếu bắt đầu dự án mới, bạn nên dùng v2.

Cần thư viện nào để khai báo đầu vào của tool?

SDK dùng chuẩn Standard Schema, nên bạn có thể dùng Zod v4, Valibot, ArkType hoặc thư viện nào tương thích. Ví dụ trong README dùng Zod v4. README không ghi lệnh cài Zod, bạn cần tự cài thêm khi làm theo ví dụ.

Dữ liệu của tôi có an toàn khi dùng SDK này không?

Tư liệu không có phần nào nói về việc gửi dữ liệu ra ngoài. Server bạn viết chạy bằng code của chính bạn, nên mức an toàn phụ thuộc vào cách bạn viết và cấu hình. Repo có file SECURITY.md để xem quy trình báo lỗi bảo mật, và SDK có các hàm hỗ trợ xác thực cho server lẫn client.

Học cách dùng ở đâu cho dễ?

README trỏ tới hai hướng dẫn từng bước: xây server đầu tiên (server cảnh báo thời tiết qua stdio, từ `npm init` đến lúc gọi tool) và xây client đầu tiên. Ngoài ra có thư mục `examples/` chứa các cặp client/server chạy được, cùng trang tài liệu đầy đủ và API reference của dự án.

Chuyển nhanh tới mục

  1. I.typescript-sdk làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Kiểm tra Node.js
    2. B.Tạo thư mục dự án
    3. C.Cài gói server hoặc client
    4. D.Cài thêm middleware (nếu cần)
    5. E.Chép ví dụ greet
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Lập trình viên đưa dữ liệu nội bộ cho AI
    2. B.Dev web muốn gắn MCP vào ứng dụng Express có sẵn
    3. C.Người làm nội bộ viết client để thử server
    4. D.Người mới học MCP tự thực hành
  6. VI.Lỗi hay gặp và cách xử lý
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.