Bỏ qua tới nội dung
Ông T.vn

MCP Inspector: kiểm thử MCP server bằng web, CLI, TUI — hướng dẫn cài đặt và dùng

9 phút đọcCập nhật

Bài này là một góc nhìn khác về modelcontextprotocol/inspector — 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: MCP Inspector: kiểm thử MCP server — hướng dẫn cài đặt và dùng →

MCP Inspector: kiểm thử MCP server bằng web, CLI, TUI — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

MCP Inspector (gói npm @modelcontextprotocol/inspector) là công cụ của dự án Model Context Protocol để kiểm tra và gỡ lỗi các MCP server. Nó có bản web, CLI, TUI và một công cụ thử nghiệm tên mcpdo. Chỉ cần Node đúng phiên bản và một lệnh npx là chạy được, không cần cài đặt phức tạp.

MCP Inspector là bộ công cụ để kiểm tra một MCP server (máy chủ theo giao thức Model Context Protocol) xem nó hoạt động đúng chưa. Tác giả mô tả ngắn gọn là «Deterministic testing tools for MCP servers». Bạn chạy nó, kết nối vào server của mình, rồi xem server có những gì và thử gọi chúng.

Ai nên dùng? Chủ yếu là người đang viết hoặc đang thử một MCP server: lập trình viên mới, dev làm tự động hoá, hay người muốn biết server mình vừa cài có chạy thật không trước khi gắn vào một ứng dụng AI. Nếu bạn chưa từng nghe tới MCP, bạn cứ hiểu nó là cách để ứng dụng AI cắm thêm công cụ bên ngoài. Inspector là chỗ để bạn kiểm tra các công cụ đó.

Điểm đáng giá nhất là một gói duy nhất có tới bốn cách dùng: web, CLI, TUI và mcpdo (thử nghiệm). Bạn có thể bấm chuột trên trình duyệt, hoặc viết lệnh để chạy tự động trong CI. Repo hiện có khoảng 11.288 sao và 1.569 fork, và vẫn được cập nhật trong 3 tháng gần đây.

CLI

modelcontextprotocol/inspector

MCP Inspector là công cụ cho lập trình viên để kiểm tra, gỡ lỗi MCP server qua giao diện web, dòng lệnh (CLI) hoặc giao diện terminal (TUI).

★ 11kTypeScript
Xem repo trên GitHub

I.MCP Inspector làm được gì

Theo README, cùng một gói @modelcontextprotocol/inspector cung cấp bốn cách kiểm tra server:

  • Web: một ứng dụng một trang xây bằng Vite, React và Mantine, có backend Node. Đây là chế độ mặc định, hợp với người mới vì bạn nhìn và bấm trực tiếp.
  • CLI: client dòng lệnh để viết script, chạy trong CI hoặc để các agent AI nhận phản hồi nhanh. Ví dụ bạn muốn mỗi lần sửa code, máy tự kiểm tra server còn chạy không.
  • TUI: giao diện tương tác ngay trong terminal, xây bằng Ink. Hợp khi bạn làm việc qua SSH, không có trình duyệt.
  • mcpdo (thử nghiệm): kết nối một lần, đặt tên cho kết nối, rồi chạy nhiều lệnh tiếp theo trên kết nối đó qua một tiến trình nền cục bộ. Đỡ phải kết nối lại mỗi lần.

Ngoài ra, README và danh sách tài liệu còn nhắc tới những thứ hữu ích cho việc thật:

  • Quản lý bí mật (OAuth token, OAuth client secret, giá trị env: của server stdio) và lưu vào kho khoá của hệ điều hành nếu có.
  • Phục vụ giao diện web qua HTTPS, có hướng dẫn riêng.
  • Có image Docker (repo có sẵn Dockerfile).
  • Có quy trình smoke test cho shell hoặc CI: kết nối, liệt kê, gọi, kiểm tra kết quả.
  • Có quy trình review một MCP App: dùng CLI trước, sau đó mở web một lần.
  • Có thư mục skills/, trong đó skills/mcpdo dạy agent AI cách điều khiển công cụ mcpdo.

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

Theo tư liệu, bạn cần:

  • Node.js phiên bản ^22.23.4 || ^24.22.1 || >=26.12.1. README gọi đây là bản vá trên mỗi dòng được hỗ trợ. Node cũ hơn có thể không chạy.
  • Một MCP server để kiểm tra. Cách chỉ định server nằm trong tài liệu «MCP server configuration» của repo.
  • Để chạy từ mã nguồn: git và npm.

README không nói gì về yêu cầu GPU, API key hay tài khoản trả phí để dùng chính Inspector. Còn server bạn muốn kiểm tra có thể có yêu cầu riêng, bạn xem tài liệu của server đó. Về hệ điều hành, README nhắc tới Linux, Termux, container và kho khoá của hệ điều hành, nhưng không có danh sách hệ điều hành hỗ trợ chính thức. Bạn xem thêm tài liệu «Testing and the quality gate» để biết các trình duyệt được hỗ trợ.

Inspector quản lý các thông tin nhạy cảm như OAuth token, client secret và giá trị env của server. Nếu máy không có kho khoá (Linux thiếu libsecret, phiên SSH, container...), chúng được lưu vào ~/.mcp-inspector/secrets.json và KHÔNG được mã hoá trừ khi bạn cung cấp khoá. Đừng dùng trên máy dùng chung khi chưa đọc tài liệu «Where secrets are stored».

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

Cách nhanh nhất là chạy thẳng bằng npx, không cần tải mã nguồn. Cách thứ hai dành cho người muốn sửa hoặc đóng góp code.

  1. Kiểm tra NodeĐảm bảo Node đúng phiên bản yêu cầu
  2. Chạy bằng npxMở web UI, hoặc thêm cờ để dùng CLI/TUI
  3. Thử mcpdoXem trợ giúp của công cụ thử nghiệm
  4. (Tuỳ chọn) Chạy từ mã nguồnClone repo, npm install, npm run build

A.Kiểm tra Node

Mở terminal (trên Windows: PowerShell hoặc Windows Terminal) rồi gõ lệnh dưới. Phiên bản phải thuộc các dòng đã nêu ở phần chuẩn bị. README yêu cầu Node ^22.23.4, ^24.22.1 hoặc từ 26.12.1 trở lên.

Terminal
node --version

B.Chạy bằng npx

npx sẽ tải gói về và chạy luôn. Lệnh đầu tiên mở giao diện web (chế độ mặc định). Hai lệnh sau chạy bản CLI và TUI.

Terminal
npx @modelcontextprotocol/inspector                   # web UI (default)
npx @modelcontextprotocol/inspector --cli             # CLI
npx @modelcontextprotocol/inspector --tui             # TUI

Người mới hay vấp ở chỗ: lần chạy đầu có thể mất một lúc vì npx phải tải gói. Bạn cứ chờ, đừng tắt vội.

C.Thử mcpdo

mcpdo là binary thứ hai trong cùng gói, vẫn đang ở mức thử nghiệm. Lệnh sau chỉ hiện phần trợ giúp:

Terminal
npx -p @modelcontextprotocol/inspector mcpdo --help

D.Chạy từ mã nguồn (tuỳ chọn)

Bước này chỉ cần khi bạn muốn phát triển hoặc sửa Inspector. Hãy mở terminal ở thư mục bạn muốn đặt code.

Terminal
git clone https://github.com/modelcontextprotocol/inspector.git
cd inspector
npm install          # at the repo root; postinstall cascades into every client
npm run build        # web → cli → tui → launcher

Sau khi build xong, bạn có thể chạy bản web. Lệnh thứ nhất dùng giao diện đã build, lệnh thứ hai chạy chế độ dev (Vite):

Terminal
npm run web        # prod web launcher against clients/web/dist
npm run web:dev    # web launcher in --dev mode (Vite)

Nếu chỉ muốn sửa giao diện web cho nhanh, README gợi ý chạy Vite trực tiếp:

Terminal
cd clients/web && npm run dev

Lưu ý: các lệnh npm run web chạy launcher đã build, nên phải npm run build trước. Đây là chỗ người mới hay quên.

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

README không mô tả màn hình cụ thể sau khi chạy, nên mình nói theo những gì tư liệu cho biết:

  • Với lệnh npx @modelcontextprotocol/inspector, đây là chế độ web mặc định, nên bạn kỳ vọng một giao diện web của Inspector chạy lên. Địa chỉ và cổng được in ra terminal. Nếu chưa thấy, xem tài liệu «Environment variables» vì cổng có thể chỉnh bằng biến môi trường.
  • Với --tui, giao diện sẽ hiện ngay trong cửa sổ terminal.
  • Với mcpdo --help, bạn thấy phần trợ giúp của công cụ.
  • Nếu chạy từ mã nguồn, lệnh npm run validate chạy kiểm tra định dạng, lint, typecheck, build và unit test. Đây là cách xác nhận bản build của bạn lành.
Terminal
npm run validate     # fast inner loop: format:check + lint + typecheck + build + unit tests

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

README không đưa ví dụ từng bước, nên các tình huống dưới đây bám vào các khả năng và tài liệu mà repo liệt kê. Cú pháp chi tiết (cách khai báo server, cờ lệnh) bạn xem tài liệu «MCP server configuration» và README của từng client trong thư mục clients/.

A.Dev mới viết MCP server đầu tiên

Bạn vừa viết xong một server nhỏ và chưa biết nó có khai báo công cụ đúng không. Hãy mở bản web bằng npx @modelcontextprotocol/inspector, kết nối vào server của bạn rồi xem danh sách và thử gọi từng cái. Kết quả: bạn thấy ngay server trả lời đúng hay sai, không cần gắn vào ứng dụng AI rồi đoán mò.

Nếu server của bạn chạy bằng HTTPS với chứng chỉ riêng, repo có tài liệu «Serving the web UI over HTTPS» với các biến INSPECTOR_TLS_KEY_PATH và INSPECTOR_TLS_CERT_PATH.

B.Nhân viên kỹ thuật làm kiểm tra tự động trong CI

Team của bạn có một MCP server nội bộ và muốn mỗi lần đẩy code lên thì máy tự kiểm tra. Đây là việc của bản CLI. Tài liệu «Smoke-testing an MCP server» mô tả quy trình kết nối, liệt kê, gọi, rồi kiểm tra kết quả bằng --format json kết hợp jq, kèm bảng mã thoát (exit code) và cách giữ OAuth không đòi tương tác. Kết quả: pipeline đỏ khi server hỏng, xanh khi ổn.

Công cụ tốt nhất để tin một MCP server là gọi thử nó, đừng chỉ đọc mô tả.

Ông T

C.Người dùng terminal qua SSH

Bạn làm việc trên một máy chủ từ xa, không có trình duyệt. Chạy npx @modelcontextprotocol/inspector --tui để có giao diện tương tác ngay trong terminal. Chú ý: phiên SSH thường không có kho khoá, nên bí mật có thể rơi vào file secrets.json không mã hoá. Hãy đọc lưu ý an toàn ở trên trước.

D.Review một MCP App

Nếu bạn cần rà soát một MCP App, repo có công thức «CLI-first, rồi mở web một lần». Bạn chạy CLI để lấy thông tin tự động, sau đó mở web đúng một lần để xem phần giao diện. Chi tiết nằm trong tài liệu «Reviewing an MCP App».

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

Node không đúng phiên bản. Lệnh báo lỗi engine hoặc chạy hỏng. Hãy kiểm tra node --version và nâng lên một trong các bản được yêu cầu. Repo có hẳn mục bản nâng Node trong hướng dẫn chuyển từ v1 sang v2.

Dùng nhầm flag của bản v1. Bản v2 đổi cờ CLI và tách --config với --catalog. Nếu bạn có script cũ, đọc tài liệu «Migrating from v1 to v2». Trường hợp cần bản cũ, README cho biết lệnh npx @modelcontextprotocol/inspector@v1-latest (bản v1 chỉ nhận bản vá bảo mật).

Terminal
npx @modelcontextprotocol/inspector@v1-latest

Chạy npm run web mà chưa build. Launcher chạy bản đã build nên sẽ thiếu file. Hãy chạy npm run build trước, hoặc dùng npm run web:dev cho chế độ dev.

Không có kho khoá trên máy. Trên Linux thiếu libsecret, SSH, Termux hoặc container, bí mật bị lưu ra ~/.mcp-inspector/secrets.json. Cách an toàn: đọc tài liệu «Where secrets are stored» để khôi phục kho khoá, mã hoá file, hoặc chỉ giữ bí mật trong bộ nhớ.

Truy cập web qua tên máy khác hoặc HTTPS tự ký. Tài liệu HTTPS nhắc biến ALLOWED_ORIGINS cho tên máy tuỳ chọn và NODE_EXTRA_CA_CERTS khi server ngoài dùng CA riêng. Hãy đọc tài liệu đó thay vì tự đoán giá trị.

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

Điểm mạnh. Đây là công cụ do chính dự án MCP làm, cùng một gói có bốn cách dùng, và cài qua một lệnh npx. Có bản CLI cho tự động hoá và bản web cho người mới. Repo cũng có tài liệu khá đầy đủ về HTTPS, Docker, kho bí mật và smoke test. Dự án còn được cập nhật trong 3 tháng gần đây.

Giới hạn. Đây là công cụ cho lập trình viên, không phải ứng dụng cho người dùng cuối. Bạn cần biết dùng terminal và có sẵn một MCP server để thử. mcpdo còn ở mức thử nghiệm. README chưa nêu danh sách hệ điều hành hỗ trợ và không ghi rõ giấy phép ở một dòng, chỉ cho biết dự án MCP đang chuyển từ MIT sang Apache-2.0. Ngoài ra, đóng góp từ bên ngoài được nhận qua issue chứ không qua pull request.

Khi nào chọn cách khác. Nếu bạn chỉ muốn dùng một MCP server có sẵn trong ứng dụng AI mà không viết hay gỡ lỗi gì, bạn không cần Inspector. Nếu bạn cần kiểm thử logic nghiệp vụ sâu bên trong server, hãy viết unit test riêng cho code của mình và dùng Inspector để kiểm tra phần giao tiếp.

4.2/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

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

README không nói gì về phí hay gói trả tiền, và gói npm chạy được bằng một lệnh npx. Về giấy phép, README chỉ nói xem file LICENSE và cho biết dự án MCP đang chuyển từ MIT sang Apache-2.0. Bạn nên đọc file LICENSE trong repo để chắc chắn.

Cần phiên bản Node nào?

package.json và README yêu cầu Node ^22.23.4, ^24.22.1 hoặc từ 26.12.1 trở lên. Đây là các bản vá trên mỗi dòng được hỗ trợ. Bạn kiểm tra bằng lệnh node --version.

Có cần GPU hay API key không?

Tư liệu không nhắc yêu cầu GPU hay API key cho chính Inspector. Tuy vậy, server bạn muốn kiểm tra có thể cần key riêng, và Inspector có chỗ lưu các bí mật như OAuth token hay giá trị env.

Dữ liệu và bí mật có an toàn không?

Mặc định bí mật được lưu vào kho khoá của hệ điều hành nếu có. Nếu máy không có kho khoá, chúng được lưu vào ~/.mcp-inspector/secrets.json và không mã hoá trừ khi bạn cung cấp khoá. Repo có tài liệu «Where secrets are stored» để mã hoá file hoặc chỉ giữ trong bộ nhớ.

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

Tư liệu không có danh sách hệ điều hành hỗ trợ chính thức, nên mình chưa thể khẳng định. README có nhắc kho khoá hệ điều hành, Linux, Termux và container. Bạn có thể thử bằng npx rồi xem tài liệu Testing and the quality gate của repo.

Bản web, CLI và TUI khác nhau thế nào?

Web là giao diện trình duyệt, chạy mặc định. CLI là dòng lệnh để viết script, chạy CI hoặc cho agent AI. TUI là giao diện tương tác trong terminal. Cả ba chạy qua cùng binary mcp-inspector.

Còn bản v1 thì sao?

Dòng v1 nằm ở nhánh v1/main và chỉ nhận bản vá bảo mật. Bạn có thể chạy bằng npx @modelcontextprotocol/inspector@v1-latest. Muốn chuyển sang v2, đọc hướng dẫn migration trong repo.

Chuyển nhanh tới mục

  1. I.MCP Inspector làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Kiểm tra Node
    2. B.Chạy bằng npx
    3. C.Thử mcpdo
    4. D.Chạy từ mã nguồn (tuỳ chọn)
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev mới viết MCP server đầu tiên
    2. B.Nhân viên kỹ thuật làm kiểm tra tự động trong CI
    3. C.Người dùng terminal qua SSH
    4. D.Review một MCP App
  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ỏ.