> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/work/maigpt/connectors/connectors-admin.md).

# 管理連接器（管理員）

組織管理員在「MaiGPT 連接器」頁為組織啟用連接器、設定 Service Account 認證與 contextData 允許清單、查看與撤銷成員授權、處理成員的啟用申請，以及新增組織私有的 MCP 伺服器。

成員要在 MaiGPT 使用 Notion、Google Drive 這類連接器，必須先由組織**啟用**，成員才能各自授權使用（成員端操作見 [連接器](/work/maigpt/connectors.md)）。本頁給組織管理員：在 <mark style="color:blue;">MaiGPT 連接器</mark> 頁決定組織開放哪些連接器、處理成員送來的申請，並接入公司自己的 MCP 伺服器。

## 誰可以使用 <a href="#who-can-use" id="who-can-use"></a>

* 角色需要 <mark style="color:blue;">MaiGPT 連接器管理權限</mark>，左側選單才會出現 <mark style="color:blue;">MaiGPT 連接器</mark>。組織擁有者預設具備。
* 成員**使用**連接器只需要 <mark style="color:blue;">MaiGPT 權限</mark>，不需要管理權限。
* 撤銷成員的授權只有**組織擁有者**能操作。

權限設定方式見 [角色權限管理](/org/roles/role-permission.md)。

## 進入方式 <a href="#how-to-access" id="how-to-access"></a>

從左側選單點 <mark style="color:blue;">MaiGPT 連接器</mark>。清單列出平台提供與組織自訂的所有連接器：

| 欄位                                     | 說明                                                                                                  |
| -------------------------------------- | --------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">連接器名稱</mark> | 有成員申請時，名稱旁會出現「N 位成員申請」標籤，滑鼠移上去可看申請者 Email                                                           |
| <mark style="color:blue;">來源</mark>    | <mark style="color:blue;">系統內建</mark>（平台提供）或 <mark style="color:blue;">組織自訂</mark>（你們新增的私有 MCP 伺服器） |
| <mark style="color:blue;">認證類型</mark>  | OAuth 2.0（成員各自授權）、Service Account（全組織共用一組認證）或 No Auth（無認證）                                          |
| <mark style="color:blue;">工具類別</mark>  | 對話中工具卡片的顯示分類；啟用後才能設定，選了立即儲存                                                                         |
| <mark style="color:blue;">啟用</mark>    | 是否為組織開放                                                                                             |
| <mark style="color:blue;">已授權成員</mark> | 已完成授權的成員數，旁邊的編輯圖示可查看名單                                                                              |
| <mark style="color:blue;">操作</mark>    | Service Account 連接器的認證設定；組織自訂連接器的編輯與刪除                                                              |

### 從「工具」頁進入 <a href="#access-from-tools-page" id="access-from-tools-page"></a>

組織自訂的連接器另有一個入口：<mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">工具</mark>，頁內第二欄切到 <mark style="color:blue;">管理連接器</mark>。頁首說明是「管理組織自訂的 MCP 連接器。連接器會同步至 MaiGPT 連接器，並可在其中選擇是否啟用。」清單只列組織自訂的連接器（不含系統內建），欄位為 <mark style="color:blue;">連接器</mark>、<mark style="color:blue;">MCP 伺服器網址</mark>、<mark style="color:blue;">驗證方式</mark>、<mark style="color:blue;">工具類別</mark>、<mark style="color:blue;">建立時間</mark> 與 <mark style="color:blue;">操作</mark>（編輯、刪除），右上角有 <mark style="color:blue;">新增連接器</mark> 與 <mark style="color:blue;">重新整理</mark>。這裡與本頁清單修改的是同一份資料；啟用／停用與成員授權仍在本頁操作。

## 為組織啟用連接器 <a href="#enable-connector" id="enable-connector"></a>

打開該列的 <mark style="color:blue;">啟用</mark> 開關，看到 <mark style="color:blue;">已成功啟用連接器</mark> 即完成。啟用後成員端的狀態依認證類型不同：

| 認證類型            | 啟用時                                                                           | 成員端                                                                 |
| --------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| OAuth 2.0       | 直接啟用                                                                          | 每位成員各自點 <mark style="color:blue;">授權</mark>，用自己的帳號登入該服務             |
| Service Account | 先跳出 <mark style="color:blue;">Service Account 認證</mark> 視窗，填入認證標頭後建立；按取消則開關還原 | 不需授權，所有人共用管理員填的認證；認證標頭空白時顯示 <mark style="color:blue;">需管理員設定</mark> |
| No Auth（無認證）    | 直接啟用                                                                          | 不需授權即可使用                                                            |

關閉開關（<mark style="color:blue;">已成功停用連接器</mark>）後，成員就無法再於對話中使用它；已授權成員的授權仍保留，重新啟用即可恢復。

### 開放給角色 <a href="#role-access" id="role-access"></a>

**系統內建**的連接器啟用後，還受角色的 MaiGPT 使用權限限制：成員的角色要在 <mark style="color:blue;">連接器</mark> 卡片勾「全部」或勾選這個連接器，才看得到授權按鈕；否則成員端顯示 <mark style="color:blue;">角色未開放</mark>。**組織自訂**的連接器不受角色限制。設定方式見 [MaiGPT 角色使用權限](/org/roles/maigpt-role-permissions.md#set-available-scope)。

## 處理成員的申請 <a href="#enablement-requests" id="enablement-requests"></a>

成員在 <mark style="color:blue;">管理我的連接器</mark> 看到不能用的連接器時，可以送出申請。系統會寄 Email 通知組織擁有者與具備 MaiGPT 連接器管理權限的人，並在本頁上方顯示「有 N 個連接器待處理成員的啟用申請」。

| 成員看到的狀態                                | 成員按的按鈕                                  | 你要做的事                                              |
| -------------------------------------- | --------------------------------------- | -------------------------------------------------- |
| <mark style="color:blue;">組織未啟用</mark> | <mark style="color:blue;">申請啟用</mark>   | 在本頁打開該連接器的 <mark style="color:blue;">啟用</mark> 開關  |
| <mark style="color:blue;">角色未開放</mark> | <mark style="color:blue;">向管理員申請</mark> | 連接器已啟用，請到申請者所屬角色的 MaiGPT 使用權限勾選這個連接器，或把申請者加入已開放的角色 |

完成後申請會自動消解，申請者會在 [通知中心](/start/notifications.md) 收到 <mark style="color:blue;">連接器已啟用</mark>。本頁沒有逐筆拒絕的按鈕；不打算開放時，請直接告知申請者。

## 查看與撤銷成員授權 <a href="#authorized-members" id="authorized-members"></a>

點 <mark style="color:blue;">已授權成員</mark> 欄的編輯圖示，開啟名單。每位成員顯示 <mark style="color:blue;">授權時間</mark>、<mark style="color:blue;">Token 過期時間</mark> 與狀態（<mark style="color:blue;">有效</mark>、<mark style="color:blue;">已過期</mark>、<mark style="color:blue;">永久有效</mark>）。

成員離職或不應再存取時，組織擁有者可按 <mark style="color:blue;">撤銷授權</mark>；撤銷後該成員要重新授權才能再用。撤銷只適用 OAuth 2.0 連接器。尚未啟用過的連接器沒有名單，會提示「此連接器尚未建立，請先啟用」。

## 設定 Service Account 認證 <a href="#service-account-auth" id="service-account-auth"></a>

Service Account 連接器啟用後，<mark style="color:blue;">操作</mark> 欄會出現設定圖示（<mark style="color:blue;">連接器認證設定</mark>）。

* <mark style="color:blue;">認證標頭</mark>：JSON 物件，例如 `{"Authorization": "Bearer your-token"}`。已設定的標頭只顯示遮蔽後的值；欄位留空會保留現有標頭，填寫則**整組覆蓋**。
* 標頭值可以用 <mark style="color:blue;">可用的情境變數</mark>，每次對話自動代入：`{{contact_id}}`（聯絡人 ID）、`{{source_id}}`（來源 ID）、`{{contact_name}}`（聯絡人名稱）、`{{conversation_id}}`（對話 ID）、`{{inbox_id}}`（收件匣 ID）、`{{organization_id}}`（組織 ID）。

### contextData 允許清單 <a href="#context-data-allowlist" id="context-data-allowlist"></a>

Agent 嵌入在你們的網站時，網站可以用 contextData 帶入自己的資料（例如會員編號），再寫進認證標頭：

1. 在網站的對話視窗嵌入設定中，把資料放進 contextData（做法見技術手冊〈[注入頁面 Context](https://docs.maiagent.ai/tech/serve/web-chat-sdk/web-chat-context-data)〉）。
2. 在 <mark style="color:blue;">允許的 contextData Keys</mark> 填入名稱，格式為 JSON 字串陣列，例如 `["patientToken"]`；最多 20 個，每個名稱限英文、數字與底線、1 至 64 個字元。
3. 在認證標頭的值寫 `{{context_data.patientToken}}`。

規則：三處名稱必須逐字相同並區分大小寫；沒列在允許清單的名稱一律取不到值；該次對話沒有值時，那一條標頭不會送出；只支援單層名稱，不支援 `a.b`。

## 新增私有 MCP 伺服器 <a href="#add-private-mcp" id="add-private-mcp"></a>

公司自建或第三方的 MCP 伺服器不在清單中時，可以新增為組織私有的連接器，只有你們組織看得到。在本頁新增的伺服器使用 **OAuth 2.0** 認證。

1. 按右上角 <mark style="color:blue;">新增連接器</mark>。
2. 填寫 <mark style="color:blue;">名稱</mark>（英文字母、數字、底線、連字符）與 <mark style="color:blue;">伺服器 URL</mark>（必須是 `https://`）；<mark style="color:blue;">顯示名稱</mark>、<mark style="color:blue;">描述</mark>、<mark style="color:blue;">工具類別</mark>、<mark style="color:blue;">Logo</mark>（PNG、JPG、GIF、WebP、SVG，2 MB 以內）可選填。
3. 授權伺服器無法自動偵測時，再填 <mark style="color:blue;">OAuth 伺服器 URL</mark>、<mark style="color:blue;">Resource Identifier</mark>、<mark style="color:blue;">OAuth Client ID</mark>、<mark style="color:blue;">OAuth Client Secret</mark>。各欄位說明見 [MCP 工具設定](/build/tools/mcp-setup.md#oauth-custom-connector)。
4. 按 <mark style="color:blue;">確認</mark>。系統會先測試能否連上伺服器，失敗時顯示錯誤原因（或 <mark style="color:blue;">連線測試失敗</mark>），不會建立；成功時顯示 <mark style="color:blue;">已成功新增伺服器</mark>，連接器自動啟用，來源標示為 <mark style="color:blue;">組織自訂</mark>。

同一批組織自訂連接器也會出現在 <mark style="color:blue;">工具</mark> 頁的 <mark style="color:blue;">管理連接器</mark>，兩邊修改的是同一份資料。

### 編輯與刪除 <a href="#edit-delete-private" id="edit-delete-private"></a>

* **編輯**：會影響所有使用相同 MCP 伺服器網址的工具。變更 <mark style="color:blue;">伺服器 URL</mark> 會讓這些工具對不上而失去授權，請謹慎修改。
* **刪除**：成員與聯絡人對這個連接器的授權會一併移除。若有工具使用這個連接器，確認視窗會列出受影響的工具與將被撤銷的授權數，按 <mark style="color:blue;">一併刪除</mark> 會連同這些工具一起刪除。

## 常見問題 <a href="#faq" id="faq"></a>

### 已經啟用了，成員仍看不到授權按鈕？ <a href="#faq-member-cannot-authorize" id="faq-member-cannot-authorize"></a>

請成員打開 <mark style="color:blue;">管理我的連接器</mark> 看狀態。顯示 <mark style="color:blue;">角色未開放</mark> 時，到成員角色的 MaiGPT 使用權限開放這個連接器，見 [開放給角色](#role-access)。

### 成員端顯示「需管理員設定」？ <a href="#faq-admin-setup-required" id="faq-admin-setup-required"></a>

這是 Service Account 連接器還沒有認證標頭。點該列的設定圖示填入 <mark style="color:blue;">認證標頭</mark> 並儲存，成員即可使用。

### 撤銷授權時出現錯誤？ <a href="#faq-revoke-error" id="faq-revoke-error"></a>

「僅組織擁有者可以撤銷成員授權」代表你不是組織擁有者；「只能撤銷 OAuth 類型連接器的授權」代表這個連接器不是成員各自授權的類型。

### 頁面上方的申請提示一直沒消失？ <a href="#faq-request-banner" id="faq-request-banner"></a>

若該連接器早已啟用，申請者遇到的是角色限制。打開開關無法消解這類申請，請改到申請者的角色開放這個連接器。

## 延伸閱讀 <a href="#further-reading" id="further-reading"></a>

* [連接器（成員端）](/work/maigpt/connectors.md)
* [MaiGPT 角色使用權限](/org/roles/maigpt-role-permissions.md)
* [MCP 工具設定](/build/tools/mcp-setup.md)
* [通知中心](/start/notifications.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/work/maigpt/connectors/connectors-admin.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.