Tích hợp plugin·máy chủ MCP
Cách kết nối máy chủ MCP của riêng bạn với Keural và tạo gói plugin cho ứng dụng máy tính.
Plugin của Keural là các máy chủ MCP (Model Context Protocol). Đây là đặc tả dành cho nhà phát triển kết nối máy chủ MCP với Keural hoặc tạo gói plugin cho ứng dụng máy tính.
Phương thức truyền tải
| Nền tảng | Phương thức có thể chọn | Công dụng |
|---|---|---|
| Web·di động | HTTP (Streamable HTTP) · SSE | Máy chủ MCP từ xa truy cập được qua Internet |
| Ứng dụng máy tính | STDIO · HTTP | Máy chủ chạy trên máy tính này, máy chủ HTTP trong mạng nội bộ |
- Trên web, chỉ dùng máy chủ HTTP hoặc SSE từ xa. Máy chủ STDIO chạy trên ứng dụng máy tính.
- Nếu địa chỉ máy chủ kết thúc bằng
/mcp, thường đó là máy chủ Streamable HTTP, nên chọn HTTP làm phương thức truyền tải. - HTTP trên ứng dụng máy tính dành cho địa chỉ mạng nội bộ. Địa chỉ Internet công cộng nên đăng ký bằng HTTP trên web.
Giá trị nhập khi thêm trực tiếp
Các trường nhập trong Cài đặt → Plugin → ＋ Thêm MCP tùy chỉnh như sau.
| Trường | Nội dung |
|---|---|
| Tên | Bắt buộc |
| Mô tả | Không bắt buộc |
| Phương thức truyền tải | Xem bảng trên |
| Danh mục | Phân loại trong danh sách |
| URL máy chủ | Bắt buộc với HTTP hoặc SSE. Ví dụ: https://example.com/mcp |
| Lệnh thực thi | Bắt buộc với STDIO. Ví dụ: npx |
| Đối số | Đối số STDIO (mảng JSON). Ví dụ: ["-y", "@scope/server"] |
| Dùng plugin này để tìm kiếm web | Nếu bật, tìm kiếm web sẽ dùng plugin này thay vì công cụ mặc định. |
| Xác thực | Không có · Khóa API |
| Tên header · Giá trị khóa API | Khi chọn Khóa API. Ví dụ: header Authorization, giá trị Bearer … |
Nếu chọn API key, mỗi yêu cầu sẽ kèm header <tên header>: <giá trị>.
Máy chủ xác thực bằng OAuth
Plugin do quản trị viên tổ chức đăng ký bằng OAuth yêu cầu người dùng nhấn Kết nối và đăng nhập.
| Mục | Giá trị |
|---|---|
| Tìm máy chủ | /.well-known/oauth-protected-resource (có đường dẫn, sau đó là gốc), rồi /.well-known/oauth-authorization-server |
| Đăng ký client | Đăng ký client động (DCR) |
| URI chuyển hướng | https://api.keural.ai/api/user-connectors/oauth/callback |
| Header yêu cầu | Authorization: Bearer <access token> |
Cửa sổ đăng nhập mở dưới dạng pop-up, và khi kết thúc, danh sách plugin được làm mới.
Quyền của công cụ
Đặt cách chạy cho từng công cụ của plugin.
| Quyền | Hành vi |
|---|---|
| Luôn cho phép | Chạy mà không cần xác nhận. |
| Cần phê duyệt | Hiển thị thẻ phê duyệt trước khi chạy. Thẻ cũng hiển thị các đối số của công cụ. |
| Đã chặn | Agent không dùng công cụ này. |
Gói plugin cho máy tính
Ứng dụng máy tính cài plugin bằng Tệp ZIP plugin… hoặc Thư mục plugin…. Gói phải có tệp kê khai plugin.json.
{
"id": "my-plugin",
"name": "My Plugin",
"version": "1.0.0",
"description": "Tra cứu hệ thống nội bộ",
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"],
"env": { "API_BASE": "https://intranet.example.com" }
}
}
}| Trường | Bắt buộc | Nội dung |
|---|---|---|
id | Có | Chữ thường tiếng Anh, số và dấu gạch ngang |
name | Không | Tên hiển thị. Nếu không có, dùng id. |
version | Không | Mặc định 1.0.0 |
description | Không | Mô tả |
minAppVersion | Không | Phiên bản ứng dụng tối thiểu cần thiết |
mcpServers | Không | Định nghĩa máy chủ MCP. Với mỗi máy chủ: command, args, env. |
requests | Không | Quyền yêu cầu (capabilities, commands, connectors, secrets, permissions). Mảng chuỗi. |
Plugin STDIO đã đăng ký trên web được cài sang ứng dụng máy tính bằng Cài trên máy này. Sau khi cài, hãy tự nhập token xác thực và biến môi trường.