Gỡ lỗi với MCP Inspector

MCP Inspector là công cụ gỡ lỗi thiết yếu, cho phép bạn thử và xử lý sự cố MCP server một cách tương tác mà không cần một ứng dụng host AI đầy đủ. Hãy coi nó như "Postman cho MCP": một giao diện trực quan để gửi yêu cầu (request), xem phản hồi (response) và hiểu server hoạt động ra sao.

Vì sao dùng MCP Inspector?

Khi xây MCP server, bạn thường gặp các câu hỏi:

• "Server của mình có chạy không?": Inspector hiển thị trạng thái kết nối.
• "Tool đã đăng ký đúng chưa?": Inspector liệt kê mọi tool có sẵn.
• "Phản hồi có định dạng gì?": Inspector hiển thị toàn bộ phản hồi JSON.
• "Vì sao tool này không chạy?": Inspector hiển thị thông báo lỗi chi tiết.

Điều kiện cần

• Đã cài Node.js 18 trở lên
• npm (đi kèm Node.js)
• Một MCP server để thử (xem bài MCP server đầu tiên)

Cài đặt

Cách 1: chạy bằng npx (khuyến nghị để thử nhanh)

npx @modelcontextprotocol/inspector

Cách 2: cài toàn cục

npm install -g @modelcontextprotocol/inspector
mcp-inspector

Cách 3: thêm vào project

cd your-mcp-server-project
npm install --save-dev @modelcontextprotocol/inspector

Thêm vào package.json:

{
  "scripts": {
    "inspector": "mcp-inspector"
  }
}

Kết nối tới server

Server stdio (tiến trình local)

Với server giao tiếp qua standard input/output:

# Python server
npx @modelcontextprotocol/inspector python -m your_server_module

# Node.js server
npx @modelcontextprotocol/inspector node ./build/index.js

# With environment variables
OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.py

Server SSE/HTTP (qua mạng)

Với server chạy như dịch vụ HTTP:

1. Khởi động server trước:

   bash

   Copy code

   python server.py  # Server running on http://localhost:8080
   

2. Mở Inspector và kết nối:

   bash

   Copy code

   npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse
   

Tổng quan giao diện Inspector

Khi Inspector khởi động, bạn sẽ thấy một giao diện web (thường ở http://localhost:5173):

┌─────────────────────────────────────────────────────────────┐
│  MCP Inspector                              [Connected ✅]   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   🔧 Tools  │  │ 📄 Resources│  │ 💬 Prompts  │         │
│  │    (3)      │  │    (2)      │  │    (1)      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  📋 Message Log                                       │ │
│  │  ─────────────────────────────────────────────────── │ │
│  │  → initialize                                         │ │
│  │  ← initialized (server info)                          │ │
│  │  → tools/list                                         │ │
│  │  ← tools (3 tools)                                    │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Thử tool

Liệt kê tool có sẵn

1. Bấm tab Tools.
2. Inspector tự gọi tools/list.
3. Bạn sẽ thấy mọi tool đã đăng ký với tên, mô tả và input schema (tham số).

Gọi một tool

1. Chọn một tool trong danh sách.
2. Điền các tham số bắt buộc vào form.
3. Bấm Run Tool.
4. Xem phản hồi ở bảng kết quả.

Ví dụ: thử tool máy tính

Tool: add
Parameters:
  a: 25
  b: 17

Response:
{
  "content": [
    {
      "type": "text",
      "text": "42"
    }
  ]
}

Gỡ lỗi khi tool lỗi

Khi tool thất bại, Inspector hiển thị:

Error Response:
{
  "error": {
    "code": -32602,
    "message": "Invalid params: 'b' is required"
  }
}

Các mã lỗi thường gặp:

Thử resource

Liệt kê resource

1. Bấm tab Resources.
2. Inspector gọi resources/list.
3. Bạn sẽ thấy URI của resource, tên, mô tả và MIME type.

Đọc một resource

1. Chọn một resource.
2. Bấm Read Resource.
3. Xem nội dung trả về.

Ví dụ đầu ra:

Resource: file:///config/settings.json
Content-Type: application/json

{
  "config": {
    "debug": true,
    "maxConnections": 10
  }
}

Thử prompt

Liệt kê prompt

1. Bấm tab Prompts.
2. Inspector gọi prompts/list.
3. Xem các mẫu prompt có sẵn.

Lấy một prompt

1. Chọn một prompt.
2. Điền các đối số bắt buộc.
3. Bấm Get Prompt.
4. Xem các message prompt đã được dựng.

Phân tích message log

Message log hiển thị mọi thông điệp giao thức MCP. Bản ghi dưới đây lấy từ một server cũ theo 2025-11-25, có bước bắt tay initialize đã bị bỏ. Server 2026-07-28 dùng metadata trong từng request và server/discover thay thế.

14:32:01 → {"jsonrpc":"2.0","id":1,"method":"initialize",...}
14:32:01 ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",...}}
14:32:02 → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
14:32:02 ← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
14:32:05 → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
14:32:05 ← {"jsonrpc":"2.0","id":3,"result":{"content":[...]}}

Cần chú ý gì

• Cặp request/response: mỗi → phải có một ← tương ứng.
• Thông báo lỗi: tìm "error" trong các phản hồi.
• Thời gian: khoảng trống lớn có thể là dấu hiệu vấn đề hiệu năng.
• Phiên bản giao thức: đảm bảo server và client thống nhất phiên bản.

Tích hợp với VS Code

Bạn có thể chạy Inspector ngay từ VS Code.

Dùng launch.json

Thêm vào .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug with MCP Inspector",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx",
      "runtimeArgs": [
        "@modelcontextprotocol/inspector",
        "python",
        "${workspaceFolder}/server.py"
      ],
      "console": "integratedTerminal"
    },
    {
      "name": "Debug SSE Server with Inspector",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:5173",
      "preLaunchTask": "Start MCP Inspector"
    }
  ]
}

Dùng task

Thêm vào .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MCP Inspector",
      "type": "shell",
      "command": "npx @modelcontextprotocol/inspector node ${workspaceFolder}/build/index.js",
      "isBackground": true,
      "problemMatcher": {
        "pattern": {
          "regexp": "^$"
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "Inspector",
          "endsPattern": "listening"
        }
      }
    }
  ]
}

Các tình huống gỡ lỗi thường gặp

Tình huống 1: server không kết nối được

Triệu chứng: Inspector hiển thị "Disconnected" hoặc treo ở "Connecting...".

Danh sách kiểm tra:

1. Lệnh chạy server có đúng không?
2. Đã cài đủ dependency chưa?
3. Đường dẫn server là tuyệt đối hay tương đối so với thư mục hiện tại?
4. Đã đặt các biến môi trường cần thiết chưa?

Các bước gỡ lỗi:

# Test server manually first
python -c "import your_server_module; print('OK')"

# Check for import errors
python -m your_server_module 2>&1 | head -20

# Verify MCP SDK is installed
pip show mcp

Tình huống 2: tool không xuất hiện

Triệu chứng: tab Tools hiển thị danh sách rỗng.

Nguyên nhân có thể:

1. Tool không được đăng ký khi server khởi tạo.
2. Server bị crash sau khi khởi động.
3. Handler tools/list trả về mảng rỗng.

Các bước gỡ lỗi:

1. Xem phản hồi tools/list trong message log.
2. Thêm log vào code đăng ký tool.
3. Kiểm tra có decorator @mcp.tool() (Python).

Tình huống 3: tool trả về lỗi

Triệu chứng: lời gọi tool trả về phản hồi lỗi.

Cách gỡ lỗi:

1. Đọc kỹ thông báo lỗi.
2. Kiểm tra kiểu tham số khớp với schema.
3. Thêm try/catch với thông báo lỗi chi tiết.
4. Xem log server để tìm stack trace.

Ví dụ xử lý lỗi tốt hơn:

@mcp.tool()
async def my_tool(param1: str, param2: int) -> str:
    try:
        # Tool logic here
        result = process(param1, param2)
        return str(result)
    except ValueError as e:
        raise McpError(f"Invalid parameter: {e}")
    except Exception as e:
        raise McpError(f"Tool failed: {type(e).__name__}: {e}")

Tình huống 4: nội dung resource rỗng

Triệu chứng: resource trả về nhưng nội dung rỗng hoặc null.

Danh sách kiểm tra:

1. Đường dẫn file hoặc URI đúng.
2. Server có quyền đọc resource.
3. Nội dung resource được trả về đúng cách.

Tính năng nâng cao của Inspector

Header tuỳ chỉnh (SSE)

npx @modelcontextprotocol/inspector \
  --sse http://localhost:8080/sse \
  --header "Authorization: Bearer your-token"

Log chi tiết

DEBUG=mcp* npx @modelcontextprotocol/inspector python server.py

Ghi lại phiên làm việc

Inspector có thể xuất message log để phân tích sau:

1. Bấm Export Log trong bảng message.
2. Lưu file JSON.
3. Chia sẻ với đồng đội để cùng gỡ lỗi.

Best practice

1. Thử sớm và thường xuyên: dùng Inspector trong suốt quá trình phát triển, không chỉ khi có lỗi.
2. Bắt đầu đơn giản: thử kết nối cơ bản trước khi gọi tool phức tạp.
3. Kiểm tra schema: nhiều lỗi đến từ kiểu tham số không khớp.
4. Đọc thông báo lỗi: lỗi MCP thường mô tả khá rõ.
5. Luôn mở Inspector: nó giúp phát hiện vấn đề ngay khi bạn phát triển.

Tài liệu thêm

• MCP Inspector GitHub Repository
• MCP Specification - Protocol Messages
• JSON-RPC 2.0 Specification

Bài tiếp theo: Kiểm thử và triển khai MCP server.

Nguồn

• Dịch và biên tập từ microsoft/mcp-for-beginners · 03-GettingStarted/13-mcp-inspector/README.md, giấy phép MIT.