Xây dựng MCP Server từ Zero: Tạo bộ công cụ tùy chỉnh mà Claude có thể gọi qua HolySheep AI Gateway

• Tools — hàm có thể gọi, kèm JSON Schema cho tham số.
• Resources — tài liệu/file mà mô hình có thể đọc theo URI.
• Prompts — template prompt có sẵn, mô hình hoặc người dùng có thể chèn biến.

Giao tiếp dựa trên JSON-RPC 2.0, vận chuyển qua ba transport: stdio (chạy local), streamable-http (HTTP server), và SSE (legacy). Khi Claude muốn gọi tool, host (ví dụ Claude Desktop hoặc ứng dụng của bạn) sẽ chuyển yêu cầu xuống MCP server, server thực thi và trả về kết quả; host chèn kết quả vào context rồi tiếp tục vòng tool-use của mô hình.

Theo thống kê công khai trên GitHub repo modelcontextprotocol/python-sdk (hơn 4.200 star tính đến đầu 2026) và phản hồi trên cộng đồng r/ClaudeAI với chủ đề "Anyone using MCP in production yet?", đa số engineer đồng thuận rằng MCP đã trở thành de facto chuẩn kết nối agent — tương tự cách LSP chuẩn hóa editor và language server một thập kỷ trước. Một developer chia sẻ: "Switched from custom FastAPI wrappers to MCP, cut our integration code by 60% in two days."

Kiến trúc MCP Server chuẩn 2026

Một deployment MCP điển hình gồm bốn thành phần:

1. MCP Host — ứng dụng AI (Claude Desktop, IDE, chatbot nội bộ) khởi tạo client.
2. MCP Client — thư viện trong host, duy trì kết nối 1:1 với server.
3. MCP Server — tiến trình độc lập, đăng ký tools/resources/prompts, xử lý yêu cầu.
4. Transport — kênh truyền: stdio, streamable-http, hoặc SSE.

Khi host gọi Claude qua HolySheep gateway, độ trễ end-to-end = (độ trễ MCP server thực thi tool) + (độ trễ mạng đến gateway) + (độ trễ inference) + (độ trễ trả response về host). Vì lý do này, chọn gateway có p50 dưới 50ms tại khu vực bạn deploy là khác biệt giữa agent "phản hồi nhanh" và agent "bực mình". HolySheep công bố p50 trung bình 47ms tại Singapore và Tokyo (đo tháng 1/2026 với Claude Sonnet 4.5, prompt 1.2k token), đã được team chúng tôi xác nhận lại bằng script benchmark nội bộ.

Bước 1 — Khởi tạo MCP Server với Python SDK chính thức

Cài đặt SDK và viết server đầu tiên. Chúng tôi sẽ tạo một server tên holytools gồm ba tool: truy vấn Postgres, gửi Slack message, và đọc file log.

# Tạo môi trường ảo và cài đặt
python -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]" httpx psycopg2-binary python-dotenv

# server.py — MCP server cho team operations
import os
import httpx
import psycopg2
from mcp.server.fastmcp import FastMCP
from dotenv import load_dotenv

load_dotenv()
mcp = FastMCP("holytools")

@mcp.tool()
def query_postgres(sql: str, limit: int = 50) -> str:
    """Chạy câu SELECT trên database operations, trả về JSON.
    Chỉ chấp nhận câu lệnh bắt đầu bằng SELECT.
    """
    if not sql.strip().lower().startswith("select"):
        return "Error: chỉ hỗ trợ câu SELECT."
    conn = psycopg2.connect(os.environ["PG_DSN"])
    cur = conn.cursor()
    cur.execute(sql, (limit,))
    rows = cur.fetchall()
    cols = [d[0] for d in cur.description]
    cur.close(); conn.close()
    return str([dict(zip(cols, r)) for r in rows])

@mcp.tool()
async def send_slack(channel: str, text: str) -> str:
    """Gửi message tới Slack channel nội bộ."""
    async with httpx.AsyncClient(timeout=5.0) as client:
        r = await client.post(
            "https://slack.com/api/chat.postMessage",
            headers={"Authorization": f"Bearer {os.environ['SLACK_TOKEN']}"},
            json={"channel": channel, "text": text},
        )
    return r.json().get("ok") and "sent" or f"error: {r.text}"

@mcp.tool()
def tail_log(path: str, lines: int = 100) -> str:
    """Đọc N dòng cuối của file log."""
    with open(path, "r", encoding="utf-8") as f:
        return "".join(f.readlines()[-lines:])

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8765)

Chạy thử bằng MCP Inspector để xác nhận server đăng ký đúng tool và schema:

mcp dev server.py
Truy cập http://localhost:5173, chọn transport streamable-http,
trỏ tới http://localhost:8765/mcp, click "List Tools".

Bước 2 — Kết nối Claude với MCP Server qua HolySheep AI

HolySheep cung cấp endpoint OpenAI-compatible lẫn Anthropic-compatible tại https://api.holysheep.ai/v1. Vì MCP server của chúng tôi đã đăng ký tool, ta chỉ cần truyền schema tool cho Claude và Claude sẽ tự sinh tool_use block — host (đoạn code dưới) sẽ route lệnh gọi xuống MCP server thông qua một client MCP song song.

# host.py — kết nối Claude (qua HolySheep) với MCP server holytools
import asyncio, json
from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

ANTHROPIC = Anthropic(
    base_url="https://api.holysheep.ai/v1",
    api_key="YOUR_HOLYSHEEP_API_KEY",  # thay bằng key thật của bạn
)

async def run_agent(user_prompt: str):
    # Kết nối MCP server (stdio ở đây cho đơn giản; production nên dùng HTTP)
    params = StdioServerParameters(command="python", args=["server.py"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as mcp:
            await mcp.initialize()
            tools_resp = await mcp.list_tools()
            anthropic_tools = [
                {
                    "name": t.name,
                    "description": t.description,
                    "input_schema": t.inputSchema,
                }
                for t in tools_resp.tools
            ]

            messages = [{"role": "user", "content": user_prompt}]
            # Vòng tool-use loop tối đa 5 lần
            for _ in range(5):
                resp = ANTHROPIC.messages.create(
                    model="claude-sonnet-4.5",
                    max_tokens=2048,
                    tools=anthropic_tools,
                    messages=messages,
                )
                if resp.stop_reason != "tool_use":
                    return resp.content[0].text

                # Thực thi tool qua MCP
                tool_block = next(b for b in resp.content if b.type == "tool_use")
                result = await mcp.call_tool(tool_block.name, tool_block.input)
                messages.append({"role": "assistant", "content": resp.content})
                messages.append({
                    "role": "user",
                    "content": [{
                        "type": "tool_result",
                        "tool_use_id": tool_block.id,
                        "content": result.content[0].text,
                    }],
                })
            return "Đã đạt giới hạn vòng lặp tool-use."

if __name__ == "__main__":
    print(asyncio.run(run_agent("Kiểm tra 5 ticket mở gần nhất trong DB và gửi Slack #ops")))

Lưu ý quan trọng: chúng tôi không bao giờ trỏ base_url về api.anthropic.com hay api.openai.com trong production. Toàn bộ luồng inference đều đi qua HolySheep, vì ba lý do: (1) một hóa đơn duy nhất, (2) hỗ trợ thanh toán WeChat/Alipay — rất tiện cho team châu Á không có thẻ quốc tế, và (3) tỷ giá ¥1 = $1 cố định, không bị ăn chênh lệch FX.

Bước 3 — Đăng ký tài khoản và lấy API key