Hướng dẫn AI

Xây dựng cổng OpenAPI cho các dịch vụ MCP cục bộ với Open MCP Gateway

Tìm hiểu cách cài đặt Open MCP Gateway, cấu hình các dịch vụ MCP cục bộ, tạo các route tương thích với OpenAPI, tích hợp chúng với Open WebUI, quản lý plugin bên ngoài, theo dõi nhật ký và biên dịch gateway thành tệp thực thi native độc lập.

20 tháng 9, 2026Thời gian đọc khoảng 19 phút

Xây dựng cổng OpenAPI cho dịch vụ MCP cục bộ với Open MCP Gateway

Open MCP Gateway là gì?

Open MCP Gateway, viết tắt là OMG, là một gateway hiệu năng cao, cung cấp các dịch vụ Model Context Protocol được triển khai cục bộ thông qua các route HTTP REST tuân thủ OpenAPI 3.1.0. Gateway được xây dựng bằng Bun 1.4 và TypeScript cho hệ sinh thái Open WebUI, dù đây là một dự án cộng đồng và không liên kết với đội ngũ Open WebUI.

Gateway nằm giữa một client bên ngoài và một hoặc nhiều dịch vụ MCP. Một client như Open WebUI giao tiếp với gateway qua HTTP hoặc HTTPS, trong khi gateway quản lý các transport MCP bên dưới và chuyển đổi công cụ của chúng thành giao diện tương thích với OpenAPI.

OMG hỗ trợ các dịch vụ stdio nhị phân gốc, các pipeline stdio dựa trên script Node hoặc Bun, cùng các transport mạng SSE hoặc HTTP. Nhờ đó, các dịch vụ MCP sử dụng những mô hình thực thi và giao tiếp khác nhau vẫn có thể cung cấp một giao diện HTTP thống nhất.

Tính năng chính

Đầu ra OpenAPI 3.1.0 nghiêm ngặt: Schema đầu vào của công cụ được đặt tại requestBody.content['application/json'].schema. Các giá trị operationId được tạo ra giữ nguyên tên công cụ MCP ban đầu thay vì thêm các tên như tool_*_post.
Nhiều transport MCP: Các dịch vụ stdio nhị phân gốc, stdio dạng script, SSE và HTTP có thể được quản lý qua một gateway duy nhất.
Pool phiên blue-green: Các phiên dịch vụ được hoán đổi nóng phía sau AsyncMutex, cho phép cập nhật cấu hình mà không làm gián đoạn các yêu cầu đang được xử lý.
Quản lý vòng đời: Gateway cung cấp lớp bao bọc giao thức, khả năng tự khôi phục vòng đời và tải lại nóng cho các dịch vụ được quản lý.
Bố cục XDG đa nền tảng: Các tệp cấu hình, dữ liệu ứng dụng, trạng thái runtime và bộ nhớ đệm được lưu bên ngoài kho mã nguồn.
Bản dựng độc lập: Bun có thể biên dịch gateway thành một tệp thực thi gốc không phụ thuộc runtime.
Hỗ trợ reverse proxy: Gateway đọc các header X-Forwarded-* để servers.url trong OpenAPI được tạo ra phản ánh địa chỉ bên ngoài mà client nhìn thấy.

Điều kiện tiên quyết

Để chạy dự án từ mã nguồn, cần Bun 1.4 trở lên. Bạn cũng cần đăng ký ít nhất một dịch vụ MCP. Dịch vụ đó có thể là tệp thực thi gốc cục bộ, một gói JavaScript hoặc TypeScript được khởi chạy qua Bun, hoặc một dịch vụ MCP khả dụng qua SSE hay HTTP.

Cài đặt và chạy Gateway

Chạy từ mã nguồn

Sao chép hoặc tải kho mã nguồn, truy cập vào thư mục của kho, cài đặt các dependency và khởi chạy lệnh phát triển:

bun install
bun run dev

Tiến trình phát triển đọc cấu hình gateway từ thư mục cấu hình XDG của nền tảng thay vì từ chính kho mã nguồn.

Xây dựng tệp thực thi độc lập

Để tạo tệp thực thi gốc, hãy chạy:

bun run build

Đầu ra được ghi vào build/mcp-gateway trên các hệ thống tương tự Unix hoặc build/mcp-gateway.exe trên Windows. Tệp nhị phân đã biên dịch không cần runtime Bun riêng khi triển khai.

Tìm hiểu bố cục thư mục XDG

Open MCP Gateway phân tách các tệp theo mục đích sử dụng. Điều này ngăn dữ liệu được tạo, plugin đã cài đặt, nhật ký và bộ nhớ đệm làm lộn xộn cây mã nguồn.

Cấu hình: XDG_CONFIG_HOME chứa tệp mcp-gateway/config.json5 chính.
Dữ liệu: XDG_DATA_HOME chứa kho plugin MCP bên ngoài cùng package.json riêng của kho.
Trạng thái: XDG_STATE_HOME lưu trạng thái runtime và nhật ký lâu dài.
Bộ nhớ đệm: XDG_CACHE_HOME lưu các tài liệu đặc tả đã được lưu đệm và dữ liệu runtime tạm thời.

Đường dẫn cấu hình chính là:

$XDG_CONFIG_HOME/mcp-gateway/config.json5

Tệp này sử dụng JSON5, nên hỗ trợ chú thích và dấu phẩy ở cuối.

Cấu hình dịch vụ MCP

Tạo thư mục cấu hình nếu cần, sau đó thêm config.json5. Ví dụ sau đăng ký một tệp thực thi MCP gốc và một dịch vụ MCP dựa trên gói:

{
    mcpServers: {
        // Native Binary Stdio
        codebase_memory: {
            command: "${HOME}/.local/bin/codebase-memory-mcp",
            args: [],
            env: {},
        },

        // Script Stdio
        another_mcp: {
            command: "bun",
            args: [
                "run",
                "${APP_DATA_DIR}/node_modules/<pkg>/dist/index.js",
            ],
            env: {},
        },
    },

    host: "127.0.0.1",
    port: 9090,
}

Mỗi khóa bên trong mcpServers xác định một dịch vụ MCP. Với tệp nhị phân gốc, đặt command thành đường dẫn đến tệp thực thi. Với dịch vụ dựa trên gói, sử dụng Bun làm lệnh và truyền đường dẫn script đã cài đặt qua args. Có thể thêm các biến môi trường dành riêng cho dịch vụ vào env.

Gateway hỗ trợ nội suy biến môi trường trong các đường dẫn. Các biến bao gồm ${APP_DATA_DIR}, ${XDG_DATA_HOME}, ${HOME} và %USERPROFILE%. Nội suy giúp cấu hình dễ tái sử dụng trên nhiều máy tính mà không cần ghi cứng mọi đường dẫn tuyệt đối.

Giữ mã định danh dịch vụ ổn định. Ví dụ, một dịch vụ có tên codebase_memory sẽ được cung cấp dưới đường dẫn URL tương ứng được sử dụng khi truy xuất tài liệu OpenAPI của dịch vụ đó.

Quản lý plugin MCP bên ngoài

Không nên cài đặt các gói MCP dành riêng cho nghiệp vụ trong kho gateway. Thay vào đó, hãy cài đặt và duy trì chúng trong thư mục dữ liệu XDG của gateway:

cd "$XDG_DATA_HOME/mcp-gateway"
bun add <mcp-package-name>

Để nâng cấp một gói đã cài đặt, hãy chạy:

cd "$XDG_DATA_HOME/mcp-gateway"
bun update <pkg>

Sau khi cài đặt, tham chiếu đến entry point của gói trong config.json5 bằng ${APP_DATA_DIR}, như trong ví dụ stdio của script. Điều này giúp tách biệt các dependency của gateway khỏi các dependency của tiện ích mở rộng MCP.

Cách sử dụng cơ bản

Cài đặt các dependency của gateway hoặc build tệp thực thi gốc.
Tạo $XDG_CONFIG_HOME/mcp-gateway/config.json5.
Thêm một hoặc nhiều dịch vụ bên dưới mcpServers.
Khởi động gateway bằng bun run dev hoặc chạy tệp thực thi đã biên dịch.
Lấy tài liệu OpenAPI của dịch vụ đã cấu hình và đăng ký tài liệu đó với client bên ngoài.

Đối với dịch vụ có tên codebase_memory, mẫu URL OpenAPI được ghi lại là:

http://<gateway-host>:8444/codebase_memory/openapi.json

Trong ví dụ này, 8444 là cổng có thể truy cập từ bên ngoài. Đây có thể là cổng của reverse proxy thay vì cổng nội bộ của gateway, chẳng hạn như 9090 trong ví dụ cấu hình.

Tích hợp với Open WebUI

Một reverse proxy như Caddy hoặc Nginx có thể cung cấp gateway thông qua host, cổng và giao thức bên ngoài mong muốn. Cấu hình proxy để gửi các header X-Forwarded-* phù hợp. Open MCP Gateway đọc các header này khi tạo tài liệu OpenAPI, đảm bảo servers.url trỏ đến địa chỉ công khai thay vì listener nội bộ.

Khởi động Open MCP Gateway phía sau reverse proxy.
Mở bảng quản trị Open WebUI.
Đi đến khu vực Functions, Tools hoặc OpenAPI.
Đăng ký URL tài liệu OpenAPI cho từng dịch vụ MCP đã cấu hình:
```
http://<gateway-host>:8444/codebase_memory/openapi.json
```
Cho phép Open WebUI tải đặc tả. Sau đó, các công cụ của dịch vụ MCP có thể được sử dụng như công cụ gốc thông qua các operation OpenAPI được tạo.

Vì các ID operation giữ nguyên tên công cụ MCP ban đầu, client sẽ thấy các mã định danh công cụ rõ ràng, không có hậu tố hoặc tiền tố do gateway tạo.

Kiểm thử và giám sát log

Chạy lệnh kiểm thử của dự án sau khi thay đổi gateway hoặc cấu hình của gateway:

bun run test

Trên Windows, repository cũng cung cấp script kiểm thử PowerShell:

.\ps1_scripts\test-gateway.ps1

Các assertion end-to-end bao quát kiểm tra tình trạng hoạt động, quá trình bắt tay MCP và việc căn chỉnh origin của proxy.

Trên các hệ thống giống Unix, theo dõi log gateway liên tục bằng:

tail -f "$XDG_STATE_HOME/mcp-gateway/logs/gateway.log"

Điều này hữu ích khi chẩn đoán sự cố khởi động tiến trình, đường dẫn tệp thực thi không hợp lệ, lỗi bắt tay MCP hoặc vấn đề cấu hình reverse proxy.

Mẹo nâng cao

Sử dụng đường dẫn portable

Ưu tiên các đường dẫn nội suy như ${HOME} và ${APP_DATA_DIR} thay cho đường dẫn tuyệt đối phụ thuộc vào từng máy. Trên Windows, có thể sử dụng %USERPROFILE% khi phù hợp. Điều này giúp chia sẻ cấu hình giữa các hệ thống dễ dàng hơn.

Đặt plugin bên ngoài thư mục source checkout

Cài đặt các gói MCP bên ngoài trong $XDG_DATA_HOME/mcp-gateway. Cách này giữ cho cây source sạch sẽ và cho phép nâng cấp gateway cùng các tiện ích mở rộng nghiệp vụ độc lập với nhau.

Tách biệt địa chỉ nội bộ và bên ngoài

Bind gateway vào 127.0.0.1 để listener nội bộ chỉ hoạt động cục bộ. Sau đó, reverse proxy có thể cung cấp endpoint TLS bên ngoài. Đảm bảo các header chuyển tiếp mô tả đúng scheme, host và cổng công khai để tài liệu OpenAPI được tạo quảng bá đúng URL.

Tận dụng cập nhật nóng

Pool session blue-green thay thế các session dịch vụ trong khi bảo vệ quá trình chuyển đổi bằng AsyncMutex. Thiết kế này cho phép cập nhật cấu hình mà không chấm dứt các request đang chạy. Tính năng hot reload và tự khôi phục vòng đời cũng làm giảm nhu cầu quản lý tiến trình thủ công.

Biên dịch để triển khai

Sử dụng bun run build khi máy chủ đích không cần cài Bun hoặc các dependency của dự án. Triển khai tệp thực thi được tạo cùng với cấu hình XDG bắt buộc và mọi binary hoặc gói MCP được quản lý riêng.

Kết luận

Open MCP Gateway cung cấp một cầu nối thống nhất từ các dịch vụ MCP cục bộ đến các route OpenAPI 3.1.0 nghiêm ngặt. Bằng cách kết hợp hỗ trợ nhiều transport, cấu hình portable dựa trên XDG, quản lý plugin bên ngoài, khả năng nhận biết reverse proxy và các bản build độc lập, công cụ này mang đến một phương thức thực tế để cung cấp các công cụ MCP cục bộ cho Open WebUI và các client hỗ trợ OpenAPI khác.