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

> 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.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-06 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/typescript-sdk-viet-mcp-server-client-typescript

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ụ.

```repo
- repo | modelcontextprotocol/typescript-sdk
- kind | Thư viện
- desc | 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.
- stars | 14k
- lang | TypeScript
```

## 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 Schema**: bạ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à tutorial**: có 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.

## Cần chuẩn bị gì

- **Node.js phiên bản 20 trở lên**: file `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ói**: README đư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/JavaScript**: README 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ả schema**: ví 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, GPU**: tư 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.

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

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

### 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:

```bash
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.

### 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:

```bash
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ài gói client

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

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

### 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:

```bash
# 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`.

### 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.

```note
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.
```

## 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ông**: lệ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 đợi**: README đề 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.

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

### 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.

### 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.

### 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:

```bash
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.

### 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.

## 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ản**: nhá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ục**: lỗ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 schema**: ví 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.

## 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ý.

## 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.
