Connector
Nối agent với MCP server từ xa: cách xác thực, tool theo từng agent, và cách xử lý khi kết nối hỏng.
Một connector nối tổ chức của bạn với một MCP server từ xa (MCP) — Google Drive, hệ thống ticket, hay API nội bộ của bạn — để agent gọi được các tool server đó cung cấp. Bạn tự thêm và quản lý connector trên console, ở mục Kết nối.
Đội của bạn tự viết MCP server? Xem Xây dựng MCP server để biết tiêu chuẩn xác thực và cách thiết kế tool mà Harnix cần.
Đặt tên cho từng kết nối
Mỗi connector có một tên do bạn đặt, duy nhất trong tổ chức. Hai connector có thể trỏ cùng một server nhưng dùng tài khoản khác nhau — "Google Drive – Nhân sự" và "Google Drive – Tài chính" — và được giao cho các agent khác nhau.
Thêm connector
- Mở Kết nối, bấm Thêm kết nối.
- Nhập Tên và URL máy chủ MCP từ xa của server.
- Chọn cách Xác thực rồi bấm Thêm kết nối.
Harnix lưu connector và kiểm tra server ngay (tối đa 10 giây). Sheet sau đó hiện một trong ba kết quả:
- Tìm thấy N công cụ. Xong.
- Máy chủ này cần bạn đăng nhập. Bấm Kết nối (xem bên dưới).
- Lỗi, kèm lý do. Sửa cấu hình (thường ở Nâng cao) rồi bấm Lưu và thử lại. Dù kết quả nào, connector cũng đã được lưu.
Xác thực
| Cách | Dùng khi |
|---|---|
| Tự động (mặc định) | Bạn không chắc. Harnix hỏi server: nếu server đòi đăng nhập OAuth thì connector dùng OAuth, không thì không xác thực. |
| Header | Server cần một header cố định, ví dụ Authorization: Bearer … hay header chứa API key. |
| Client credentials | Server cấp token cho một ứng dụng (OAuth client credentials): nhập Client ID, Client secret và scope nếu cần. |
| Không xác thực | Server mở, không cần xác thực. |
Trong Nâng cao bạn có thể nhập OAuth Client ID và OAuth Client Secret của riêng mình (chỉ khi server không hỗ trợ đăng ký tự động, hoặc bạn muốn dùng OAuth app của mình), các Scope cần xin, và Transport (Tự động thử Streamable HTTP trước, rồi SSE).
Nếu bạn tự tạo OAuth app ở nhà cung cấp, hãy khai redirect URI này:
https://app.harnix.vn/connectors/callback.
Đăng nhập (Kết nối)
Với connector OAuth, Kết nối mở trang đăng nhập của nhà cung cấp trong một cửa sổ nhỏ. Bạn đồng ý cấp quyền ở đó; cửa sổ tự đóng và connector chuyển sang Đã kết nối kèm danh sách tool. Nếu trình duyệt chặn cửa sổ, bấm Tiếp tục trong thẻ này.
Quyền đăng nhập thuộc về tổ chức: mọi cuộc hội thoại với agent dùng connector này đều hành động bằng quyền bạn đã cấp. Hãy tách connector (và tài khoản nhà cung cấp) khi các agent khác nhau cần thấy dữ liệu khác nhau.
Chọn tool cho từng agent
Mở một agent, vào tab Công cụ:
- Tìm kiếm tri thức cho biết agent có tra cứu knowledge base hay không (xem Tool).
- Công cụ tích hợp quản lý các tool nền tảng như
ask_userđể agent hỏi lại người dùng (xem Tool). - Kết nối liệt kê các connector agent được dùng. Thêm kết nối để chọn một connector và chọn tool của nó. Mọi tool đều bật mặc định — kể cả tool server thêm sau này — và mỗi tool có công tắc riêng.
Tool đã tắt không bao giờ được đưa cho model của agent đó. Agent khác dùng cùng connector không bị ảnh hưởng. Thay đổi áp dụng cho các run bắt đầu sau khi bạn đổi.
Xác nhận trước khi gọi tool
Một tool của connector có thể thay đổi dữ liệu ở hệ thống của bạn — tạo đơn hàng, gửi email, cập nhật ticket. Những tool như vậy không chạy âm thầm: agent dừng lại, người dùng cuối thấy tên connector, tên tool và tham số thật agent sắp gửi, rồi mới quyết định đồng ý hay từ chối. Không một hành động ghi nào xảy ra mà người dùng chưa nhìn thấy.
Tool nào cần xác nhận là do MCP server khai qua annotation: tool được đánh
dấu readOnlyHint: true (chỉ đọc) chạy ngay; mọi tool khác — kể cả
tool của server không khai annotation gì — hỏi xác nhận trước. Mở một agent,
vào tab Công cụ, mục Kết nối: mỗi tool có công tắc Cần xác nhận
riêng để bật hoặc tắt yêu cầu xác nhận. Công tắc hiển thị mặc định nếu
không có ghi đè; bấm Về mặc định để xoá ghi đè. Một tool đã tắt
(disabled_tools) không thể đổi yêu cầu xác nhận — công tắc bị vô hiệu hoá.
Trong hội thoại, việc xác nhận diễn ra qua khung approval của
stream và
POST /v2/runs/{run_id}/approval:
đồng ý, đồng ý cho cả cuộc hội thoại này, hoặc từ chối; kênh
server-to-server tự quyết qua cùng route.
Từ chối, hay không trả lời trong 5 phút, không làm hỏng cuộc hội thoại:
tool nhận một kết quả lỗi, trợ lý nói với người dùng rằng hành động không
được thực hiện, và run kết thúc bình thường.
Mọi quyết định — ai, lúc nào, kết quả, có ghi nhớ cho cuộc hội thoại hay không — hiện trên trace của run ở Lượt chạy & Trace.
Khi connector hỏng
| Trạng thái | Ý nghĩa | Cần làm |
|---|---|---|
| Đã kết nối | Đang hoạt động. | — |
| Cần đăng nhập | Đã thêm, chưa đăng nhập. | Bấm Kết nối. |
| Cần kết nối lại | Quyền đăng nhập bị thu hồi hoặc hết hạn, hoặc connector cần thêm quyền. | Bấm Kết nối lại trên trang connector. |
| Lỗi | Không kết nối được server, hoặc server từ chối cấu hình. | Mở connector, đọc lý do, bấm Sửa để sửa. |
| Ngừng hoạt động | Connector đang tắt. | Bấm Kích hoạt trong menu của connector. |
Connector hỏng không bao giờ làm cuộc chat thất bại: agent vẫn trả lời, chỉ thiếu tool của connector đó cho tới khi bạn sửa, và trace của run ghi lại lý do.
Ngừng hoạt động (trong menu của connector, hoặc trên trang của nó) tắt connector mà không mất cấu hình hay quyền đăng nhập: agent vẫn được gán nhưng không gọi được tool cho tới khi bạn bấm Kích hoạt.
Nếu cột Công cụ hiện —, nghĩa là Harnix chưa lấy danh sách tool của server đó; bấm Kiểm tra (hoặc Làm mới trên trang connector) để tải.
Ngắt kết nối xoá quyền đăng nhập đã lưu (agent vẫn được gán connector, tool ngừng hoạt động cho tới khi có người kết nối lại). Xoá xoá connector, quyền đăng nhập và việc gán cho mọi agent.
Giới hạn và bảo mật
- Chỉ chấp nhận địa chỉ
httpscông khai; địa chỉ private/nội bộ và URL có username hoặc password bị từ chối. - Token, client secret và giá trị header được mã hoá khi lưu và không bao giờ hiện lại — kể cả trên console hay trong trace.
- Kết quả của một lần gọi tool bị cắt ở 64 KB (xem Tool).