# modelcontextprotocol/typescript-sdk: xây MCP server và client — hướng dẫn cài đặt và dùng

> modelcontextprotocol/typescript-sdk là SDK TypeScript chính thức để xây MCP server và MCP client trên Node.js, Bun hoặc Deno. Bạn có thể tạo tool, resource, prompt, kết nối qua stdio hoặc Streamable HTTP và dùng OAuth helper. Cài đặt khá đơn giản nếu đã có Node.js từ 20 trở lên; phần khó chủ yếu nằm ở việc thiết kế MCP server và cấu hình ứng dụng kết nối.

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

modelcontextprotocol/typescript-sdk là SDK TypeScript chính thức để xây MCP server và MCP client theo Model Context Protocol (MCP). Repo cung cấp các thư viện giúp ứng dụng cung cấp context cho mô hình ngôn ngữ theo cách tiêu chuẩn, tách phần cung cấp dữ liệu và công cụ khỏi phần gọi LLM.

Repo phù hợp với lập trình viên TypeScript, đội ngũ muốn kết nối trợ lý AI với dữ liệu nội bộ, hoặc người đang xây công cụ tự động hóa cho doanh nghiệp. Mình đánh giá điểm đáng giá nhất là SDK đã tách riêng package server và client, có sẵn transport stdio, Streamable HTTP, helper OAuth, middleware cho nhiều framework và nhiều ví dụ có thể chạy.

Repo hiện có khoảng 13.758 sao và 2.383 fork. Đây là monorepo đang được cập nhật, với mã nguồn chính viết bằng TypeScript. Nếu bạn đang dùng thế hệ cũ, cần chú ý repo này có nhánh v2; package chính của v2 là `@modelcontextprotocol/server` và `@modelcontextprotocol/client`.

```repo
- repo | modelcontextprotocol/typescript-sdk
- kind | Thư viện
- desc | SDK TypeScript chính thức để xây MCP server và client, kết nối ứng dụng với công cụ, tài nguyên và prompt cho LLM.
- stars | 14k
- lang | TypeScript
```

## modelcontextprotocol/typescript-sdk làm được gì

- **Xây MCP server bằng TypeScript:** Bạn có thể tạo một server để công bố tool, resource và prompt cho ứng dụng AI. Ví dụ, server có thể cung cấp dữ liệu tồn kho, tra cứu đơn hàng, đọc tài liệu nội bộ hoặc gọi một API doanh nghiệp.

- **Đăng ký tool có schema đầu vào:** SDK cho phép mô tả tool và khai báo dữ liệu đầu vào bằng Standard Schema. README minh họa việc dùng Zod v4, đồng thời SDK cũng hỗ trợ Valibot, ArkType hoặc thư viện tương thích Standard Schema. Việc có schema giúp yêu cầu đầu vào rõ ràng hơn và giảm lỗi khi mô hình gọi tool.

- **Xây MCP client:** Package client giúp một ứng dụng kết nối tới MCP server, liệt kê các tool và gọi tool. Đây là phần phù hợp khi bạn muốn viết ứng dụng trung gian, trợ lý nội bộ hoặc một bộ kiểm thử cho MCP server.

- **Kết nối qua stdio:** Transport stdio phù hợp với server chạy cục bộ cùng máy với client. Đây là cách đơn giản để bắt đầu vì không cần dựng web server hay mở cổng mạng.

- **Phục vụ qua Streamable HTTP:** SDK có hỗ trợ Streamable HTTP cho trường hợp MCP server cần chạy như một dịch vụ. Cách này phù hợp khi nhiều client hoặc ứng dụng khác nhau cần truy cập cùng một server.

- **Dùng middleware theo framework:** Các package tùy chọn hỗ trợ Node.js HTTP, Express, Fastify và Hono. Chúng chủ yếu là adapter mỏng để nối MCP vào runtime hoặc framework có sẵn, không tự thêm business logic.

- **Hỗ trợ xác thực và OAuth:** README liệt kê auth helpers ở phía server và OAuth helpers ở phía client. Đây là nền tảng hữu ích khi MCP server cần kiểm soát người dùng hoặc kết nối tới dịch vụ yêu cầu đăng nhập.

- **Có ví dụ chạy được:** Thư mục `examples/` chứa các cặp ví dụ client/server có thể chạy và tự kiểm tra. Mỗi thư mục minh họa một câu chuyện sử dụng riêng, giúp bạn xem cách ghép các thành phần thay vì chỉ đọc API rời rạc.

- **Có tài liệu cho cả server và client:** Repo có hướng dẫn xây server, xây client, tài liệu về tool, resource, prompt, HTTP, stdio, OAuth và chuyển từ v1 lên v2. Phần `docs/` cũng có cấu hình để dựng tài liệu cục bộ.

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

- **Node.js từ phiên bản 20 trở lên:** `package.json` yêu cầu Node `>=20`. Đây là yêu cầu quan trọng nhất nếu bạn dùng các lệnh cài đặt bằng npm.

- **Một môi trường chạy JavaScript hoặc TypeScript:** SDK chạy trên Node.js, Bun và Deno. README đưa ra lệnh cài package tương ứng cho cả ba môi trường.

- **npm, Bun hoặc Deno:** Bạn chỉ cần dùng một trình quản lý package phù hợp với runtime của mình. Ví dụ bên dưới ưu tiên npm vì đây là lựa chọn quen thuộc với người mới.

- **Một dự án TypeScript hoặc JavaScript:** README minh họa server bằng TypeScript. Bạn cần có nơi để đặt mã nguồn server hoặc client của mình.

- **Thư viện schema nếu dùng schema trong tool:** Ví dụ chính thức dùng Zod v4. README cũng nói SDK chấp nhận Valibot, ArkType hoặc thư viện tương thích Standard Schema.

- **Tài khoản, API key và phần cứng:** README không yêu cầu tài khoản, API key, GPU hay phần cứng đặc biệt cho việc cài SDK. Nếu tool do bạn viết gọi một dịch vụ bên ngoài, yêu cầu xác thực của dịch vụ đó sẽ phụ thuộc vào chính dịch vụ, không phải thông tin được nêu trong README này.

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

```steps
- Chọn runtime | Dùng Node.js, Bun hoặc Deno; với Node.js cần phiên bản từ 20
- Tạo dự án | Mở terminal trong thư mục dự án TypeScript hoặc JavaScript
- Cài package server hoặc client | Cài đúng package theo phần bạn muốn xây
- Cài middleware nếu cần | Chỉ thêm package framework khi tích hợp Express, Fastify, Hono hoặc Node.js HTTP
- Tạo thành phần MCP đầu tiên | Dùng ví dụ server tối giản hoặc xem các ví dụ trong thư mục examples
```

### Chọn runtime và mở terminal

README xác nhận SDK chạy trên Node.js, Bun và Deno. Với người mới, Node.js thường là lựa chọn dễ theo dõi nhất. Hãy kiểm tra phiên bản Node trước khi cài. `node --version` là lệnh phổ thông để xem phiên bản hiện tại; phiên bản cần đáp ứng yêu cầu `>=20` ghi trong `package.json`.

Mở PowerShell hoặc Terminal tại thư mục dự án của bạn. Nếu chưa có dự án, bạn có thể tạo một thư mục riêng rồi mở terminal tại đó. README không đưa ra toàn bộ lệnh khởi tạo dự án, vì vậy phần khởi tạo cụ thể có thể tùy theo công cụ TypeScript bạn đang dùng.

Nếu muốn lấy mã nguồn repo để đọc ví dụ, có thể dùng lệnh phổ thông sau:

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

Lệnh đầu tiên tải mã nguồn về máy. Lệnh thứ hai đi vào thư mục repo. Bạn không bắt buộc phải clone repo nếu chỉ muốn cài SDK vào dự án riêng bằng npm, Bun hoặc Deno.

### Cài package server

Nếu mục tiêu là xây MCP server, cài package server bằng npm:

```bash
npm install @modelcontextprotocol/server
```

Lệnh này thêm package `@modelcontextprotocol/server` vào dự án hiện tại. Hãy chạy lệnh trong đúng thư mục có dự án của bạn, không chạy nhầm ở một thư mục khác. Sau khi cài, bạn có thể import `McpServer` và `StdioServerTransport` như ví dụ trong README.

Nếu bạn dùng Bun hoặc Deno, README đưa ra hai lựa chọn sau:

```bash
bun add @modelcontextprotocol/server
deno add npm:@modelcontextprotocol/server
```

Chọn một lệnh theo runtime của bạn. Không cần chạy cả ba lệnh cho cùng một dự án.

### Cài package client

Nếu bạn muốn viết ứng dụng kết nối tới MCP server, cài package client:

```bash
npm install @modelcontextprotocol/client
```

README cũng nêu cách cài bằng Bun và Deno:

```bash
bun add @modelcontextprotocol/client
deno add npm:@modelcontextprotocol/client
```

Package client dành cho phần kết nối, transport, helper cấp cao và OAuth helper. Nếu cùng một dự án vừa tạo server vừa tạo client, hãy xem hướng dẫn của repo để xác định cách tổ chức package phù hợp.

### Cài package middleware tùy chọn

Bạn chỉ cần cài middleware khi muốn nối MCP vào runtime hoặc web framework cụ thể. Các package này là adapter mỏng, không thay thế phần logic nghiệp vụ của ứng dụng.

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

`@modelcontextprotocol/node` hỗ trợ wrapper Streamable HTTP cho `IncomingMessage` và `ServerResponse`. Với Express, Fastify hoặc Hono, README yêu cầu cài cả package middleware của MCP và framework tương ứng.

### Tạo MCP server tối giản

README cung cấp ví dụ server stdio có một tool tên `greet`. Mã dưới đây tạo server, khai báo schema đầu vào và trả về lời chào:

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

`McpServer` là đối tượng server. `registerTool` đăng ký tool với tên, mô tả và schema đầu vào. Ở đây, tool yêu cầu trường `name` là chuỗi. Hàm xử lý nhận `name` rồi trả về nội dung văn bản. `StdioServerTransport` kết nối server qua stdio.

Bạn cần cài package schema tương ứng nếu dùng đúng ví dụ Zod trong README. README nói rõ schema của SDK dùng Standard Schema và ví dụ dùng Zod v4, nhưng phần lệnh cài Zod riêng không được đưa ra trong nội dung được cung cấp. Vì vậy, hãy xem tutorial hoặc `package.json` của ví dụ trong repo để biết cách cài đầy đủ cho dự án cụ thể.

### Xem tutorial và ví dụ end-to-end

Sau khi cài package, hãy mở phần hướng dẫn xây server và xây client trong tài liệu của repo. README giới thiệu tutorial tạo server cảnh báo thời tiết qua stdio, bắt đầu từ `npm init` đến lúc gọi tool. Repo cũng có `examples/README.md` và các ví dụ client/server có thể chạy, tự kiểm tra.

README chưa ghi một lệnh chạy chung cho toàn bộ ví dụ trong phần nội dung được cung cấp. Vì vậy, bạn nên mở `examples/README.md` và `package.json` trong từng ví dụ để dùng đúng script của ví dụ đó, thay vì tự đoán tên lệnh.

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

Có ba cách kiểm tra theo đúng thông tin README cung cấp.

Trước hết, kiểm tra môi trường. Nếu dùng Node.js, phiên bản phải đáp ứng `>=20`, vì đây là điều kiện trong `package.json`. Sau đó kiểm tra package đã được thêm vào dự án bằng cách xem file khai báo dependency của dự án.

Tiếp theo, chạy server tối giản trong tutorial hoặc ví dụ. Kết quả mong đợi là server kết nối thành công với `StdioServerTransport` mà không báo lỗi import, lỗi phiên bản Node hoặc lỗi schema. README mô tả server này có một tool `greet`.

Cuối cùng, dùng client tương ứng để kết nối, liệt kê tool và gọi tool. Với ví dụ `greet`, kết quả mong đợi là nội dung `Hello, <tên>!`. Các ví dụ trong `examples/` được mô tả là runnable và self-verifying, nhưng README được cung cấp không nêu một lệnh chạy duy nhất cho mọi thư mục. Hãy dùng hướng dẫn trong từng ví dụ.

Nếu bạn đang phát triển tài liệu của repo, có thể kiểm tra các script dựng docs bằng những lệnh README cung cấp:

```bash
pnpm docs:api
pnpm docs:dev
pnpm docs:build
pnpm docs:multi
```

Các script này lần lượt tạo API reference, khởi động VitePress dev server cho site v2, build site v2 và build site kết hợp. Đây là kiểm tra cho tài liệu, không phải quy trình bắt buộc để chạy một MCP server.

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

### Chủ shop tra cứu tồn kho bằng trợ lý AI

Chủ shop có thể xây một MCP server với tool `check_inventory`. Tool nhận mã sản phẩm, truy vấn hệ thống quản lý hàng và trả về số lượng còn lại. Schema đầu vào nên yêu cầu mã sản phẩm là chuỗi, tương tự cách README dùng `z.object({ name: z.string() })` cho tool `greet`.

Server có thể chạy cục bộ qua stdio nếu chỉ dùng trên máy của chủ shop. Trợ lý AI kết nối qua MCP client, liệt kê tool và gọi `check_inventory` khi người dùng hỏi “mặt hàng này còn bao nhiêu?”. Kết quả nên là thông tin tồn kho có cấu trúc rõ ràng để người dùng quyết định nhập thêm hàng.

### Nhân viên văn phòng tra cứu tài liệu nội bộ

Một đội ngũ có thể tạo resource hoặc tool để tìm tài liệu quy trình, chính sách hoặc biểu mẫu. MCP server chịu trách nhiệm cung cấp context; ứng dụng AI chịu trách nhiệm tương tác với người dùng và xử lý câu hỏi.

Nếu server cần được nhiều người truy cập, có thể phục vụ qua Streamable HTTP và dùng middleware cho Node.js HTTP, Express, Fastify hoặc Hono. README mô tả các middleware này là adapter để nối MCP vào framework, nên phần phân quyền và logic tìm kiếm vẫn cần được bạn thiết kế trong ứng dụng.

### Lập trình viên xây bộ công cụ cho nhóm phát triển

Một dev có thể tạo server gồm các tool như đọc trạng thái build, xem log kiểm thử hoặc tra cứu quy ước code. Client kết nối tới server, liệt kê các tool rồi gọi đúng tool khi cần. Cách tách server và client giúp nhóm thay đổi phần dữ liệu hoặc hệ thống nội bộ mà không phải viết lại toàn bộ ứng dụng AI.

Khi bắt đầu, hãy dùng server `greet` trong README để kiểm tra luồng stdio trước. Sau khi luồng cơ bản hoạt động, thay phần xử lý lời chào bằng logic thật của nhóm. Đây là cách giảm số lượng điểm lỗi khi tích hợp.

### Đội ngũ cần kết nối dịch vụ có đăng nhập

Nếu MCP server hoặc client phải làm việc với dịch vụ yêu cầu xác thực, hãy xem auth helpers ở phía server và OAuth helpers ở phía client. README liệt kê các helper này nhưng không cung cấp trong nội dung hiện tại một cấu hình OAuth hoàn chỉnh hay tên biến môi trường cụ thể.

Vì vậy, không nên tự bịa cấu hình key hoặc callback URL. Hãy theo tutorial OAuth và tài liệu API của phiên bản SDK bạn đang dùng, đồng thời chỉ cấp quyền tối thiểu cho server.

> MCP giúp bạn tách phần cung cấp dữ liệu và công cụ khỏi phần tương tác với LLM.
>
> — Ông T

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

### Node.js quá cũ

Lỗi có thể xuất hiện khi cài hoặc chạy package nếu Node.js không đáp ứng `>=20`. Hãy kiểm tra phiên bản Node và nâng cấp theo cách phù hợp với máy của bạn. Không nên cố bỏ qua điều kiện trong `package.json` vì có thể phát sinh lỗi khó đoán ở runtime.

### Cài nhầm package v1 và v2

README phân biệt v2 với dòng v1.x. V2 dùng `@modelcontextprotocol/server` và `@modelcontextprotocol/client`, còn package cũ `@modelcontextprotocol/sdk` thuộc dòng v1.x. Nếu mã nguồn hoặc tutorial của bạn dùng import khác, hãy xác định mình đang theo tài liệu v1 hay v2 trước khi sửa code.

### Import không khớp với package đã cài

Một lỗi dễ gặp là cài client nhưng lại import API của server, hoặc ngược lại. Hãy đối chiếu mục tiêu của mình: xây MCP server thì dùng package server; viết ứng dụng kết nối thì dùng package client. Với transport, xem đúng đường dẫn import trong tutorial, chẳng hạn `@modelcontextprotocol/server/stdio` cho `StdioServerTransport` trong ví dụ README.

### Thiếu schema hoặc schema không tương thích

Tool trong ví dụ có `inputSchema` dùng Zod v4. Nếu dự án chưa cài thư viện schema hoặc dùng một API không tương thích, phần đăng ký tool có thể không chạy. README cho biết SDK hỗ trợ Standard Schema, Zod v4, Valibot và ArkType; hãy dùng một lựa chọn được hỗ trợ và xem hướng dẫn cài đặt tương ứng trong repo.

### Dùng middleware nhưng chưa cài framework tương ứng

Các lệnh README cho Express, Fastify và Hono đều cài cả middleware MCP lẫn framework. Nếu chỉ cài một phần, import hoặc cấu hình ứng dụng có thể thất bại. Hãy dùng đúng cặp package trong lệnh mẫu và chỉ chọn middleware phù hợp với runtime của bạn.

### Tự đoán lệnh chạy ví dụ

Repo có nhiều ví dụ và script tài liệu, nhưng README không đưa một lệnh chạy chung cho mọi ví dụ. Nếu chưa biết chạy gì, mở `examples/README.md` và `package.json` của ví dụ đó. Không nên tự đổi tên script hoặc thêm cờ lệnh khi chưa có hướng dẫn.

```note
MCP server có thể được cấp quyền truy cập dữ liệu và công cụ thật. Hãy kiểm tra schema đầu vào, giới hạn quyền truy cập và cách lưu thông tin xác thực trước khi kết nối vào dữ liệu nội bộ hoặc dịch vụ tính phí.
```

## 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ó package tách biệt, nhiều transport, middleware tùy chọn và ví dụ end-to-end. Node.js, Bun và Deno đều được README hỗ trợ, nên bạn có thể chọn runtime phù hợp với hệ thống hiện có.

Điểm mạnh là phạm vi tính năng rộng nhưng vẫn chia thành các package rõ ràng. Bạn có thể bắt đầu bằng server stdio rất nhỏ, sau đó mở rộng sang HTTP, middleware, OAuth, resource và prompt. Thư mục `examples/`, tài liệu server/client và API reference cũng giúp đội ngũ có đường đi từ thử nghiệm đến triển khai.

Giới hạn là SDK không tự cung cấp mô hình ngôn ngữ, cơ sở dữ liệu, hệ thống phân quyền nghiệp vụ hay quy trình bảo mật hoàn chỉnh. Bạn vẫn phải tự viết logic tool, tự quyết định dữ liệu nào được phép cung cấp và tự xử lý yêu cầu xác thực của dịch vụ bên ngoài. README cũng không ghi rõ một quy trình cài đặt duy nhất cho mọi loại dự án, nên người mới cần đọc tutorial và `package.json` của ví dụ.

Nếu bạn chỉ cần gọi một API đơn giản trong một script nhỏ, một thư viện HTTP thông thường có thể gọn hơn. Nếu cần hệ sinh thái MCP, nhiều client, nhiều server hoặc kết nối trợ lý AI với công cụ nội bộ, `modelcontextprotocol/typescript-sdk` là lựa chọn đáng cân nhắc. Repo ghi phần đóng góp mới theo Apache License 2.0 và mã nguồn hiện có theo MIT; hãy xem file `LICENSE` trước khi phân phối sản phẩm.

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

### SDK này miễn phí không?

README không nêu phí sử dụng dịch vụ hay phí bản quyền thương mại. Repo ghi phần đóng góp mới theo Apache License 2.0 và mã nguồn hiện có theo MIT; bạn nên xem file LICENSE trong repo để xác định trường hợp phân phối cụ thể.

### Có cần GPU không?

README không yêu cầu GPU. SDK chạy trên Node.js, Bun hoặc Deno và cung cấp thư viện MCP server/client; nhu cầu phần cứng của ứng dụng AI hoặc dịch vụ phía sau sẽ phụ thuộc vào hệ thống bạn tích hợp.

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

README chỉ nói SDK chạy trên Node.js, Bun và Deno, không nêu danh sách hệ điều hành cụ thể. Vì vậy chưa có thông tin trực tiếp trong tư liệu để khẳng định chi tiết cho Windows; bạn cần kiểm tra runtime và ví dụ thực tế trên môi trường của mình.

### Có cần API key không?

README không yêu cầu API key để cài SDK hoặc chạy ví dụ server stdio tối giản. Nếu tool của bạn gọi dịch vụ bên ngoài, API key có thể cần theo yêu cầu của dịch vụ đó; README được cung cấp không nêu tên biến môi trường hay cấu hình key cụ thể.

### Dữ liệu có an toàn không?

SDK cung cấp cơ chế xây server, client, transport và auth/OAuth helper nhưng không tự bảo đảm dữ liệu của ứng dụng. Bạn vẫn phải tự giới hạn quyền, kiểm tra đầu vào và quyết định dữ liệu nào được phép đưa cho MCP server hoặc client.

### Repo này khác gì package MCP v1?

README cho biết nhánh chính là v2, dùng `@modelcontextprotocol/server` và `@modelcontextprotocol/client`. Dòng v1.x dùng package `@modelcontextprotocol/sdk` và có nhánh, tài liệu riêng; nếu chuyển phiên bản, hãy đọc migration guide của repo.

### Có cần dùng Express, Fastify hoặc Hono không?

Không. SDK có thể chạy bằng stdio và có hỗ trợ Streamable HTTP. Express, Fastify, Hono và Node.js HTTP chỉ là các lựa chọn middleware tùy chọn khi bạn muốn nối MCP vào runtime hoặc framework tương ứng.
