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). Bạn dùng nó để viết MCP server (đưa công cụ, dữ liệu cho AI) hoặc MCP client (kết nối tới server). Cài bằng một dòng npm, nhưng bạn cần biết viết code TypeScript cơ bản.

typescript-sdk là bộ thư viện TypeScript chính thức của Model Context Protocol (MCP). Bạn dùng nó để tự viết MCP server, tức là một chương trình nhỏ đưa công cụ và dữ liệu của bạn cho AI dùng, hoặc MCP client để kết nối tới các server đó. Repo hiện có khoảng 13.754 sao và 2.382 fork, và vẫn được cập nhật trong vài tháng gần đây.

MCP là một chuẩn chung để ứng dụng AI "nói chuyện" với công cụ bên ngoài. Thay vì mỗi AI một kiểu kết nối riêng, bạn viết server MCP một lần, rồi các ứng dụng hỗ trợ MCP đều có thể dùng. Ví dụ bạn muốn AI tra được tồn kho trong file của shop, hoặc gọi được một hàm nội bộ của công ty. Bạn đóng gói chúng thành "tool" trong một MCP server.

Bài này dành cho lập trình viên mới và người làm kỹ thuật trong doanh nghiệp, đã quen mở terminal và sửa vài dòng code. Điểm đáng giá nhất là đây là SDK do chính dự án MCP phát hành. Nó chạy được trên Node.js, Bun và Deno, và đủ cả phía server lẫn phía client. Nếu bạn chưa từng viết code thì đây chưa phải công cụ dùng ngay. Nó là nguyên liệu để bạn (hoặc đồng nghiệp lập trình) làm ra công cụ.

Thư viện

modelcontextprotocol/typescript-sdk

SDK TypeScript chính thức của Model Context Protocol, giúp bạn tự viết MCP server và client để AI kết nối với công cụ và dữ liệu của bạn.

★ 14kTypeScript
Xem repo trên GitHub

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

Repo này là một monorepo, tức là một kho chứa nhiều gói nhỏ. Các phần chính:

  • Thư viện server (@modelcontextprotocol/server)giúp bạn khai báo tool, resource và prompt cho AI. Server nói chuyện qua stdio (chạy ngay trên máy bạn) hoặc Streamable HTTP (chạy như một dịch vụ web). Có cả phần hỗ trợ xác thực (auth helpers).
  • Thư viện client (@modelcontextprotocol/client)giúp bạn viết chương trình kết nối tới một MCP server, liệt kê tool nó có và gọi thử. Có hỗ trợ OAuth khi server yêu cầu đăng nhập.
  • Gói middleware (không bắt buộc)các adapter mỏng để gắn MCP vào framework bạn đang dùng. Hiện có gói cho Node.js HTTP (@modelcontextprotocol/node), Express, Fastify và Hono. Nếu web của bạn đã chạy bằng một trong các framework này, bạn đỡ phải tự nối.
  • Schema theo chuẩn Standard Schemabạn có thể dùng Zod v4, Valibot, ArkType hoặc thư viện tương thích để mô tả dữ liệu đầu vào của tool. Bạn không bị ép dùng một thư viện duy nhất.
  • Ví dụ chạy được (examples/)mỗi thư mục là một cặp client/server hoàn chỉnh, tự kiểm tra được. Đây là chỗ học nhanh nhất.
  • Tài liệu và tutorialcó hướng dẫn từng bước dựng server đầu tiên (một server báo thời tiết qua stdio) và client đầu tiên, cùng trang tài liệu đầy đủ, phần xử lý sự cố và API reference.

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

  • Node.js phiên bản 20 trở lênfile package.json của repo yêu cầu Node >=20. README cũng nói SDK chạy được trên Bun và Deno nếu bạn thích dùng hai môi trường đó.
  • Một trình quản lý góiREADME đưa lệnh cho npm, Bun và Deno. Người mới cứ dùng npm, đi kèm với Node.js.
  • Một dự án TypeScript/JavaScriptREADME nhắc đến bước npm init trong tutorial. Bạn cần một thư mục dự án để cài thư viện vào.
  • Thư viện mô tả schemaví dụ mẫu dùng Zod v4 (zod/v4). README không ghi riêng lệnh cài Zod, nên hãy xem tutorial "Build your first server" để biết dự án cần những gì.
  • Hệ điều hành, tài khoản, API key, GPUtư liệu không yêu cầu gì thêm. Bản thân SDK không bắt buộc tài khoản hay key. Nhưng nếu server của bạn gọi dịch vụ bên thứ ba thì dịch vụ đó có thể cần key riêng.

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

  1. Mở terminal trong thư mục dự ánDùng thư mục dự án Node.js của bạn (bản 20 trở lên)
  2. Cài gói serverChạy npm install @modelcontextprotocol/server nếu bạn muốn viết server
  3. Cài gói clientChạy npm install @modelcontextprotocol/client nếu bạn muốn viết client
  4. Cài middleware nếu cầnChỉ khi bạn dùng Express, Fastify, Hono hoặc Node.js HTTP
  5. Chép ví dụ greet vào fileDán đoạn code mẫu của README rồi chạy theo tutorial

A.Mở terminal đúng chỗ

Bạn cần một thư mục dự án có sẵn package.json. Nếu chưa có, tutorial của repo bắt đầu từ lệnh npm init. Trên Windows, bạn mở PowerShell rồi dùng cd để vào đúng thư mục. Chỗ người mới hay vấp là chạy lệnh cài ở thư mục khác, khiến thư viện nằm sai chỗ.

Nếu muốn xem ví dụ có sẵn của repo, bạn tải về trước:

Terminal
git clone https://github.com/modelcontextprotocol/typescript-sdk.git
cd typescript-sdk

Lệnh đầu tải toàn bộ mã nguồn về máy. Lệnh thứ hai đi vào thư mục vừa tải. README chưa ghi cách chạy riêng từng ví dụ, nên bạn xem examples/README.md trong repo để biết cách chạy.

B.Cài gói server

Đây là gói để viết MCP server. README đưa ba cách tùy môi trường, bạn chỉ chọn một:

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

Dòng đầu dùng npm. Dòng hai dùng Bun. Dòng ba dùng Deno. Dòng bắt đầu bằng # chỉ là chú thích, bạn không cần gõ.

C.Cài gói client

Gói này để viết chương trình kết nối tới MCP server:

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

D.Cài middleware (tùy chọn)

Chỉ cài khi bạn muốn đưa MCP server lên web bằng framework quen thuộc. Chọn đúng dòng bạn cần:

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

Ví dụ gói Express cài kèm cả express, vì gói middleware chỉ là adapter, không tự mang framework theo. Chi tiết nằm trong packages/middleware/README.md.

E.Chép ví dụ greet

Đây là một server nhỏ nhất, chỉ có một tool tên greet, giao tiếp qua stdio. Đoạn code này lấy nguyên từ README:

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 nhanh từng phần:

  • new McpServer(...) tạo server với tên và phiên bản do bạn đặt.
  • registerTool('greet', ...) đăng ký một tool. description là mô tả để AI hiểu khi nào nên gọi tool. inputSchema quy định tool nhận đầu vào gì, ở đây là một chuỗi name.
  • Hàm async ở cuối là phần xử lý. Nó nhận tên và trả về câu chào.
  • StdioServerTransport và server.connect(...) mở kênh stdio để ứng dụng AI nói chuyện với server.

README không ghi lệnh chạy file này. Hãy làm theo tutorial "Build your first server" (từ npm init đến lúc gọi tool) để biết cấu hình TypeScript và cách chạy.

MCP server là code chạy trên máy hoặc máy chủ của bạn, và AI có thể gọi các tool bạn khai báo. Chỉ đưa vào tool những việc bạn chấp nhận cho AI làm (đọc file nào, gọi API nào). Đừng ghi API key thẳng trong code rồi đưa lên GitHub công khai.

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

Tư liệu không nêu một dòng kết quả cố định sau khi cài. Bạn có thể kiểm tra theo ba mức:

  • Cài thành cônglệnh npm install kết thúc không báo lỗi, và gói xuất hiện trong package.json của dự án.
  • Code biên dịch đượcđoạn ví dụ greet import được McpServer và StdioServerTransport mà không báo lỗi thiếu module.
  • Chạy đúng như mong đợiREADME đề cập tutorial client, nơi bạn kết nối tới server, liệt kê tool và gọi chúng. Nếu client thấy tool greet và trả về Hello, <tên>! thì server đã hoạt động. Ngoài ra thư mục examples/ có các cặp client/server tự kiểm tra.

Lưu ý: server stdio thường đứng yên chờ client nối vào, nên khi tự chạy nó có thể không in gì ra. Đây là bình thường, không phải treo.

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

SDK chỉ là nền để bạn xây công cụ. Các tình huống dưới đây dựa đúng vào khả năng server/client mà README mô tả. Phần code cụ thể bạn tự viết theo tutorial.

SDK không làm sẵn công cụ cho bạn. Nó cho bạn đường ống chuẩn để AI cắm vào công cụ của chính bạn.

Ông T

A.Dev trong công ty: đưa hàm nội bộ cho AI dùng

Bối cảnh: bạn là lập trình viên, công ty có sẵn hàm tra cứu đơn hàng. Bạn cài @modelcontextprotocol/server, rồi đăng ký hàm đó thành một tool giống ví dụ greet: có description rõ ràng, inputSchema mô tả mã đơn, và hàm xử lý trả về nội dung dạng text. Kết quả là ứng dụng AI hỗ trợ MCP có thể gọi tool này khi nhân viên hỏi về một đơn hàng.

B.Chủ shop có đội kỹ thuật: tool đơn giản trước, mở rộng sau

Bối cảnh: bạn muốn thử MCP nhưng chưa biết bắt đầu từ đâu. Cách an toàn nhất là làm đúng tutorial "Build your first server", một server báo cảnh báo thời tiết qua stdio. Làm xong, đổi nội dung tool sang việc của shop bạn, ví dụ trả về thông tin trong một tệp dữ liệu. Chạy trên máy của bạn qua stdio nên dữ liệu không phải đưa lên máy chủ nào khác.

C.Dev web: gắn MCP vào ứng dụng Express có sẵn

Bối cảnh: dịch vụ web của bạn đã chạy bằng Express. Bạn cài thêm gói middleware:

Terminal
npm install @modelcontextprotocol/express express

README mô tả gói này gồm cài đặt mặc định cho app và kiểm tra Host header. Server đi qua Streamable HTTP nên nhiều người dùng có thể kết nối thay vì chỉ một máy cục bộ. Cách nối cụ thể xem packages/middleware/README.md và tài liệu trên trang chính thức.

D.Dev làm ứng dụng AI: viết client để gọi nhiều server

Bối cảnh: bạn đang làm một ứng dụng và muốn nó dùng được các MCP server có sẵn. Bạn cài @modelcontextprotocol/client, theo tutorial "Build your first client": kết nối tới server, liệt kê tool, rồi gọi từng tool. Nếu server yêu cầu đăng nhập, SDK có sẵn phần hỗ trợ OAuth để bạn khỏi tự viết từ đầu.

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

README có một mục Troubleshooting riêng (trong repo/tài liệu). Dưới đây là những lỗi rất dễ gặp với loại công cụ này.

  • Cài nhầm gói hoặc nhầm phiên bảnnhánh main là v2 với hai gói @modelcontextprotocol/server và @modelcontextprotocol/client. Bản v1 là gói @modelcontextprotocol/sdk nằm ở nhánh v1.x và có tài liệu riêng. Nếu bạn làm theo hướng dẫn cũ trên mạng, hãy kiểm tra xem nó nói về v1 hay v2, và xem hướng dẫn nâng cấp (migration guide) khi chuyển từ v1 sang v2.
  • Node quá cũrepo yêu cầu Node 20 trở lên. Chạy node --version để kiểm tra. Nếu thấp hơn, hãy cập nhật Node trước khi cài.
  • Chạy lệnh sai thư mụclỗi "không tìm thấy module" thường do bạn cài thư viện ở thư mục này nhưng chạy code ở thư mục khác. Hãy cài và chạy trong cùng thư mục dự án.
  • Thiếu thư viện schemaví dụ mẫu import zod/v4. Nếu báo không tìm thấy, dự án của bạn chưa có Zod hoặc bản Zod chưa phù hợp. Xem tutorial để biết bản cần dùng, hoặc đổi sang thư viện tương thích Standard Schema khác.
  • Server stdio "không phản hồi" khi chạy tayđó là hành vi thường gặp, vì nó chờ client gửi yêu cầu. Hãy kiểm tra bằng client trong tutorial thay vì nhìn terminal.

Gặp lỗi lạ, bạn xem mục Troubleshooting của repo, hoặc mở issue trên GitHub theo mẫu repo cung cấp.

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

Điểm mạnh

  • Là SDK chính thức của MCP, nên bám sát chuẩn.
  • Có cả server lẫn client, chạy trên Node.js, Bun và Deno.
  • Tài liệu có tutorial từng bước, ví dụ chạy được và API reference.
  • Có adapter cho Express, Fastify, Hono và Node.js HTTP.
  • Cho bạn chọn thư viện schema (Zod v4, Valibot, ArkType...).

Giới hạn

  • Đây là thư viện cho lập trình viên, không phải ứng dụng bấm là chạy. Bạn cần biết TypeScript ở mức cơ bản.
  • Có hai dòng phiên bản (v1 và v2) với tên gói khác nhau, nên tài liệu cũ có thể gây nhầm.
  • README chưa ghi lệnh chạy ví dụ greet, bạn phải đọc thêm tutorial.
  • Giấy phép: README ghi Apache License 2.0 cho đóng góp mới và MIT cho mã cũ. Nếu dùng trong sản phẩm thương mại, hãy đọc file LICENSE trong repo.

Khi nào chọn cách khác: nếu bạn không viết code và chỉ muốn dùng MCP server làm sẵn, hãy tìm server có sẵn cho nhu cầu của bạn thay vì tự viết. Nếu bạn làm bằng ngôn ngữ khác, hãy xem trang MCP để tìm SDK phù hợp. Còn nếu bạn là dev TypeScript muốn đưa công cụ của mình cho AI dùng theo chuẩn chung, repo này là điểm bắt đầu hợp lý.

4.0/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 theo giấy phép Apache License 2.0 cho đóng góp mới và MIT cho mã hiện có. Chi tiết xem file LICENSE trong repo. Tư liệu không nói gì về chi phí của dịch vụ bên ngoài mà server của bạn có thể gọi.

Cần Node.js bản nào để dùng?

File package.json của repo yêu cầu Node 20 trở lên. README cho biết SDK cũng chạy được trên Bun và Deno.

Cài gói nào: server hay client?

Tùy bạn muốn làm gì. Muốn đưa công cụ cho AI dùng thì cài @modelcontextprotocol/server. Muốn viết chương trình kết nối tới MCP server thì cài @modelcontextprotocol/client. Có thể cài cả hai.

Khác gì giữa v1 và v2 của SDK?

Nhánh main là v2 với hai gói @modelcontextprotocol/server và @modelcontextprotocol/client. v1 dùng gói @modelcontextprotocol/sdk, nằm ở nhánh v1.x và vẫn nhận sửa lỗi, cập nhật bảo mật trong ít nhất sáu tháng sau khi v2 ra mắt. Chuyển từ v1 sang v2 thì xem migration guide trên trang tài liệu.

Có chạy được trên Windows không, có cần GPU không?

Tư liệu không nêu yêu cầu hệ điều hành hay GPU. SDK là thư viện TypeScript chạy trên Node.js, Bun hoặc Deno, nên về nguyên tắc chỉ cần môi trường chạy các công cụ đó. Bạn nên tự thử trên máy mình.

Dữ liệu của tôi có an toàn không?

Tư liệu chưa có thông tin chi tiết về vấn đề này. Về nguyên tắc, server bạn viết chạy ở đâu thì dữ liệu nằm ở đó, và AI chỉ làm được những gì bạn khai báo thành tool. Repo có file SECURITY.md, bạn nên đọc trước khi đưa vào sản phẩm thật.

Người không biết lập trình có dùng được không?

Khó. Đây là thư viện để lập trình viên viết code, không phải phần mềm bấm là chạy. Nếu bạn không viết code, hãy nhờ đồng nghiệp kỹ thuật hoặc tìm MCP server có sẵn cho việc của bạ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.Mở terminal đúng chỗ
    2. B.Cài gói server
    3. C.Cài gói client
    4. D.Cài middleware (tùy chọ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.Dev trong công ty: đưa hàm nội bộ cho AI dùng
    2. B.Chủ shop có đội kỹ thuật: tool đơn giản trước, mở rộng sau
    3. C.Dev web: gắn MCP vào ứng dụng Express có sẵn
    4. D.Dev làm ứng dụng AI: viết client để gọi nhiều server
  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ỏ.