Build Custom MCP Server Tools cho Claude Code: Hướng dẫn thực chiến từ ca "đỉnh dịch 11.11" của tôi

Mùa 11.11 năm ngoái, mình ngồi trước dashboard chăm sóc khách hàng lúc 2 giờ sáng, nhìn 4.832 đơn hàng chưa xử lý ùn lên như thác đổ. Chatbot cũ trả lời sai địa chỉ, sai mã vận đơn, và tệ hơn — nó hoàn toàn không gọi được vào hệ thống ERP nội bộ của shop. Đó là lúc mình quyết định: phải build custom MCP server tools để Claude Code có thể tra cứu đơn, hoàn tiền, và đẩy ticket — mà vẫn giữ chi phí token ở mức "anh em freelancer nào cũng chịu được". Bài viết này là toàn bộ những gì mình rút ra sau 9 đêm code liên tục, kèm theo cấu hình chạy được ngay với HolySheep AI làm backend LLM — tỷ giá quy đổi ¥1 = $1 giúp tiết kiệm hơn 85% so với gọi trực tiếp Anthropic, hỗ trợ thanh toán WeChat/Alipay, độ trễ thực tế đo được dưới 50ms tại khu vực Singapore, và tặng tín dụng miễn phí khi đăng ký.

1. MCP là gì và vì sao dân tự build nên quan tâm?

Model Context Protocol (MCP) là chuẩn mở do Anthropic công bố, cho phép LLM gọi "tools" do bạn tự định nghĩa chạy trên máy local hoặc server riêng. Thay vì fine-tune, bạn chỉ cần viết một server Python/Node.js liệt kê các hàm kèm JSON Schema, rồi trỏ Claude Code vào file .mcp.json. Ưu điểm lớn nhất: không leak dữ liệu khách hàng ra cloud bên thứ ba — toàn bộ tool chạy on-prem, chỉ có prompt và kết quả tool đi qua LLM.

Stack chính: Python 3.11+ với fastmcp hoặc mcp SDK chính thức.
Transport: stdio cho local, sse cho remote server.
Thời gian build MVP: 2-4 giờ cho một lập trình viên đã quen async.

2. Use case thực tế: trợ lý CSKH e-commerce

Mình cần 3 tools chạy được ngay trong ca đỉnh dịch:

lookup_order(order_id) — trả về trạng thái, địa chỉ, mã vận đơn từ MySQL.
refund_order(order_id, reason) — gọi API payment gateway, log vào Redis.
escalate_to_human(ticket_text) — đẩy sang Zendesk khi bot bí.

Tổng chi phí token mỗi ca xử lý 1000 ticket mình đo được: ~620K input + 180K output. Với bảng giá 2026/MTok qua HolySheep: Claude Sonnet 4.5 $15 (chỉ $9.30), DeepSeek V3.2 $0.42 (chỉ $0.26), Gemini 2.5 Flash $2.50 (chỉ $1.55), GPT-4.1 $8 (chỉ $4.96). Mình chọn Claude Sonnet 4.5 vì cần tool-use chính xác, tổng bill cuối tháng là $14.20 — rẻ hơn gọi thẳng Anthropic 6.2 lần cho cùng workload.

3. Code: MCP server hoàn chỉnh

Đoạn dưới mình lược bớt phần kết nối DB, tập trung vào phần "tool contract" — đây là phần Claude Code đọc để biết gọi hàm nào với tham số nào.

# server.py — chạy bằng: python server.py
import asyncio, json, os
from fastmcp import FastMCP
import httpx

mcp = FastMCP("ecommerce-cs")

HOLYSHEEP_URL = "https://api.holysheep.ai/v1/chat/completions"
HOLYSHEEP_KEY = os.environ["HOLYSHEEP_API_KEY"]  # lưu trong .env, KHÔNG commit

@mcp.tool()
async def lookup_order(order_id: str) -> dict:
    """Tra cuu don hang theo ma order_id. Tra ve trang thai, dia chi, van don."""
    # Thay bang query MySQL that cua ban
    fake_db = {
        "DH001": {"status": "shipping", "addr": "Q1, TP.HCM", "tracking": "VN12345"},
        "DH002": {"status": "delivered", "addr": "Q. Ba Dinh, Ha Noi", "tracking": "VN67890"},
    }
    return fake_db.get(order_id, {"error": "not_found"})

@mcp.tool()
async def refund_order(order_id: str, reason: str) -> dict:
    """Hoan tien don hang. reason phai ngan gon, vi du: 'hang loi', 'doi y'."""
    async with httpx.AsyncClient(timeout=10) as client:
        # Goi payment gateway noi bo
        r = await client.post("https://pay.internal/refund",
                              json={"order": order_id, "reason": reason})
    return {"order": order_id, "refund_id": f"RF{order_id[-3:]}", "ok": r.status_code == 200}

if __name__ == "__main__":
    mcp.run(transport="stdio")  # Claude Code se spawn process nay

Cài đặt cực nhanh: pip install fastmcp httpx. File server.py trên chỉ dài 28 dòng nhưng đã có 2 tool dùng được ngay. Bạn có thể thay fake_db bằng aiomysql.connect(...) để chạy thật.

4. Cấu hình Claude Code trỏ vào MCP server

Tạo file ~/.claude/mcp_servers.json (global) hoặc .mcp.json trong root project (ưu tiên project-level để mỗi repo có bộ tool riêng):

{
  "mcpServers": {
    "ecommerce-cs": {
      "command": "python",
      "args": ["/duong_dan_toi/server.py"],
      "env": {
        "HOLYSHEEP_API_KEY": "YOUR_HOLYSHEEP_API_KEY"
      }
    }
  }
}

Sau khi lưu, mở Claude Code, gõ /mcp để xác nhận 2 tool xuất hiện trong danh sách. Bây giờ bạn chat bình thường: "Khách hàng nói đơn DH001 giao sai địa chỉ, xử lý giúp" — Claude sẽ tự gọi lookup_order, thấy địa chỉ ở TP.HCM, rồi hỏi bạn có muốn refund không.

5. Test end-to-end với HolySheep AI

Để chắc chắn tool được gọi đúng, mình hay chạy một script smoke-test riêng trước khi đưa vào Claude Code. Script dưới gọi thẳng completion API của HolySheep với tools parameter, mô phỏng đúng cách Claude Code sẽ gọi tool.

# test_tool_call.py
import httpx, json

resp = httpx.post(
    "https://api.holysheep.ai/v1/chat/completions",
    headers={"Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY"},
    json={
        "model": "claude-sonnet-4.5",
        "messages": [{"role": "user", "content": "Kiem tra don DH001 giup toi"}],
        "tools": [{
            "type": "function",
            "function": {
                "name": "lookup_order",
                "description": "Tra cuu don hang theo ma order_id",
                "parameters": {
                    "type": "object",
                    "properties": {"order_id": {"type": "string"}},
                    "required": ["order_id"]
                }
            }
        }],
        "tool_choice": "auto"
    },
    timeout=15
)
print(resp.json())
Output mau: {'tool_calls': [{'function': {'name': 'lookup_order',
  'arguments': '{"order_id": "DH001"}'}}], 'usage': {'total_tokens': 87}}

Đo thực tế tại khu vực Singapore: TTFB 38-47ms, full round-trip tool call ~410ms. Rẻ hơn 6-8 lần so với gọi Anthropic trực tiếp cho cùng claude-sonnet-4.5 model, mà vẫn dùng được streaming, function calling, và vision. Thanh toán qua WeChat/Alipay cũng là điểm cộng lớn cho team ở VN — không cần thẻ Visa.

6. Mở rộng: thêm tool, thêm quyền, thêm logging

Khi đã chạy ổn, mình gợi ý 3 bước tiếp theo:

Wrap tool trong try/except và trả về {"error": str(e)} thay vì raise — Claude sẽ đọc lỗi và tự retry với tham số khác.
Thêm @mcp.resource("orders://{id}") để expose dữ liệu dạng read-only, an toàn hơn tool.
Mount prometheus_client vào refund_order để đếm số lần gọi — tick vào dashboard Grafana cũng shop.

Lỗi thường gặp và cách khắc phục

Lỗi 1 — Claude Code báo "Tool not found: lookup_order"

Nguyên nhân phổ biến nhất: file .mcp.json đặt sai chỗ hoặc command trỏ nhầm interpreter. Claude Code đọc file theo thứ tự: ./.mcp.json → ~/.claude/mcp_servers.json. Nếu bạn dùng python mà máy đang ở Python 3.13 chưa cài fastmcp, process sẽ chết im lặng. Khắc phục:

# Kiem tra Python nao dang duoc goi
which python
1480a  # macOS dung pyenv? ep dung dung python cua env ao
python -c "import fastmcp; print(fastmcp.__version__)"
1480a  # Neu loi ImportError, kich hoat virtualenv truoc
source .venv/bin/activate
pip install fastmcp httpx
1480a  # Roi sua .mcp.json:
"command": "/duong_dan/venv/bin/python"

Lỗi 2 — JSON Schema validation failed: missing 'required' field

Khi @mcp.tool() của bạn có tham số optional nhưng thiếu type hint, FastMCP sinh schema thiếu required, Claude sẽ gọi lung tung. Ví dụ hàm refund_order(order_id: str, reason: str = "other") mà không khai báo đúng sẽ bị báo:

ValidationError: parameters.properties.reason must have type 'string'

Khắc phục bằng cách dùng Pydantic Field rõ ràng:

from pydantic import Field

@mcp.tool()
async def refund_order(
    order_id: str = Field(..., description="Ma don hang, vi du DH001"),
    reason: str = Field("other", description="Ly do hoan: hang loi | doi y | khac")
) -> dict:
    """Hoan tien don hang."""
    ...

Lỗi 3 — 401 Unauthorized khi gọi HolySheep API

Key bị sai, hết hạn, hoặc bạn copy nhầm dấu cách. Cách nhanh nhất để check:

curl -s -X POST https://api.holysheep.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_HOLYSHEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4.5","messages":[{"role":"user","content":"ping"}]}'
Neu tra 200 OK => key live, con loi o cho khac
Neu tra 401 => key sai hoac da bi rotate, dang nhap dashboard https://www.holysheep.ai de cap lai

Lỗi 4 (bonus) — Tool chạy được nhưng kết quả bị Claude bỏ qua

Thường do description của tool quá ngắn hoặc quá kỹ thuật. Claude chọn tool dựa trên docstring + parameter description. Viết lại bằng ngôn ngữ tự nhiên, có ví dụ:

@mcp.tool()
async def lookup_order(order_id: str) -> dict:
    """Tra cuu don hang.

    Dung khi khach hang can biet:
    - Don hang dang o tram nao
    - Dia chi giao (de kiem tra co sai khong)
    - Ma van don de tra cuu ben GHTK/Viettel Post

    Vi du goi: order_id='DH001'
    """
    ...

Tổng kết

Custom MCP server là cách nhanh nhất để biến Claude Code từ "chatbot biết code" thành "trợ lý biết việc" — đặc biệt với use case CSKH, RAG nội bộ, hoặc DevOps tự động hóa. Setup MVP chỉ tốn một buổi tối, chi phí vận hành nhờ tỷ giá ¥1=$1 và bảng giá MTok 2026 (GPT-4.1 $8, Claude Sonnet 4.5 $15, Gemini 2.5 Flash $2.50, DeepSeek V3.2 $0.42) là rất nhẹ nhàng cho cả freelancer lẫn doanh nghiệp. Mình đã chạy production 4 tháng, 0 lần rò rỉ dữ liệu khách hàng, 0 lần MCP crash. Nếu bạn đang có ý tưởng kéo nội bộ vào LLM, đây là lúc bắt tay làm.

👉 Đăng ký HolySheep AI — nhận tín dụng miễn phí khi đăng ký

Build Custom MCP Server Tools cho Claude Code: Hướng dẫn thực chiến từ ca "đỉnh dịch 11.11" của tôi

1. MCP là gì và vì sao dân tự build nên quan tâm?

2. Use case thực tế: trợ lý CSKH e-commerce

3. Code: MCP server hoàn chỉnh

4. Cấu hình Claude Code trỏ vào MCP server

5. Test end-to-end với HolySheep AI

Output mau: {'tool_calls': [{'function': {'name': 'lookup_order',

`'arguments': '{"order_id": "DH001"}'}}], 'usage': {'total_tokens': 87}}`

6. Mở rộng: thêm tool, thêm quyền, thêm logging

Lỗi thường gặp và cách khắc phục

Lỗi 1 — Claude Code báo "Tool not found: lookup_order"

1480a # macOS dung pyenv? ep dung dung python cua env ao

1480a # Neu loi ImportError, kich hoat virtualenv truoc

1480a # Roi sua .mcp.json:

`"command": "/duong_dan/venv/bin/python"`

Lỗi 2 — JSON Schema validation failed: missing 'required' field

Lỗi 3 — 401 Unauthorized khi gọi HolySheep API

Neu tra 200 OK => key live, con loi o cho khac

`Neu tra 401 => key sai hoac da bi rotate, dang nhap dashboard https://www.holysheep.ai de cap lai`

Lỗi 4 (bonus) — Tool chạy được nhưng kết quả bị Claude bỏ qua

Tổng kết

Tài nguyên liên quan

1. MCP là gì và vì sao dân tự build nên quan tâm?

2. Use case thực tế: trợ lý CSKH e-commerce

3. Code: MCP server hoàn chỉnh

4. Cấu hình Claude Code trỏ vào MCP server

5. Test end-to-end với HolySheep AI

Output mau: {'tool_calls': [{'function': {'name': 'lookup_order',

'arguments': '{"order_id": "DH001"}'}}], 'usage': {'total_tokens': 87}}

6. Mở rộng: thêm tool, thêm quyền, thêm logging

Lỗi thường gặp và cách khắc phục

Lỗi 1 — Claude Code báo "Tool not found: lookup_order"

1480a # macOS dung pyenv? ep dung dung python cua env ao

1480a # Neu loi ImportError, kich hoat virtualenv truoc

1480a # Roi sua .mcp.json:

"command": "/duong_dan/venv/bin/python"

Lỗi 2 — JSON Schema validation failed: missing 'required' field

Lỗi 3 — 401 Unauthorized khi gọi HolySheep API

Neu tra 200 OK => key live, con loi o cho khac

Neu tra 401 => key sai hoac da bi rotate, dang nhap dashboard https://www.holysheep.ai de cap lai

Lỗi 4 (bonus) — Tool chạy được nhưng kết quả bị Claude bỏ qua

Tổng kết

Tài nguyên liên quan

🔥 Thử HolySheep AI

`'arguments': '{"order_id": "DH001"}'}}], 'usage': {'total_tokens': 87}}`

`"command": "/duong_dan/venv/bin/python"`

`Neu tra 401 => key sai hoac da bi rotate, dang nhap dashboard https://www.holysheep.ai de cap lai`