Test MCP server (Inspector, pytest, Claude Code)

Luồng hoạt động#

flowchart LR
  A["Hàm tool (Python)"] -->|"unit test"| B["pytest"]
  A --> C["Server FastMCP"]
  C -->|"stdio_client + ClientSession"| D["pytest e2e"]
  C -->|"mcp dev"| E["MCP Inspector"]
  C -->|"claude mcp add"| F["Claude Code"]
  F --> G["/mcp, thử prompt thật"]

Cấu hình#

Chuẩn bị#

uv add "mcp[cli]<2"        # code dưới đây dùng API 1.x (mcp.server.fastmcp)
uv add --dev pytest anyio

Tầng 1 - unit test hàm tool#

Decorator @mcp.tool() trả lại chính hàm gốc, nên gọi trực tiếp được:

import pytest
from server import list_devices, ping
 
 
def test_list_devices_filter():
    names = {d["name"] for d in list_devices(role="pe")}
    assert names == {"pe1-hni", "pe2-hcm"}
 
 
def test_ping_rejects_hostname():
    with pytest.raises(ValueError):
        ping("router.example.com")      # chỉ nhận IP

Với tool gọi thiết bị/API ngoài, mock tầng I/O (monkeypatch subprocess.run, client HTTP), đừng để unit test đụng thiết bị thật.

Tầng 2 - test giao thức qua stdio#

Khởi chạy server như tiến trình con và nói chuyện bằng JSON-RPC thật, nên bắt được lỗi schema, lỗi print() ra stdout, lỗi import:

import sys
 
import pytest
from mcp import ClientSession, StdioServerParameters, stdio_client
 
 
@pytest.fixture
def anyio_backend():
    return "asyncio"
 
 
@pytest.mark.anyio
async def test_tools_over_stdio():
    params = StdioServerParameters(command=sys.executable, args=["server.py"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
 
            tools = await session.list_tools()
            assert "ping" in {t.name for t in tools.tools}
 
            ok = await session.call_tool("list_devices", {"role": "pe"})
            assert not ok.isError
 
            bad = await session.call_tool("ping", {"target": "not-an-ip"})
            assert bad.isError            # lỗi trả về cho model, server không chết

uv run pytest -q

Điểm cần nhớ:

• Plugin anyio có sẵn trong pytest khi cài anyio; @pytest.mark.anyio + fixture anyio_backend là đủ, không cần pytest-asyncio.
• Exception trong tool không làm call_tool raise: kết quả có isError=True và content chứa thông báo (dạng Error executing tool <tên>: <lỗi>). Assert trên isError, đừng pytest.raises.
• Muốn kiểm tra schema model nhìn thấy: assert trên t.inputSchema của từng tool (kiểu, required) để bắt hồi quy khi đổi chữ ký hàm.
• Kết quả dạng list/dict trả về trong content (mỗi phần tử là một TextContent chứa JSON); tool trả str thì đọc content[0].text. Có thể parse bằng json.loads để assert.

Tầng 3a - MCP Inspector#

uv run mcp dev server.py                                  # Inspector qua CLI của mcp
npx @modelcontextprotocol/inspector uv run server.py      # hoặc chạy Inspector trực tiếp

Trong Inspector: Connect → tab Tools → List Tools → chọn tool, nhập tham số → Run Tool. Xem cả tab Notifications (log server) khi tool lỗi. Trường hợp cần thử: tham số thiếu, sai kiểu, giá trị biên, tool chạy lâu.

Tầng 3b - Claude Code#

claude mcp add netops-test -- uv run --directory /opt/netops-mcp server.py
claude mcp list
claude mcp get netops-test

Trong phiên Claude Code gõ /mcp xem trạng thái và danh sách tool, rồi hỏi một câu buộc model phải gọi tool (vd "liệt kê thiết bị role pe"). Kiểm tra: model có chọn đúng tool không, tham số có đúng không, kết quả lỗi có đủ gợi ý để tự sửa không. Nếu model chọn sai, sửa docstring/tên tool trước khi sửa code (xem Thiết kế tool cho agent và Đánh giá agent).

Lỗi thường gặp#

Kiểm tra nhanh#

uv run pytest -q                       # unit + e2e
uv run mcp dev server.py               # thử tay bằng Inspector
claude mcp list                        # server đã đăng ký và connected?

Tham khảo#

• MCP Python SDK
• MCP Inspector
• Claude Code: MCP
• Lỗi agent thường gặp