Tự xây dựng MCP Server: Kết nối Claude Code với API nội bộ

Định nghĩa

MCP Server là một chương trình nhỏ chạy ở local hoặc remote, đóng vai trò "phiên dịch viên" giữa Claude Code và bất kỳ API nào bạn muốn kết nối. Thay vì dạy Claude cách gọi từng endpoint riêng lẻ, server này tự quảng cáo khả năng của mình qua giao thức JSON-RPC, cho phép Claude tự khám phá và gọi tool một cách chuẩn hoá — giống như cách USB-C cho phép bạn cắm bất kỳ thiết bị nào mà không cần đầu chuyển đổi riêng.

Điểm mấu chốt là MCP biến Claude từ "người nghe lời" thành "người tự chủ": bạn không cần viết prompt dài dòng hướng dẫn cách gọi API, chỉ cần nói "kiểm tra đơn hàng đang pending" và Claude sẽ tự biết dùng tool nào, tham số gì.

Giải thích chi tiết

Nguyên lý "Inversion of Control" — Từ dạy AI sang AI tự đọc menu

Trước MCP, việc kết nối Claude với một API yêu cầu rất nhiều boilerplate: bạn phải mô tả schema trong prompt, dạy cách xử lý auth, và viết code để parse response. Đây là kiểu "manual integration" — bạn đang dạy AI cách dùng từng công cụ, rất mất thời gian khi API thay đổi hoặc khi onboard người mới.

MCP lật ngược mô hình này bằng capability advertisement. Server của bạn tự động expose một "menu" (schema) qua endpoint tools/list. Claude đọc menu này và tự quyết định gọi tool nào với tham số gì. Điều này hoạt động vì LLM cực kỳ giỏi sinh structured output — cho chúng một JSON Schema mô tả function, chúng sẽ tạo ra đúng arguments mà không cần few-shot prompting.

JSON-RPC 2.0 đóng vai trò như "ngôn ngữ chung" trong giao thức này. Mỗi message là một JSON object với method, params, và id, gửi qua transport layer (thường là stdio cho local server hoặc Server-Sent Events cho remote). Sự đơn giản này làm nên điểm mạnh của MCP: bạn có thể viết server bằng bất kỳ ngôn ngữ nào chỉ cần xuất ra JSON đúng format — rất phù hợp với môi trường đa ngôn ngữ thường thấy ở các công ty khởi nghiệp Việt Nam (Python backend, Node.js microservices, Go utilities).

Ba primitives: Resources, Tools, và Prompts

MCP không chỉ là "gọi hàm". Nó định nghĩa ba loại khả năng giúp phân biệt rõ ràng giữa đọc và ghi:

• Tools: Các hành động có side effect (POST/PUT/DELETE). Ví dụ: create_issue, send_slack_message, update_database. Claude phải xin phép user trước khi gọi.
• Resources: Dữ liệu read-only (GET). Ví dụ: get_user_profile, list_repositories. Được truy cập qua URI scheme như file:// hoặc api://.
• Prompts: Template có sẵn cho các tác vụ phức tạp. Ví dụ: template để viết commit message chuẩn hoá hoặc phân tích log theo format công ty.

Khi xây dựng server, bạn cần quyết định endpoint của mình thuộc loại nào. Quy tắc đơn giản: nếu thay đổi state thì là Tool; nếu chỉ đọc thì là Resource. Phân biệt này giúp Claude biết khi nào cần hỏi trước khi hành động, tránh "vô tình" xóa dữ liệu production.

FastMCP và MCP-Framework: Build server trong 5 phút

Thay vì viết JSON-RPC handler thủ công, bạn có thể dùng framework để rút ngắn thời gian từ vài giờ xuống vài phút — đặc biệt hữu ích khi bạn muốn nhanh chóng wrap một API nội bộ công ty để Claude sử dụng:

FastMCP (Python):

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def calculate_bmi(height: float, weight: float) -> float:
    """Tính chỉ số BMI từ chiều cao (m) và cân nặng (kg)"""
    return weight / (height ** 2)

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

MCP-Framework (TypeScript):

import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const server = new Server({
  name: "my-server",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

Frameworks này tự động generate JSON Schema từ type hints (Python) hoặc TypeScript definitions, xử lý transport layer, và cung cấp dev server với hot reload. Điều này giúp developer Việt Nam — thường xuyên phải làm việc với legacy code thiếu tài liệu — nhanh chóng đóng gói API cũ thành interface chuẩn mà AI có thể hiểu.

Từ localhost đến production: MCP Proxy và Security

Hầu hết tutorial chỉ dạy chạy server ở localhost với stdio transport. Nhưng trong production, bạn cần xử lý authentication (OAuth 2.0, API keys), rate limiting, và session management — đặc biệt khi kết nối với hệ thống ngân hàng hoặc ERP chứa dữ liệu nhạy cảm.

Giải pháp cộng đồng là MCP Proxy pattern: đặt một gateway giữa client (Claude) và server thực sự. Proxy này xử lý auth complexity, logging, và caching, trong khi server core giữ giao thức MCP đơn giản. Điều này giống như cách HTTP APIs thường có API Gateway phía trước, và rất phù hợp với các doanh nghiệp Việt Nam đang dùng Kong hoặc Nginx.

AutoMCP — một công cụ biên dịch từ OpenAPI spec sang MCP server — đạt 76.5% success rate out-of-the-box trên 50 APIs thực tế (5,066 endpoints). Sau khi sửa trung bình 19 dòng trong OpenAPI spec, tỷ lệ thành công lên 99.9%. Điều này cho thấy nếu bạn đã có REST API tài liệu tốt (dù là Swagger cũ của dự án outsource trước đó), việc chuyển sang MCP gần như tự động.

Ví dụ thực tế

Kết nối Claude với hệ thống đơn hàng nội bộ (FastMCP)

Giả sử công ty bạn có API quản lý đơn hàng chạy trên https://api.company.com. Bạn muốn PM có thể hỏi Claude: "Đơn hàng nào đang pending quá 3 ngày?" mà không cần viết SQL hay nhờ developer query database.

Bước 1: Tạo file order_mcp_server.py:

from fastmcp import FastMCP
import requests
import os

mcp = FastMCP("order-server")

@mcp.tool()
def get_pending_orders(days: int) -> str:
    """
    Lấy danh sách đơn hàng đang chờ xử lý quá N ngày.
    Trả về JSON string với id, customer_name, amount, created_at.
    """
    headers = {"Authorization": f"Bearer {os.getenv('API_TOKEN')}"}
    resp = requests.get(
        f"https://api.company.com/orders?status=pending&days=[days]",
        headers=headers
    )
    return resp.text

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

Bước 2: Thêm vào Claude Code:

claude mcp add --transport stdio order-server -- python order_mcp_server.py

Bước 3: Sử dụng trong chat:

User: "Kiểm tra đơn hàng nào pending quá 3 ngày và tổng giá trị là bao nhiêu?"
Claude: [Tự gọi tool get_pending_orders với days=3, sau đó tính toán và trả lời bằng tiếng Việt]

Tích hợp API GHN tính phí ship cho shop online

Bạn đang chạy shop trên Shopee hoặc website riêng và muốn nhanh chóng báo giá ship cho khách trước khi tạo đơn. Xây dựng MCP server kết nối API GHN (Giao Hàng Nhanh) để Claude tự động tính toán:

from fastmcp import FastMCP
import requests

mcp = FastMCP("ghn-shipping")

@mcp.tool()
def calculate_shipping_fee(to_district: str, to_ward: str, weight: int = 500) -> dict:
    """
    Tính phí ship GHN từ kho Hà Nội đến quận/huyện chỉ định.
    Trả về phí ship và thời gian dự kiến (ngày).
    """
    headers = {"Token": os.getenv("GHN_TOKEN")}
    data = {
        "from_district_id": 1442,  # Quận Cầu Giấy
        "to_district_id": get_district_id(to_district),
        "to_ward_code": get_ward_code(to_ward, to_district),
        "weight": weight,
        "service_type_id": 2  # Chuẩn
    }
    
    resp = requests.post(
        "https://online-gateway.ghn.vn/shiip/public-api/v2/shipping-order/fee",
        headers=headers,
        json=data
    )
    result = resp.json()
    return {
        "fee": result["data"]["total"],
        "time": "2-3 ngày",
        "insurance": result["data"]["insurance_fee"]
    }

@mcp.tool()
def create_ghn_order(customer_name: str, phone: str, address: str, weight: int) -> str:
    """Tạo đơn hàng GHN và trả về mã vận đơn"""
    # Implementation tương tự
    pass

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

Claude giờ có thể trả lời: "Gửi đến Quận 1, TP.HCM 1kg hàng thường phí bao nhiêu?" và tự động gọi API để lấy giá chính xác, thay vì tra bảng giá cũ.

Auto-generate từ OpenAPI (AutoMCP)

Nếu team bạn đã có tài liệu API dạng OpenAPI (Swagger) — ví dụ như hệ thống ERP cũ được tài liệu hóa bằng Swagger UI — dùng AutoMCP để generate server trong 1 phút:

# Giả sử bạn có file openapi.json từ hệ thống cũ
npx automcp generate --spec openapi.json --output ./mcp-server
cd ./mcp-server
npm install
npm run build

# Kết nối với Claude
claude mcp add --transport stdio my-api -- node ./dist/index.js

Server được generate sẽ expose tất cả endpoints từ OpenAPI dưới dạng MCP tools, giữ nguyên authentication và error handling. Bạn chỉ cần sửa lại khoảng 19 dòng trong spec (theo thống kê của AutoMCP) để đạt 99.9% tỷ lệ thành công — tiết kiệm hàng tuần làm việc so với viết wrapper thủ công.

Ứng dụng

Developer cá nhân / Freelancer

• Kết nối Claude với side projects: tự động deploy, query analytics, quản lý infrastructure (AWS/GCP/VPS Viettel) qua MCP thay vì nhớ các command cụ thể.
• Xây dựng "second brain": MCP server cho Zotero (quản lý paper), Notion (notes), hoặc Obsidian (vault) để Claude truy vấn kiến thức cá nhân — đặc biệt hữu ích cho sinh viên IT hoặc researcher Việt Nam.

Team / Startup nhỏ

• Chuẩn hoá API nội bộ: Thay vì mỗi người viết script khác nhau để gọi API công ty, xây dựng một MCP server duy nhất, đặt trong repo và dùng chung qua .claude/mcp.json. Giảm thiểu "tribal knowledge" — kiến thức chỉ có trong đầu một người.
• Tích hợp CI/CD: Server cho phép Claude đọc trạng thái GitHub Actions, trigger redeploy lên Vercel/Netlify, hoặc kiểm tra logs server Vietnam-hosting (như Azdigi, iNET) ngay trong flow coding.

Doanh nghiệp / Enterprise

• Security boundary: Dùng MCP Proxy để kiểm soát quyền truy cập — server core không cần biết về OAuth, proxy sẽ handle auth và audit log mọi lệnh gọi từ Claude. Tuân thủ các quy định về bảo mật thông tin cá nhân (Nghị định 13/2023/NĐ-CP).
• Data governance: MCP cho phép fine-grained access control. Ví dụ: một server chỉ expose các tools đọc dữ liệu đã anonymized, server khác mới cho phép write, và phân quyền theo team qua proxy — rất phù hợp với ngân hàng hoặc fintech Việt Nam.

So sánh

Kết luận: Nếu bạn đang dùng Claude Code cho công việc hàng ngày và thường xuyên cần tích hợp một API nội bộ (như hệ thống đơn hàng tự viết, API đối tác Viettel Post, hoặc database của khách hàng), việc tự build MCP Server là đầu tư đúng đắn — bạn trả chi phí setup một lần để tiết kiệm thời gian copy-paste và context switching mãi mãi. Còn nếu chỉ cần kết nối các dịch vụ phổ biến (GitHub, Slack, PostgreSQL), dùng server có sẵn từ cộng đồng là lựa chọn hợp lý hơn.

Bài viết liên quan

Cùng cụm MCP:

• MCP là gì? Model Context Protocol giải thích đơn giản — Giải thích khái niệm cơ bản về giao thức kết nối công cụ cho AI
• Cài đặt MCP Server đầu tiên: Hướng dẫn từng bước — Walkthrough chi tiết cho người mới bắt đầu, không cần biết code
• MCP GitHub: Quản lý PR, issue, code review từ Claude — Ví dụ thực chiến với MCP server phổ biến nhất
• MCP Database: Truy vấn PostgreSQL/SQLite từ Claude — Kết nối trực tiếp với database để phân tích dữ liệu
• MCP Slack: Đọc tin nhắn, post updates, tự động hoá — Tích hợp workflow team communication
• MCP Filesystem: Quản lý file nâng cao — Thao tác file an toàn với capability-based sandboxing

Đọc tiếp:

• Hooks là gì? 25 events và 4 loại hook — Kết hợp MCP với event-driven automation để tự động trigger tools khi file thay đổi
• Agent Teams: Nhiều Claude phối hợp cùng lúc — Dùng subagents để chạy song song nhiều MCP server cho các tác vụ phức tạp

Việc tự build MCP Server là bước chuyển từ "người dùng AI" sang "kỹ sư AI". Khi bạn hiểu cách AI "nhìn" thế giới bên ngoài qua lăng kính JSON-RPC, bạn không còn bị giới hạn bởi các tích hợp có sẵn — bạn có thể mở rộng khả năng của Claude Code đến bất kỳ hệ thống nào doanh nghiệp bạn đang sử dụng, từ API đối tác logistics đến hệ thống ERP nội bộ.