Biến Open WebUI Thành Siêu Trợ Lý AI: Tích Hợp MetaMCP Từ A-Z!

Lê Lân

18/08/2025

Hướng Dẫn Triển Khai MetaMCP và Tích Hợp Với Open WebUI

Mở Đầu

MetaMCP là một giải pháp toàn diện bao gồm MCP Aggregator, Orchestrator, Middleware và Gateway được gói gọn trong một Docker container, giúp bạn dễ dàng quản lý và tích hợp các MCP servers thông qua các endpoint OpenAPI.

Trong bài viết này, bạn sẽ được hướng dẫn chi tiết cách tự host MetaMCP, cấu hình để tạo ra các endpoint OpenAPI phục vụ cho Open WebUI, cho phép tích hợp các công cụ MCP một cách dễ dàng. Bạn sẽ tìm hiểu từ việc triển khai MetaMCP, thêm server, cấu hình namespace, tạo API key, đến thiết lập Open WebUI để sử dụng các công cụ trực tiếp.

Bài viết bao gồm các bước hướng dẫn từ cơ bản đến nâng cao, kèm theo các lưu ý quan trọng, mẹo vận hành và cách xử lý sự cố phổ biến.

🚀 Bước 1: Triển Khai MetaMCP Với Cấu Hình Chuẩn

Clone và Cài Đặt MetaMCP

Sử dụng lệnh:

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
cp example.env .env

Cấu Hình APP_URL để Open WebUI có thể truy cập

Trong file .env , chỉnh sửa biến APP_URL phù hợp với môi trường của bạn:

Môi trường local cả MetaMCP và Open WebUI:

APP_URL=http://localhost:12008

Open WebUI dùng bản deploy, MetaMCP cũng deploy:

APP_URL=https://your-metamcp-domain.com

⚠️ Open WebUI phải có khả năng truy cập đến địa chỉ APP_URL . Kiểm tra kỹ tường lửa và cấu hình mạng để đảm bảo điều này.

Thêm các biến bảo mật quan trọng:

POSTGRES_PASSWORD=your_secure_password
BETTER_AUTH_SECRET=your_auth_secret # Sinh ngẫu nhiên bằng lệnh openssl rand -hex 32 | base64

Khởi động MetaMCP

Chạy MetaMCP với Docker Compose:

docker compose up -d

Kiểm tra MetaMCP đã chạy bằng cách mở APP_URL trên trình duyệt.

🔧 Bước 2: Cấu Hình MetaMCP Cho Open WebUI

Tạo Tài Khoản MetaMCP

Truy cập APP_URL , tạo hoặc đăng nhập tài khoản.

Đề xuất: Tắt chức năng đăng ký tài khoản mới trong phần Settings để tăng cường bảo mật.

Thêm MCP Servers

Vào mục MCP Servers trên sidebar.

Bấm Add Server, cấu hình server ví dụ filesystem server:

Thuộc tính	Giá trị
Name	hacker-news-server
Description	Hacker News integration for fetching stories and comments
Type	STDIO
Command	uvx
Arguments	mcp-hn
Environment Variables	Nếu cần
Ownership	Everyone (Public) để Open WebUI truy cập

Lặp lại với các MCP server khác bạn muốn tích hợp.

Tạo Namespace

Vào mục Namespaces, bấm Create Namespace.

Cấu hình:

Thuộc tính	Giá trị
Name	openwebui-tools
Description	Aggregated tools for Open WebUI
Ownership	Everyone (Public)
MCP Servers	Chọn các server đã thêm vào

Namespace này giúp gom nhóm các server thành một endpoint tổng hợp.

Quản Lý Công Cụ (Tùy Chọn)

Trong namespace đã tạo, vào phần Tools Management.

Tùy chỉnh bật/tắt các công cụ để giữ cho tập công cụ gọn gàng, bảo mật hơn.

🔗 Bước 3: Tạo Endpoint OpenAPI

Tạo Endpoint Công Khai

Vào mục Endpoints, nhấn Create Endpoint.

Điền thông tin:

Thuộc tính	Giá trị
Name	openwebui-api
Description	OpenAPI endpoint for Open WebUI
Ownership	Everyone (Public)
Namespace	Chọn "openwebui-tools"
API Key Auth	Bật (ON)
Query Param Auth	Tắt (OFF), dùng Bearer token
MCP Server Creation	Bật (tự động tạo MCP server cho endpoint)

Khi hoàn tất, giao diện OpenAPI sẽ có sẵn tại:

Giao diện người dùng: {APP_URL}/metamcp/openwebui-api/api

Schema OpenAPI: {APP_URL}/metamcp/openwebui-api/api/openapi.json

🔑 Bước 4: Sinh API Key

Tạo API Key cho Open WebUI

Vào mục API Keys, nhấn Generate Key.

Cấu hình mô tả:

Thuộc tính	Giá trị
Description	Open WebUI Integration Key
Scope	Public (cho Open WebUI)

Nhấn Generate Key và lưu lại khóa này cẩn thận, khóa có định dạng bắt đầu bằng sk_mt_ .

Nếu bạn chọn "Automatically create an MCP server for this endpoint" ở bước trước, ít nhất một API key sẽ được tự động sinh ra, bạn có thể sử dụng luôn.

🎨 Bước 5: Cấu Hình Open WebUI

5.1 Mở Open WebUI và Vào Cài Đặt

Truy cập giao diện Open WebUI.

Vào phần Settings, chọn tab Tools.

5.2 Thêm Kết Nối Tool Server Mới

Trong Manage Tool Servers, nhấn vào biểu tượng "+" để thêm kết nối.

Nhập các thông tin:

Trường	Giá trị ví dụ
Base URL	`{APP_URL}/metamcp/openwebui-api/api`
OpenAPI.json Path	`{APP_URL}/metamcp/openwebui-api/api/openapi.json`
Auth Bearer Token	API Key đã tạo ở bước 4

Dùng nút Refresh để kiểm tra kết nối hoạt động.

5.3 Kiểm Tra Công Cụ Được Liệt Kê

Đóng cửa sổ cài đặt.

Tạo chat mới, xem danh sách công cụ đã sẵn sàng để gọi.

5.4 Sử Dụng Công Cụ Qua Chat

Ví dụ truy vấn: "show top hacker news" sẽ gọi công cụ tích hợp Hacker News.

Các mô hình hỗ trợ gọi tool sẽ tự động sử dụng công cụ khi cần.

🔧 Khắc Phục Sự Cố Thường Gặp

Vấn Đề	Giải Pháp
Lỗi kết nối	Kiểm tra APP_URL có truy cập được không, tường lửa, cấu hình mạng
Lỗi xác thực	Kiểm tra định dạng API key (bắt đầu `sk_mt_` ), Header Authorization
Công cụ không chạy	Kiểm tra trạng thái MCP server, quyền của công cụ, xem nhật ký lỗi
Lỗi CORS	Cho phép domain Open WebUI trong cấu hình MetaMCP, kiểm tra APP_URL

📚 Tham Khảo

MetaMCP GitHub Repository

MetaMCP Open WebUI Integration Documentation

Open WebUI Project

Docker Documentation

🎉 Kết Luận

Bạn đã hoàn tất việc tự host MetaMCP và tích hợp nó thành công với Open WebUI. Bộ công cụ này giúp:

Quản lý công cụ tập trung thông qua MetaMCP

Nâng cao khả năng AI của Open WebUI bằng các MCP servers tích hợp

Bảo mật với API key và xác thực token chuẩn Bearer

Kiến trúc mở rộng dễ dàng bổ sung thêm công cụ

Với hướng dẫn này, bạn đã xây dựng được môi trường làm việc AI mạnh mẽ, linh hoạt và tiện lợi, sẵn sàng cho các workflow tự động và nâng cao trải nghiệm người dùng.

Nếu cần hỗ trợ hoặc có câu hỏi, bạn có thể truy cập MetaMCP GitHub Issues hoặc tham gia cộng đồng Discord của MetaMCP .