Kết nối tùy chỉnh cho phép quản trị viên tổ chức đăng ký một API HTTPS hoặc, nếu được bật, một máy chủ Streamable HTTP MCP không có trong danh mục tích hợp sẵn. Định nghĩa kết nối xác định ranh giới mạng và phương thức xác thực. Nó không tự động tạo tài liệu tham khảo API đầy đủ cho tác nhân.
Ai cấu hình gì
- Quản trị viên tổ chức tạo, chỉnh sửa và xóa định nghĩa kết nối.
- Thành viên kết nối bí mật riêng hoặc hoàn thành quy trình OAuth của kết nối.
- Ủy quyền tác nhân kiểm soát tác nhân nào có thể sử dụng thông tin xác thực đã kết nối và các quyền được đặt tên mà họ nhận được.
Định nghĩa được chia sẻ trong tổ chức. Thông tin xác thực của thành viên vẫn chỉ thuộc phạm vi thành viên đó và tổ chức.
Kết nối API HTTP
- Mở Kết nối → Tùy chỉnh và chọn Kết nối mới.
- Chọn HTTP API và nhập tên hiển thị.
- Thêm một hoặc nhiều Tiền tố HTTPS, mỗi dòng một tiền tố. Một yêu cầu phải khớp với một tiền tố đã cấu hình trước khi kết nối có thể cho phép yêu cầu đó.
- Thêm xác thực nếu API yêu cầu:
- Xác thực API: nhập tên header và mẫu header chứa
{{secret}}, ví dụAuthorizationvàBearer {{secret}}. - OAuth 2.0: nhập URL ủy quyền, URL token, client ID, client secret, phạm vi và phương thức xác thực endpoint token. Đăng ký chính xác URL chuyển hướng hiển thị trong biểu mẫu với nhà cung cấp.
- Xác thực API: nhập tên header và mẫu header chứa
- Tạo kết nối. Mỗi thành viên cần sử dụng sẽ chọn Kết nối và cung cấp bí mật hoặc hoàn thành OAuth.
- Ủy quyền tác nhân và quyền cần thiết.
Thay đổi định nghĩa OAuth hiện tại hoặc thông tin client sẽ ngắt kết nối OAuth hiện có. Thành viên phải kết nối lại sau khi thay đổi.
Kết nối MCP
Nếu MCP xuất hiện là loại kết nối trong không gian làm việc của bạn, hãy nhập endpoint Streamable HTTP MCP qua HTTPS và cấu hình xác thực API hoặc OAuth trong cùng biểu mẫu. Nếu MCP không xuất hiện trong danh sách chọn, nó chưa được bật cho không gian làm việc đó.
Hướng dẫn tác nhân quy trình API
Kết nối tùy chỉnh cung cấp quyền truy cập mạng an toàn và chèn thông tin xác thực. Biểu mẫu tạo không tải lên hoặc tự động phát hiện tài liệu OpenAPI. Hãy cung cấp cho tác nhân endpoint, phương thức, tham số và phản hồi mong đợi trong yêu cầu, hoặc ghi lại quy trình đó trong một quy trình làm việc với tài liệu tham khảo API đính kèm dưới dạng tệp.
Hãy xác thực kết nối mới bằng một yêu cầu chỉ đọc, phạm vi hẹp tới một endpoint đã biết. Không có yêu cầu Kiểm tra kết nối chung vì nhiều API không cung cấp endpoint gốc có ý nghĩa.
Ranh giới bảo mật
- Chỉ chấp nhận tiền tố HTTPS và endpoint MCP.
- Tường lửa chỉ chèn thông tin xác thực đã lưu vào các yêu cầu phù hợp.
- Bí mật đã lưu được mã hóa khi lưu trữ và không hiển thị cho tác nhân dưới dạng biến môi trường.
- Không đưa khóa, token hoặc client secret vào tin nhắn trò chuyện, hướng dẫn quy trình làm việc hoặc tệp đính kèm.
- Sử dụng thông tin xác thực dịch vụ với phạm vi tối thiểu cần thiết cho quy trình làm việc.
Khắc phục sự cố
| Vấn đề | Kiểm tra |
|---|---|
| Kết nối mới không khả dụng | Chỉ quản trị viên tổ chức mới có thể tạo hoặc chỉnh sửa định nghĩa kết nối. |
| Tác nhân không thấy kết nối | Kết nối cho thành viên hiện tại, sau đó ủy quyền cho tác nhân đó. |
| Yêu cầu bị chặn trước khi đến API | Xác nhận URL yêu cầu bắt đầu bằng một trong các tiền tố HTTPS đã cấu hình. |
| API trả về 401 hoặc 403 | Kết nối lại thông tin xác thực thành viên và kiểm tra khóa upstream hoặc phạm vi OAuth. |
| OAuth trả về lỗi chuyển hướng | Đăng ký chính xác URL chuyển hướng hiển thị trong biểu mẫu kết nối và kiểm tra URL ủy quyền, token. |
| Tác nhân đoán sai endpoint hoặc payload | Đưa quy trình API vào quy trình làm việc và đính kèm tài liệu tham khảo phù hợp thay vì chỉ dựa vào tên kết nối. |
Tiếp theo
- Xem Quy trình làm việc để ghi lại các công việc lặp lại với kết nối tùy chỉnh.
- Xem Quyền để biết cách xử lý thông tin xác thực kết nối tùy chỉnh.
- Xem Danh mục trước khi xây dựng tùy chỉnh — dịch vụ của bạn có thể đã được hỗ trợ.
