> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agents.fpt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kết nối (Connectors)

> Nơi agent được phép chạm tới hệ thống khác

Instructions cho agent biết phải làm gì, kết nối mới cho agent tay chân để làm. Trong trang agent, mục **Kết nối** nằm ở cột **Cấu hình** bên phải màn hình **Dựng agent**.

## Cách gắn một kết nối cho agent

<Steps>
  <Step title="Nhấn dấu + ở mục Kết nối">
    Console hỏi bạn chọn kiểu tài khoản: **Dùng chung** (một tài khoản của workspace) hoặc **Theo người dùng** (tài khoản riêng của mỗi người).
  </Step>

  <Step title="Chọn connector">
    Hộp thoại liệt kê connector theo nhóm — Analytics, Documents, Email, Productivity… Bạn tìm theo tên, tích từng cái hoặc **Chọn tất cả**. Connector đã gắn rồi sẽ hiện nhãn *Đã thêm* kèm kiểu tài khoản đang dùng.
  </Step>

  <Step title="Nhấn Xong">
    Connector xuất hiện trong danh sách, sẵn sàng để bạn chỉnh quyền cho từng công cụ bên trong.
  </Step>
</Steps>

Nếu hệ thống cần dùng chưa có trong danh sách, dùng **Thêm MCP tùy chỉnh** để đấu nối một MCP server riêng.

| Kiểu tài khoản | Khi agent chạy |
| - | - |
| **Dùng chung** | Agent dùng một tài khoản chung của workspace. Người dùng không phải khai báo gì |
| **Theo người dùng** | Mỗi người tự kết nối tài khoản của mình; agent chỉ thấy dữ liệu người đó có quyền |

Hộp thư, lịch, tài liệu cá nhân thì nên để **theo người dùng**. Nguồn dùng chung của cả tổ chức — CRM, hệ thống ticket — thường hợp với **dùng chung** hơn.

## Mỗi connector là một bộ công cụ

Gắn connector không có nghĩa là mở toàn bộ hệ thống. Bên trong mỗi connector là danh sách **công cụ (tools)** — từng hành động cụ thể agent có thể gọi. Nhấn vào tên connector trong danh sách để bung ra xem.

Ví dụ **SharePoint** có 12 công cụ, chia thành ba nhóm việc:

| Nhóm | Công cụ |
| - | - |
| **Tìm và duyệt** | Search SharePoint · List SharePoint drives · List SharePoint files · Get SharePoint item |
| **Đọc nội dung** | Read SharePoint text file · Read SharePoint Word file · Read SharePoint PDF file · List Excel worksheets · Read Excel range |
| **Ghi và chia sẻ** | Edit SharePoint text file · Edit Excel cell · Create SharePoint share link |

Nhìn vào danh sách này là biết ngay agent có thể chạm tới đâu: đọc file Word, PDF, bảng Excel trong SharePoint/OneDrive, và nếu được cho phép thì ghi đè nội dung file hay tạo link chia sẻ.

## Ba mức quyền cho từng công cụ

Mỗi công cụ có một mức quyền riêng, đặt ngay dưới tên nó:

| Mức | Agent làm gì | Nên dùng cho |
| - | - | - |
| **Tự động** | Gọi công cụ ngay, không hỏi ai | Việc chỉ đọc, không đổi dữ liệu gì |
| **Hỏi** | Dừng lại xin phép người dùng trước khi chạy | Việc ghi, sửa, chia sẻ ra ngoài |
| **Chặn** | Không được gọi công cụ này, dù Instructions có yêu cầu | Hành động agent này không có lý do gì phải làm |
| | | |

Số **ngoại lệ** hiện cạnh tên connector cho biết có bao nhiêu công cụ đang khác mức mặc định — liếc qua là biết agent đã được siết ở đâu.

## Ví dụ: một cấu hình SharePoint hợp lý

Với một agent trợ lý email và lịch, cách đặt quyền thường thấy:

* **Tự động** cho toàn bộ nhóm tìm kiếm và đọc — agent cần tra tài liệu liên tục, mà đọc thì không làm hỏng gì.
* **Hỏi** cho `Edit SharePoint text file`, `Edit Excel cell` và `Create SharePoint share link` — ba việc này ghi đè nội dung hoặc tạo link người ngoài mở được, nên phải có người gật đầu.

Kết quả: connector hiện **3 ngoại lệ**, đúng bằng ba công cụ đã chuyển sang *Hỏi*.

<Warning>
  Quyền ở đây chỉ giới hạn *hành động*, không nới rộng *dữ liệu*. Agent vẫn chỉ thấy những gì tài khoản kết nối được phép thấy — đặt **Tự động** cũng không giúp nó đọc được thư mục mà tài khoản đó không có quyền.
</Warning>

<img src="https://mintcdn.com/fpt-62e894b4/MLGg3fcpvPErRgBt/images/agent-ket-noi-quyen.jpg?fit=max&auto=format&n=MLGg3fcpvPErRgBt&q=85&s=6d0ff18493bdf86bfd76e69043a793cd" alt="Agent Ket Noi Quyen" width="1568" height="772" data-path="images/agent-ket-noi-quyen.jpg" />

## Thêm MCP tùy chỉnh

Hệ thống bạn cần chưa có trong Marketplace thì tự đấu nối MCP server riêng: Mở **Kết nối**, chọn tab **Custom Connectors**, nhấn **Thêm MCP tùy chỉnh**.

<img src="https://mintcdn.com/fpt-62e894b4/91oWXyIxHSR9EXmO/images/mcp_oauth_manual.jpg?fit=max&auto=format&n=91oWXyIxHSR9EXmO&q=85&s=7ccc13139408be1a9a48eb0e72e54b48" alt="Thêm MCP tùy chỉnh với xác thực OAuth 2.1" width="1562" height="784" data-path="images/mcp_oauth_manual.jpg" />

| Trường | Bắt buộc | Ý nghĩa | Ví dụ |
| - | - | - | - |
| Tên | Có | Tên hiển thị của server trong danh sách Custom Connectors | my-mcp-server |
| URL | Có | Địa chỉ endpoint MCP của server | [https://api.example.com/mcp](https://api.example.com/mcp) |
| Xác thực | Có | Cách server kiểm tra danh tính, xem bảng bên dưới | OAuth 2.1 (Auto) |

### Bốn kiểu xác thực

| Kiểu | Khi nào dùng |
| - | - |
| **Không xác thực** | Server mở, không yêu cầu danh tính |
| **Static Headers** | Server nhận API key hoặc token cố định qua header |
| **OAuth 2.1 (Auto)** | Server có công bố metadata OAuth. Console đọc metadata của chính server và tự đăng ký client, bạn không phải điền thêm gì |
| **OAuth 2.1 (Manual)** | Server không công bố metadata OAuth, hoặc không cho đăng ký client tự động. Bạn dán các thông số lấy từ tài liệu của server |

<Info icon="shield-check">
  OAuth 2.1 là chuẩn chung, không gắn với một nhà cung cấp cụ thể. Server nào nói chuyện được bằng OAuth 2.1 đều kết nối được.
</Info>

### Các trường của OAuth 2.1 (Manual)

| Trường | Bắt buộc | Ý nghĩa |
| - | - | - |
| Authorize URL | Có | Địa chỉ người dùng được chuyển tới để đồng ý cấp quyền |
| Token URL | Có | Địa chỉ Console đổi mã ủy quyền lấy access token |
| Client ID | Có | Mã client do server cấp cho ứng dụng |
| Client secret | Không | Nằm trong mục **Nâng cao**. Phần lớn server OAuth 2.1 không cấp secret vì PKCE đã bảo vệ public client. Để trống trừ khi server cấp cho bạn |
| Scope | Không | Nằm trong mục **Nâng cao**. Cách nhau bằng dấu cách hoặc dấu phẩy. Để trống để dùng đúng scope server yêu cầu |

<Steps>
  <Step title="Mở hộp thoại">
    Vào **Kết nối**, chọn tab **Custom Connectors**, nhấn **Thêm MCP tùy chỉnh**.
  </Step>

  <Step title="Điền tên và URL">
    Đặt tên dễ nhận ra trong danh sách, rồi dán endpoint MCP của server.
  </Step>

  <Step title="Chọn kiểu xác thực">
    Thử **OAuth 2.1 (Auto)** trước. Chỉ chuyển sang **OAuth 2.1 (Manual)** khi server không tự khai báo được.
  </Step>

  <Step title="Lưu server">
    Nhấn **Lưu server**. Server xuất hiện trong danh sách Custom Connectors, sẵn sàng gắn vào agent như mọi Connector khác.
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.