# 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 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 tới chúng. SDK hỗ trợ Node.js, Bun, Deno, có sẵn transport stdio, Streamable HTTP và các gói middleware; việc cài đặt khá gọn nếu bạn đã có dự án JavaScript hoặc TypeScript.

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

modelcontextprotocol/typescript-sdk là SDK TypeScript chính thức để xây MCP server và MCP client. MCP giúp ứng dụng cung cấp dữ liệu, công cụ và prompt cho LLM theo một cách chuẩn hóa, tách phần cung cấp context khỏi phần trực tiếp gọi mô hình.

Repo phù hợp với lập trình viên TypeScript muốn biến một API, hệ thống nội bộ hoặc quy trình nghiệp vụ thành công cụ mà ứng dụng LLM có thể gọi. Bạn cũng có thể dùng nó để viết client kết nối tới các MCP server khác. Điểm đáng giá nhất là SDK đã chia sẵn phần server, client, transport và middleware, nên bạn không phải tự thiết kế toàn bộ giao thức từ đầu.

Repo hiện có khoảng 13.758 sao và 2.383 fork. Đây là nhánh v2 của SDK, dùng hai gói chính là `@modelcontextprotocol/server` và `@modelcontextprotocol/client`. Nếu dự án của bạn còn dùng v1, cần đọc tài liệu migration và nhánh v1.x riêng; bài này tập trung vào v2.

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

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

### Xây MCP server cung cấp công cụ cho LLM

Gói `@modelcontextprotocol/server` cho phép bạn tạo server MCP và đăng ký các tool. Một tool có thể là thao tác tra cứu dữ liệu, gọi API, tạo báo cáo, kiểm tra trạng thái đơn hàng hoặc thực hiện một bước trong quy trình nội bộ.

SDK cho phép mô tả đầu vào bằng Standard Schema. README minh họa với Zod v4, đồng thời cho biết bạn có thể dùng Valibot, ArkType hoặc thư viện tương thích khác. Nhờ có schema, đầu vào của tool được mô tả rõ ràng hơn và giảm nguy cơ nhận sai dữ liệu.

### Cung cấp resources và prompts

Server MCP không chỉ có tool. SDK còn hỗ trợ resources và prompts, phù hợp khi bạn muốn cung cấp tài liệu, dữ liệu hoặc mẫu hướng dẫn cho ứng dụng LLM theo cấu trúc thống nhất.

Ví dụ, một hệ thống nội bộ có thể expose tài liệu quy trình dưới dạng resource, còn prompt có thể giúp nhân viên bắt đầu một tác vụ theo mẫu chung. README không đưa ví dụ chi tiết cho từng loại, nhưng liệt kê đây là nhóm khả năng chính của server library.

### Kết nối MCP client tới server

Gói `@modelcontextprotocol/client` dùng để xây client MCP. Client có thể kết nối tới server qua các transport được SDK hỗ trợ, lấy danh sách tool rồi gọi tool phù hợp.

Khả năng này hữu ích khi bạn đang xây một ứng dụng AI riêng, một trợ lý nội bộ hoặc một lớp trung gian muốn gom nhiều MCP server vào cùng một trải nghiệm. SDK cũng có high-level helpers và OAuth helpers cho phía client.

### Chạy qua stdio hoặc Streamable HTTP

SDK có transport stdio cho trường hợp client và server giao tiếp qua luồng vào/ra của tiến trình. Đây là cách đơn giản để chạy server cục bộ, như ví dụ `greet` trong README.

SDK cũng hỗ trợ Streamable HTTP, phù hợp khi server cần chạy như một dịch vụ web hoặc được truy cập qua mạng. Các gói middleware giúp nối MCP vào Node.js HTTP, Express, Fastify hoặc Hono mà không phải tự viết toàn bộ phần tích hợp.

### Dùng với nhiều runtime và framework

README cho biết SDK chạy trên Node.js, Bun và Deno. Ngoài hai gói chính, repo có các gói middleware tùy chọn:

- `@modelcontextprotocol/node` cho `IncomingMessage` và `ServerResponse` của Node.js.
- `@modelcontextprotocol/express` cho Express, gồm thiết lập app mặc định và kiểm tra Host header.
- `@modelcontextprotocol/fastify` cho Fastify, với các tiện ích tương tự.
- `@modelcontextprotocol/hono` cho Hono, gồm thiết lập app, hook đọc JSON body và kiểm tra Host header.

Các middleware này là adapter mỏng. Chúng không nhằm bổ sung tính năng MCP hoặc logic nghiệp vụ mới, nên phần xử lý đơn hàng, khách hàng hay dữ liệu công ty vẫn do bạn tự viết.

### Có ví dụ chạy được và tài liệu theo từng bước

Repo có thư mục `examples/` với các cặp client/server chạy được và tự kiểm tra. README cũng hướng tới hai tutorial chính: xây server đầu tiên và xây client đầu tiên.

Ngoài tài liệu hướng dẫn, repo có API reference, tài liệu về tools, resources, prompts, HTTP, stdio, client, OAuth và migration. Nếu bạn mới làm MCP, nên bắt đầu từ ví dụ server tối giản rồi mới chuyển sang HTTP hoặc OAuth.

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

Bạn cần một môi trường chạy JavaScript hoặc TypeScript tương thích. README xác nhận SDK chạy trên Node.js, Bun và Deno. `package.json` của repo yêu cầu Node.js từ phiên bản 20 trở lên, vì vậy nếu dùng Node.js bạn nên kiểm tra phiên bản trước khi cài.

Bạn cần một dự án JavaScript hoặc TypeScript để cài package. Với server, package chính là `@modelcontextprotocol/server`. Với client, package chính là `@modelcontextprotocol/client`. Bạn có thể dùng npm, Bun hoặc Deno theo các lệnh README cung cấp.

Nếu dùng schema như ví dụ trong README, bạn cần thêm Zod v4. README nói schema tool dùng Standard Schema và cho phép dùng Zod v4, Valibot, ArkType hoặc thư viện tương thích. Ví dụ cụ thể của README import `zod/v4`, nhưng không đưa lệnh cài riêng cho Zod.

Nếu dùng middleware, bạn cần cài thêm framework tương ứng. Express cần package `express`, Fastify cần `fastify`, còn Hono cần `hono`, theo đúng các lệnh cài đặt trong README.

Tư liệu không nói rằng bạn bắt buộc phải có API key, tài khoản dịch vụ bên ngoài, GPU hay phần cứng đặc biệt. OAuth helpers có trong SDK, nhưng README không nêu một nhà cung cấp OAuth cụ thể hoặc thông tin tài khoản cần chuẩn bị.

```note
SDK giúp kết nối ứng dụng với tool và dữ liệu. Hãy tự kiểm soát quyền của từng tool, đặc biệt khi tool có thể sửa dữ liệu hoặc gọi hệ thống bên ngoài. README không mô tả chính sách chi phí của các mô hình hay dịch vụ mà bạn kết nối.
```

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

```steps
- Chọn runtime | Dùng Node.js từ phiên bản 20 hoặc runtime được README hỗ trợ
- Tạo hoặc mở dự án | Mở terminal tại thư mục dự án TypeScript/JavaScript
- Cài gói server hoặc client | Chọn đúng package theo vai trò của ứng dụng
- Cài middleware nếu cần | Thêm adapter và framework tương ứng
- Tạo thành phần MCP đầu tiên | Dùng mẫu server tối giản trong README
```

### Chọn runtime và thư mục làm việc

Nếu bạn dùng Node.js, hãy dùng Node.js từ phiên bản 20 trở lên vì đó là yêu cầu trong `package.json`. Mở terminal tại thư mục dự án mà bạn muốn tích hợp MCP. Người mới thường chạy lệnh ở sai thư mục, sau đó package bị cài vào một dự án khác hoặc không tìm thấy file cần dùng.

Nếu muốn xem mã nguồn và các ví dụ của repo, có thể sao chép repo rồi đi vào thư mục đó:

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

README có `package.json` và các thư mục `examples/`, `docs/`, `packages/`, `test/`. Tuy nhiên, phần README được cung cấp không ghi đầy đủ quy trình cài dependency và build toàn bộ monorepo để phát triển SDK. Nếu mục tiêu chỉ là dùng SDK trong ứng dụng, nên cài các package npm bên dưới trong dự án của bạn.

### Cài package server

Dùng lệnh này nếu bạn muốn xây MCP server:

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

Nếu dùng Bun hoặc Deno, README cung cấp hai lựa chọn tương ứng:

```bash
bun add @modelcontextprotocol/server
```

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

Chỉ chọn một trình quản lý package phù hợp với runtime của bạn. Không nên trộn npm, Bun và Deno trong cùng một quy trình nếu bạn chưa hiểu cách dự án quản lý dependency.

### Cài package client

Dùng lệnh này nếu ứng dụng của bạn cần kết nối tới MCP server:

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

Với Bun:

```bash
bun add @modelcontextprotocol/client
```

Với Deno:

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

Client và server là hai package tách biệt. Một ứng dụng chỉ đóng vai trò client không cần cài package server, trừ khi chính ứng dụng đó cũng tự chạy server.

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

Nếu server chạy với Node.js HTTP, cài adapter Node.js:

```bash
npm install @modelcontextprotocol/node
```

Nếu dùng Express:

```bash
npm install @modelcontextprotocol/express express
```

Nếu dùng Fastify:

```bash
npm install @modelcontextprotocol/fastify fastify
```

Nếu dùng Hono:

```bash
npm install @modelcontextprotocol/hono hono
```

Chỉ cài middleware tương ứng với framework bạn đang dùng. Các package này giúp nối MCP vào runtime hoặc web framework; chúng không tự tạo logic nghiệp vụ cho ứng dụng.

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

Sau khi cài server package, tạo một file TypeScript trong dự án và đưa mẫu dưới đây vào. Đây là mẫu nguyên văn trong README, tạo một tool tên `greet` nhận `name` rồi trả về lời chào qua stdio:

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

Trong ví dụ này, `McpServer` tạo server, `registerTool` đăng ký tool và `z.object({ name: z.string() })` mô tả đầu vào. `StdioServerTransport` chọn cách giao tiếp stdio. Bạn cần bảo đảm dự án đã có cách chạy TypeScript phù hợp; phần README được cung cấp không đưa lệnh chạy file TypeScript cụ thể.

### Đọc ví dụ client/server tiếp theo

Sau server tối giản, hãy xem tutorial xây server đầu tiên và tutorial xây client đầu tiên trong tài liệu của repo. README nói tutorial server đi từ `npm init` đến một weather-alert server và một lần gọi tool. README cũng chỉ tới `examples/README.md`, nơi có các cặp client/server chạy được và tự kiểm tra.

Nếu bạn muốn làm việc với tài liệu tại máy, repo có các script sau trong phần README. Đây là các lệnh dành cho việc phát triển tài liệu, không phải lệnh bắt buộc để dùng SDK trong ứng dụng:

```bash
pnpm docs:api      # Generate the API reference markdown (output: docs/api/)
pnpm docs:dev      # Start the VitePress dev server for the V2 site
pnpm docs:build    # Build the V2 site (output: docs/.vitepress/dist/)
pnpm docs:multi    # Build the combined V1 + V2 site (output: tmp/docs-combined/)
```

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

Cách kiểm tra đầu tiên là xem package server hoặc client đã xuất hiện trong dependency của dự án sau khi chạy lệnh cài đặt. Nếu dùng server, thử biên dịch hoặc chạy mẫu `McpServer` trong môi trường TypeScript của dự án. Kết quả cần có là server kết nối thành công với `StdioServerTransport` mà không báo lỗi import package.

Với mẫu server trong README, dấu hiệu đúng là tool `greet` được đăng ký với input có trường `name`, sau đó khi được gọi sẽ trả về nội dung dạng text `Hello, <tên>!`. README không cung cấp một lệnh CLI độc lập để gọi trực tiếp tool này, nên bạn cần dùng client hoặc một integration tương thích.

Nếu kiểm tra phần tài liệu, `pnpm docs:api` phải tạo API reference trong `docs/api/`; `pnpm docs:dev` phải khởi động VitePress dev server; `pnpm docs:build` phải tạo bản build trong `docs/.vitepress/dist/`. Đây là kết quả được README nêu rõ cho các script tài liệu.

Các ví dụ trong `examples/README.md` được mô tả là runnable và self-verifying. Khi cần kiểm tra end-to-end, ưu tiên chạy một ví dụ trong thư mục `examples/` theo hướng dẫn của chính ví dụ đó.

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

### Chủ shop muốn cho trợ lý AI tra cứu đơn hàng

Chủ shop có thể viết một MCP server với tool tra cứu đơn hàng. Tool nhận mã đơn, kiểm tra dữ liệu trong hệ thống của shop rồi trả về trạng thái, sản phẩm và thông tin giao hàng ở dạng text hoặc dữ liệu có cấu trúc.

Cách triển khai bám theo mẫu README: tạo `McpServer`, dùng `registerTool`, mô tả input bằng schema và kết nối bằng stdio nếu chạy cục bộ. Trong thực tế, phần truy vấn cơ sở dữ liệu hoặc API đơn hàng là logic do bạn tự thêm; SDK chỉ đảm nhận phần giao tiếp MCP.

Một client tương thích có thể nhìn thấy tool này và gọi nó khi người dùng hỏi “đơn hàng này đang ở đâu?”. Bạn nên giới hạn tool chỉ đọc dữ liệu nếu chưa cần thao tác thay đổi đơn hàng.

### Nhân viên văn phòng muốn hỏi quy trình nội bộ

Một doanh nghiệp có thể dùng resources để cung cấp tài liệu quy trình, chính sách hoặc hướng dẫn sử dụng hệ thống. Ứng dụng LLM kết nối qua MCP client có thể lấy đúng resource khi nhân viên đặt câu hỏi.

Bạn có thể chạy server nội bộ qua stdio cho một máy đơn hoặc triển khai qua Streamable HTTP khi nhiều người cần truy cập. Nếu dùng HTTP framework, chọn middleware tương ứng như Express, Fastify hoặc Hono.

Kết quả thực tế là nhân viên có một điểm truy cập thống nhất tới tài liệu thay vì phải tự tìm từng file. Quyền truy cập dữ liệu vẫn cần được thiết kế ở ứng dụng và hệ thống phía sau.

### Dev muốn kết nối nhiều công cụ vào ứng dụng AI

Một dev có thể viết MCP client để kết nối tới các server cung cấp dữ liệu, công cụ hoặc prompt khác nhau. Client dùng transport của SDK, lấy danh sách tool và gọi tool cần thiết theo luồng xử lý của ứng dụng.

Cách này phù hợp với trợ lý kỹ thuật cần gọi nhiều nguồn: một server cho tài liệu, một server cho hệ thống build, một server cho dữ liệu dự án. `@modelcontextprotocol/client` cung cấp phần client library, transport và high-level helpers để giảm lượng mã kết nối thủ công.

Nếu hệ thống cần đăng nhập hoặc cấp quyền, README cho biết client có OAuth helpers. Tuy nhiên, cách cấu hình nhà cung cấp OAuth cụ thể chưa được nêu trong phần tư liệu này.

### Nhóm phát triển muốn thử prototype bằng stdio rồi chuyển sang HTTP

Một nhóm có thể bắt đầu bằng server `greet` chạy stdio vì mô hình này ít thành phần và dễ kiểm tra. Khi prototype ổn định, nhóm chuyển sang Streamable HTTP để phục vụ ứng dụng từ xa.

Nếu ứng dụng đã dùng Node.js HTTP, Express, Fastify hoặc Hono, cài middleware tương ứng thay vì tự nối mọi adapter. Đây là cách giữ phần logic tool độc lập với web framework, vì middleware của SDK được thiết kế mỏng.

> Hãy bắt đầu bằng một tool nhỏ, kiểm tra input và quyền truy cập, rồi mới mở rộng thành cả hệ thống MCP.
>
> — Ông T

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

### Dùng Node.js thấp hơn yêu cầu

`package.json` yêu cầu Node.js từ phiên bản 20. Nếu cài package thất bại hoặc gặp lỗi cú pháp/runtime khó hiểu, hãy kiểm tra phiên bản Node.js và nâng lên phiên bản đáp ứng yêu cầu trước khi điều tra sâu hơn.

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

V2 dùng `@modelcontextprotocol/server` và `@modelcontextprotocol/client`, còn v1 dùng package `@modelcontextprotocol/sdk`. Nếu mã mẫu hoặc tài liệu bạn đang theo dõi thuộc v1, API có thể không khớp với v2. Hãy xác định rõ tài liệu và package cùng một thế hệ; README chỉ ra migration guide và nhánh v1.x cho trường hợp này.

### Quên cài framework đi kèm middleware

Các lệnh README cài cả middleware và framework, chẳng hạn `@modelcontextprotocol/express express`. Nếu chỉ cài adapter mà chưa có framework tương ứng, phần tích hợp có thể không import hoặc không khởi động được. Chọn đúng lệnh theo runtime đang dùng.

### Schema đầu vào không khớp với dữ liệu gọi tool

Mẫu `greet` yêu cầu `name` là chuỗi. Nếu client gửi thiếu trường này hoặc gửi kiểu dữ liệu khác, tool có thể không xử lý được. Hãy giữ schema rõ ràng và kiểm tra payload từ phía client trước khi mở rộng logic nghiệp vụ.

### Chạy sai transport hoặc sai cách khởi động

Server trong README dùng `StdioServerTransport`, nên không thể coi nó như một HTTP server có URL để truy cập trực tiếp. Nếu cần phục vụ qua mạng, hãy làm theo phần tài liệu Streamable HTTP và chọn middleware phù hợp; README không cung cấp một lệnh chạy HTTP hoàn chỉnh trong nội dung được trích ở đây.

## Có nên dùng không

Nên dùng nếu bạn đang xây ứng dụng TypeScript cần cung cấp hoặc sử dụng tools, resources và prompts theo MCP. SDK có package server/client tách riêng, hỗ trợ Node.js, Bun, Deno, có stdio, Streamable HTTP, OAuth helpers và middleware cho nhiều framework. Repo cũng có ví dụ chạy được, tutorial và API reference để tiếp tục học.

Giới hạn là SDK không tự biến logic nghiệp vụ thành một hệ thống hoàn chỉnh. Bạn vẫn phải tự viết phần truy cập cơ sở dữ liệu, gọi API, xác thực người dùng, phân quyền và kiểm soát dữ liệu. README được cung cấp cũng chưa ghi đầy đủ quy trình build toàn bộ monorepo hoặc lệnh chạy TypeScript độc lập, nên người mới cần dựa vào tutorial và ví dụ trong repo.

Nếu ứng dụng chỉ cần một API nội bộ đơn giản, chưa cần tích hợp LLM hoặc chưa cần giao thức MCP, một API HTTP thông thường có thể dễ triển khai hơn. Ngược lại, nếu bạn muốn các ứng dụng LLM dùng chung một bộ công cụ và dữ liệu theo chuẩn MCP, đây là lựa chọn đáng cân nhắc. Repo đang tiếp tục được cập nhật, có khoảng 13.758 sao và 2.383 fork; giấy phép được mô tả trong README là Apache License 2.0 cho đóng góp mới, với mã hiện có dưới MIT.

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

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

Tư liệu cho biết mã đóng góp mới dùng Apache License 2.0 và mã hiện có dùng MIT. README không nêu chi phí sử dụng các mô hình, API hoặc dịch vụ bên ngoài mà ứng dụng của bạn có thể kết nối.

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

README không yêu cầu GPU hay phần cứng đặc biệt. SDK chạy trên Node.js, Bun và Deno; phần mô hình LLM hoặc dịch vụ phía sau do ứng dụng của bạn lựa chọn.

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

Tư liệu chỉ xác nhận runtime 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 README để khẳng định hỗ trợ Windows.

### Cần Node.js phiên bản bao nhiêu?

`package.json` yêu cầu Node.js từ phiên bản 20 trở lên. README cũng cho biết SDK chạy trên Bun và Deno.

### Có cần API key hoặc tài khoản OAuth không?

README không yêu cầu API key để cài SDK. SDK có OAuth helpers cho phía client, nhưng tư liệu không nêu nhà cung cấp OAuth hay tài khoản cụ thể cần chuẩn bị.

### V2 khác gì v1?

V2 dùng các package `@modelcontextprotocol/server` và `@modelcontextprotocol/client`. V1 dùng package `@modelcontextprotocol/sdk` trên nhánh v1.x; README khuyên người dùng v1 xem tài liệu và migration guide riêng.

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

Có. SDK có các package middleware tùy chọn cho Express, Fastify, Hono và Node.js HTTP; bạn cài thêm framework tương ứng theo lệnh trong README.
