Dựng MCP server Python 20 dòng cho API nội bộ của bạn

Claude Code đọc được file và chạy được lệnh trong repo của bạn, nhưng nó không query được database nội bộ, không gọi được internal API, không tra được một đơn hàng trong ERP. Khoảng cách đó đóng lại bằng MCP (Model Context Protocol) — và theo hướng dẫn mới trên dev.to, phần chạy local mất chưa tới 15 phút khi bạn đã làm một lần.

MCP server thực chất là gì

Tác giả mô tả MCP như "a USB-C port for AI agents: a standard way to expose any function in your codebase as a tool an agent can call." Chỉ có ba khái niệm: server là chương trình nhỏ của bạn, expose một danh sách tool; client là Claude Code, Cursor hoặc MCP client khác, gọi tool; tool là hàm có tên và có docstring.

Server tối thiểu bằng Python

Cài SDK chính thức bằng pip install mcp, rồi viết server trong khoảng 20 dòng với FastMCP:

# Ví dụ minh hoạ theo hướng dẫn gốc
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-backend-tools")

@mcp.tool()
def get_order_status(order_id: str) -> str:
    """Look up an order's status by its ID."""
    orders = {"1001": "shipped", "1002": "packing"}
    return orders.get(order_id, "not found")

if __name__ == "__main__":
    mcp.run()

Phần quan trọng nhất không phải thân hàm mà là docstring. Claude Code đọc docstring để quyết định khi nào dùng tool, nên câu mô tả kiểu "Look up an order's status by its ID" chính là thứ khiến tool được gọi thật. Lời khuyên của tác giả: viết docstring như đang giải thích tool cho một đồng nghiệp, đừng viết như đang đặt tên biến.

Nối vào Claude Code

Claude Code đọc file .mcp.json ở thư mục gốc của project:

{
  "mcpServers": {
    "my-backend-tools": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

Restart Claude Code. Từ lúc đó, hỏi "trạng thái đơn 1002 thế nào" sẽ khiến nó gọi tool của bạn thay vì trả lời là không làm được.

Khi nào phải bỏ stdio và deploy qua HTTP

Setup stdio ở trên chạy tốt cho một mình bạn. Nhưng theo tác giả, ngay khi có người thứ hai — hoặc một máy thứ hai — cần cùng bộ tool đó, một process chạy trên laptop của bạn không scale được. Lúc đó bạn expose cùng MCP server ấy qua HTTP và chạy nó như một service trên Fly.io hoặc host bất kỳ, rồi trỏ client vào URL.

Đổi lại, cả team dùng chung một nguồn sự thật, và việc thêm tool, thêm auth, thêm monitoring gom về một chỗ. Tác giả gọi đây là "the version people actually pay for: a deployed, multi-tool MCP server with auth and logging, not a script on a dev's laptop" — lưu ý đây cũng chính là dịch vụ mà tác giả bán, nên hãy đọc câu đó như một nhận định có lợi ích liên quan. Tác giả cho biết bản thân đang vận hành một MCP server 28 tool trong production.

Làm gì trước

Nếu bạn chỉ cần một tool cho riêng mình, đoạn script 20 dòng ở trên là đủ — không cần hạ tầng gì thêm. Phân tích của chúng tôi: hãy chọn tool đầu tiên là thứ bạn phải tra thủ công nhiều lần mỗi ngày (trạng thái đơn hàng, một truy vấn read-only vào DB staging, một endpoint nội bộ), vì chi phí viết thấp mà số lần agent dùng lại cao. Chỉ chuyển sang bản HTTP có auth và logging khi đã có người thứ hai cần dùng — không phải trước đó.