# MCP Inspector: kiểm thử MCP server — hướng dẫn cài đặt và dùng

> MCP Inspector là bộ công cụ TypeScript giúp kết nối, kiểm tra và gọi MCP server qua Web, CLI hoặc giao diện terminal. Bạn có thể chạy nhanh bằng npx; nếu phát triển repo thì cần Node đúng phiên bản và chạy npm install.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-18 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/modelcontextprotocol-inspector-kiem-thu-mcp-server-2

MCP Inspector là công cụ dành cho việc kiểm tra và gỡ lỗi các MCP server. Nó cho phép bạn kết nối tới server, xem các tool và tài nguyên mà server cung cấp, gọi thử chúng, rồi dùng kết quả để xác nhận server hoạt động đúng.

Repo này phù hợp với lập trình viên xây MCP server, đội ngũ muốn kiểm thử trong CI, hoặc người cần quan sát nhanh một server trước khi đưa vào quy trình AI. Điểm đáng giá nhất là một gói npm cung cấp nhiều cách làm việc: giao diện Web dễ quan sát, CLI phù hợp tự động hoá, TUI chạy ngay trong terminal, và mcpdo thử nghiệm cho các phiên kết nối kéo dài.

Hiện repo có khoảng 11288 sao và 1570 fork. Dự án vẫn đang được cập nhật, mã nguồn chính viết bằng TypeScript.

```repo
- repo | modelcontextprotocol/inspector
- kind | CLI
- desc | Công cụ Web, CLI và TUI để kiểm tra, gỡ lỗi và tự động hoá kiểm thử MCP server.
- stars | 11k
- lang | TypeScript
```

## MCP Inspector làm được gì

### Quan sát MCP server bằng giao diện Web

Chế độ Web mở một ứng dụng React chạy trên trình duyệt, đi kèm backend Node. Đây là lựa chọn dễ bắt đầu nếu bạn muốn xem cấu hình, danh sách tool và kết quả gọi tool bằng giao diện trực quan.

Với người mới, Web giúp giảm việc phải nhớ nhiều tham số dòng lệnh. Với người phát triển server, đây là cách thuận tiện để thử từng chức năng và phát hiện lỗi trong dữ liệu trả về.

### Gọi MCP server bằng CLI

CLI được thiết kế cho các lệnh có thể lặp lại, tự động hoá và chạy trong CI. Bạn có thể dùng nó để kết nối server, liệt kê khả năng, gọi tool và lấy đầu ra ở định dạng phù hợp với bước kiểm tra tiếp theo.

README cũng mô tả quy trình smoke test theo hướng kết nối, liệt kê, gọi và kiểm tra kết quả. Khi dùng `--format json` kết hợp với `jq`, một shell script có thể tự xác nhận đầu ra thay vì cần người nhìn màn hình.

### Làm việc trong terminal bằng TUI

TUI là giao diện tương tác chạy trong terminal, xây dựng với Ink. Nó phù hợp khi bạn đang làm việc qua SSH, thích bàn phím, hoặc không muốn mở trình duyệt riêng.

TUI vẫn được khởi chạy qua binary chính `mcp-inspector`, nên bạn không phải cài một công cụ hoàn toàn khác cho từng kiểu giao diện.

### Duy trì một kết nối với mcpdo

`mcpdo` là CLI kết nối thử nghiệm. Ý tưởng của nó là kết nối một lần, sau đó chạy nhiều lệnh trên kết nối đã đặt tên thông qua một daemon cục bộ ngầm.

Cách này có thể hữu ích khi bạn cần thực hiện nhiều thao tác liên tiếp trên cùng MCP server. Vì đây là tính năng experimental, bạn nên kiểm tra tài liệu riêng trong `clients/mcpdo` trước khi dùng cho quy trình quan trọng.

### Hỗ trợ kiểm thử lặp lại trong dự án

Repo có các thư mục `test-servers` và `scripts` dành cho server kiểm thử, fixture, smoke test và các bước xác minh. Phần này có ích cho đội phát triển muốn biến các thao tác kiểm tra thủ công thành quy trình có thể chạy lại.

### Quản lý thông tin bí mật

Inspector có thể xử lý OAuth token, OAuth client secret và giá trị trong `stdio env:`. Theo README, công cụ ưu tiên lưu chúng trong keychain của hệ điều hành nếu có.

Nếu máy không có keychain phù hợp, chẳng hạn Linux thiếu libsecret hoặc Secret Service, phiên SSH không có giao diện, Termux hoặc container có volume gắn ngoài, secret có thể được lưu vào `~/.mcp-inspector/secrets.json`. Trong tình huống này, file không được mã hoá nếu bạn không cung cấp key.

```note
Hãy coi token, client secret và giá trị trong stdio env là dữ liệu nhạy cảm. Kiểm tra nơi lưu secret trước khi chạy trong máy dùng chung, phiên SSH hoặc container; không đưa file secrets.json vào kho mã nguồn.
```

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

Bạn cần Node.js ở một phiên bản được package hỗ trợ: `^22.23.4 || ^24.22.1 || >=26.12.1`. Đây là yêu cầu quan trọng vì npm package có kiểm tra engine.

Nếu chỉ muốn dùng công cụ đã xuất bản, README cho phép chạy trực tiếp bằng `npx @modelcontextprotocol/inspector`. Khi phát triển hoặc xây repo từ mã nguồn, bạn cần một bản sao repo, npm và terminal.

Nếu làm việc với một MCP server có OAuth hoặc biến môi trường nhạy cảm, bạn cần chuẩn bị thông tin xác thực tương ứng. README không yêu cầu một tài khoản dịch vụ cụ thể cho việc khởi động Inspector, và cũng không nêu yêu cầu GPU.

Repo có cấu hình Docker, tài liệu về chạy Web qua HTTPS, biến môi trường cho cổng, xác thực, proxy, kho secret và TLS. Tuy nhiên, bạn chỉ cần Docker, chứng chỉ hoặc các biến môi trường đó khi chọn đúng kịch bản tương ứng.

README không xác nhận hệ điều hành cụ thể là được hỗ trợ toàn diện. Tài liệu có đề cập đến keychain trên Linux, phiên SSH, Termux và container, nên cách lưu secret có thể thay đổi theo môi trường.

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

```steps
- Chọn cách chạy | Dùng npx để mở ngay hoặc clone repo để phát triển
- Kiểm tra Node.js | Dùng một phiên bản thuộc dải engine được hỗ trợ
- Cài dependency | Chạy npm install tại thư mục gốc nếu làm việc từ mã nguồn
- Build dự án | Chạy npm run build để tạo các client và launcher
- Khởi chạy Inspector | Chọn Web, CLI hoặc TUI theo nhu cầu
```

### Chọn cách chạy nhanh bằng npx

Nếu mục tiêu là kiểm tra một MCP server ngay, bạn không nhất thiết phải clone mã nguồn. Mở terminal và chạy binary chính ở chế độ Web:

```bash
npx @modelcontextprotocol/inspector
```

Sau khi lệnh chạy, bạn dùng giao diện Web để làm việc với MCP server. Đây là cách ngắn nhất để bắt đầu vì npm sẽ lấy package và chạy binary.

Bạn cũng có thể chọn CLI hoặc TUI:

```bash
npx @modelcontextprotocol/inspector --cli
npx @modelcontextprotocol/inspector --tui
```

Nếu muốn xem trợ giúp của `mcpdo`, dùng binary thứ hai trong cùng package:

```bash
npx -p @modelcontextprotocol/inspector mcpdo --help
```

Người mới thường nhầm `mcpdo` với một tuỳ chọn của `mcp-inspector`. README tách chúng thành hai binary, vì vậy lệnh `mcpdo` dùng dạng `npx -p ... mcpdo --help`.

### Clone repo để phát triển

Nếu bạn muốn đọc mã nguồn, sửa client hoặc chạy bộ kiểm tra của repo, clone repo rồi đi vào thư mục:

```bash
git clone https://github.com/modelcontextprotocol/inspector.git
cd inspector
```

Mở terminal tại thư mục bạn muốn lưu dự án. Sau lệnh `cd inspector`, các lệnh npm tiếp theo phải được chạy ở thư mục gốc, nơi có `package.json` và `package-lock.json`.

### Cài dependency và build

Kiểm tra Node.js của bạn trước khi cài. README yêu cầu một trong các dải sau: `^22.23.4 || ^24.22.1 || >=26.12.1`.

Tại thư mục gốc, chạy:

```bash
npm install
npm run build
```

`npm install` cài dependency ở repo root và postinstall tiếp tục cài cho từng client. `npm run build` build theo chuỗi web, CLI, TUI rồi launcher.

Repo v2 không phải npm workspace. Mỗi client trong `clients/*` có `package.json` và `node_modules` riêng. Vì vậy, không nên tự ý xoá hoặc gộp các thư mục dependency của client khi chưa đọc quy tắc trong repo.

### Chạy Web sau khi build

Launcher-driven script dùng bản build của launcher, nên hãy chạy `npm run build` trước. Sau đó chọn một trong các lệnh:

```bash
npm run web
npm run web:dev
```

`npm run web` chạy Web launcher ở chế độ production, sử dụng `clients/web/dist`. `npm run web:dev` chạy Web launcher ở chế độ `--dev` và dùng Vite.

Nếu bạn đang sửa giao diện Web hằng ngày, README khuyên chạy Vite trực tiếp để có HMR nhanh:

```bash
cd clients/web && npm run dev
```

Lệnh này phải chạy từ thư mục `clients/web`. Đây là điểm dễ vấp: các lệnh của client không nhất thiết chạy giống lệnh ở thư mục gốc.

### Chạy các bước kiểm tra của repo

Sau khi cài dependency, bạn có thể chạy vòng kiểm tra nhanh:

```bash
npm run validate
```

README mô tả `validate` gồm kiểm tra format, lint, typecheck, build và unit test. Khi cần kiểm tra coverage, chạy:

```bash
npm run coverage
```

Trước khi đẩy thay đổi lên repo, quy trình được README đánh dấu là bắt buộc:

```bash
npm run local:gate
```

Lệnh này nối các kiểm tra CI, smoke test và Storybook test. Nó phù hợp với người đang đóng góp mã nguồn hơn là người chỉ muốn dùng Inspector để kiểm tra một server.

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

Cách đơn giản nhất là chạy:

```bash
npx @modelcontextprotocol/inspector
```

Nếu Inspector khởi động được giao diện Web, bước chạy cơ bản đã thành công. Bạn có thể tiếp tục chọn hoặc cấu hình MCP server trong giao diện.

Nếu cần kiểm tra CLI, chạy:

```bash
npx @modelcontextprotocol/inspector --cli
```

Nếu cần kiểm tra TUI, chạy:

```bash
npx @modelcontextprotocol/inspector --tui
```

Với bản clone từ repo, dấu hiệu build thành công là `npm run build` hoàn tất sau chuỗi web, CLI, TUI và launcher. Với mã nguồn đang sửa, `npm run validate` phải hoàn tất các bước format, lint, typecheck, build và unit test.

README không đưa ra một MCP server cụ thể để mọi người dùng làm dữ liệu mẫu trong phần Quick start. Vì vậy, nếu bạn chưa có server, hãy đọc thêm cấu hình server trong tài liệu của repo và thư mục `test-servers` thay vì tự đoán tên server hoặc tham số kết nối.

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

### Dev kiểm tra một MCP server mới

Một lập trình viên vừa viết server có tool tra cứu đơn hàng. Bạn có thể chạy Inspector ở chế độ Web:

```bash
npx @modelcontextprotocol/inspector
```

Sau đó kết nối tới server theo cấu hình của dự án, xem danh sách tool, gọi thử tool với dữ liệu kiểm thử và quan sát kết quả. Lợi ích là phát hiện sớm lỗi schema hoặc lỗi dữ liệu trả về trước khi đưa server vào một ứng dụng AI.

### Đội kỹ thuật kiểm thử trong CI

Một đội muốn xác nhận server còn hoạt động sau mỗi lần thay đổi có thể dùng CLI trong shell hoặc CI. README mô tả quy trình gồm kết nối, liệt kê, gọi và assert, với đầu ra JSON:

```bash
npx @modelcontextprotocol/inspector --cli --format json
```

Các tuỳ chọn kết nối và gọi cụ thể phụ thuộc tài liệu CLI hoặc cấu hình server trong repo. Khi đầu ra đã là JSON, bước tiếp theo có thể dùng `jq` để kiểm tra trường cần thiết và dựa vào exit code để quyết định CI thành công hay thất bại.

### Nhân viên kỹ thuật cần làm việc qua terminal

Nếu bạn đang ở máy chủ từ xa hoặc thích thao tác bằng bàn phím, chạy:

```bash
npx @modelcontextprotocol/inspector --tui
```

TUI cho phép làm việc tương tác ngay trong terminal. Cách này hữu ích khi không thuận tiện mở trình duyệt, nhưng bạn nên để ý cơ chế lưu secret vì phiên SSH có thể không có keychain.

### Người phát triển cần nhiều lệnh trên một kết nối

Khi cần thực hiện nhiều thao tác trên cùng một kết nối, thử xem `mcpdo`:

```bash
npx -p @modelcontextprotocol/inspector mcpdo --help
```

Đọc hướng dẫn trong `clients/mcpdo` để biết cú pháp kết nối và lệnh tiếp theo. Vì mcpdo còn experimental, hãy thử ở môi trường phát triển trước khi đưa vào quy trình vận hành.

> Công cụ kiểm thử tốt không chỉ cho biết server có trả lời, mà còn giúp bạn chứng minh nó trả lời đúng.
>
> — Ông T

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

### Node.js không đúng phiên bản

Nếu npm từ chối cài hoặc chạy package, hãy kiểm tra Node.js đang dùng. Inspector yêu cầu `^22.23.4 || ^24.22.1 || >=26.12.1`; một phiên bản cũ hơn có thể không đáp ứng engine.

Cách xử lý an toàn là chuyển sang một bản Node thuộc dải được README nêu, sau đó chạy lại `npm install`. Không nên tự sửa trường `engines` trong `package.json` để bỏ qua cảnh báo.

### Chạy lệnh ở sai thư mục

`npm install`, `npm run build`, `npm run validate` và `npm run local:gate` là các lệnh dành cho thư mục gốc. Ngược lại, lệnh Vite trong README chạy từ `clients/web`.

Hãy kiểm tra vị trí terminal trước khi chạy. Nếu bạn đang ở `clients/web`, quay lại thư mục gốc trước khi chạy script root.

### Launcher chưa được build

Nếu chạy `npm run web` hoặc `npm run web:dev` ngay sau khi clone mà chưa build, launcher có thể chưa có các file cần thiết. README nói rõ launcher-driven scripts chạy bản launcher đã build.

Chạy lại:

```bash
npm install
npm run build
```

Sau đó thử script Web lần nữa.

### Secret bị lưu vào file không mã hoá

Trong môi trường không có keychain, Inspector có thể lưu secret ở `~/.mcp-inspector/secrets.json` và file này không được mã hoá nếu bạn không cung cấp key. Điều này dễ xảy ra trong container, phiên SSH hoặc máy Linux thiếu dịch vụ keychain phù hợp.

Đọc tài liệu “Where secrets are stored” trong repo để xem cách bật lại keychain, mã hoá file hoặc chỉ giữ secret trong bộ nhớ. Không chia sẻ file này và không commit nó vào repo.

### Kết nối OAuth không chạy tự động trong CI

OAuth thường cần token hoặc bước tương tác. README có tài liệu riêng về smoke test và lưu ý giữ OAuth ở chế độ không tương tác khi chạy tự động.

Hãy chuẩn bị thông tin xác thực theo cấu hình server, kiểm tra cách Inspector lưu secret, rồi thiết kế bước CI không chờ thao tác thủ công. Nếu chưa có token hoặc cấu hình rõ ràng, hãy thử trong Web hoặc CLI ở môi trường phát triển trước.

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

Bạn nên dùng MCP Inspector nếu đang phát triển MCP server và cần một công cụ chung để quan sát, gọi thử, debug hoặc tự động hoá kiểm tra. Ba giao diện Web, CLI và TUI bao phủ khá tốt các nhu cầu từ người mới đến quy trình CI. Việc gom chúng vào một package cũng giúp bạn chuyển từ thử thủ công sang script mà không phải đổi hẳn công cụ.

Điểm mạnh khác là repo có sẵn cấu trúc cho test server, smoke test, tài liệu cấu hình, Docker, HTTPS và kho secret. Dự án cũng đang được cập nhật, nên phù hợp với người muốn theo dõi hệ sinh thái MCP hiện đại.

Giới hạn là yêu cầu Node khá mới, cấu trúc repo v2 có nhiều client và không phải npm workspace nên người mới có thể hơi bối rối khi làm việc từ mã nguồn. `mcpdo` còn experimental. Cơ chế lưu secret cũng cần được kiểm tra kỹ, nhất là trên máy không có keychain.

Nếu bạn chỉ cần gọi một MCP server một lần và đã có công cụ khách hàng phù hợp, Inspector có thể là quá nhiều. Nếu bạn cần giao diện chuyên biệt cho một server cụ thể, hãy cân nhắc công cụ do chính server đó cung cấp. Còn nếu mục tiêu là kiểm tra có hệ thống, debug nhiều kiểu môi trường hoặc đưa MCP server vào CI, MCP Inspector là lựa chọn đáng thử.

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

### MCP Inspector có miễn phí không?

Tư liệu được cung cấp không xác nhận chính sách giá hoặc mức phí sử dụng. README cho biết công cụ được phát hành qua package npm `@modelcontextprotocol/inspector`, còn thông tin giấy phép cần xem trong file `LICENSE`.

### Có cần GPU để chạy MCP Inspector không?

README không nêu yêu cầu GPU. Công cụ gồm Web app với backend Node, CLI và TUI, nên tư liệu chỉ xác nhận yêu cầu Node.js chứ không đưa ra yêu cầu phần cứng đặc biệt.

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

Tư liệu được cung cấp không xác nhận Windows là hệ điều hành được hỗ trợ toàn diện. README có đề cập Linux, SSH, Termux và container trong ngữ cảnh lưu secret, nhưng không đưa hướng dẫn riêng cho Windows.

### Dữ liệu và token được lưu ở đâu?

Inspector ưu tiên lưu OAuth token, OAuth client secret và giá trị `stdio env:` trong keychain của hệ điều hành nếu có. Nếu không có keychain, chúng có thể nằm trong `~/.mcp-inspector/secrets.json`; file này không được mã hoá nếu bạn không cung cấp key.

### MCP Inspector khác gì một MCP client thông thường?

Inspector tập trung vào việc inspect và kiểm thử MCP server. Nó cung cấp Web, CLI, TUI và mcpdo, trong đó CLI hỗ trợ tự động hoá, CI và vòng phản hồi nhanh cho agent.

### Tôi nên dùng Web, CLI hay TUI?

Web phù hợp để quan sát trực quan, CLI phù hợp với script và CI, còn TUI phù hợp khi làm việc tương tác trong terminal. README cũng có `mcpdo` experimental cho trường hợp duy trì một kết nối để chạy nhiều lệnh.

### Có thể dùng Inspector để kiểm thử tự động không?

Có. README mô tả CLI dành cho automation và CI, cùng quy trình smoke test kết nối, liệt kê, gọi và assert. Đầu ra `--format json` có thể kết hợp với `jq` trong shell hoặc CI.
