> 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/tools/setup-contacts-mcp-credentials.md).

# 聯絡人 MCP 憑證設定

### 一、功能背景介紹 <a href="#section-1-background" id="section-1-background"></a>

<figure><img src="/files/ZpOuIWUKhC06ZNJEk1ZI" alt=""><figcaption></figcaption></figure>

#### 什麼是 MCP 憑證功能 <a href="#what-is-mcp-credential" id="what-is-mcp-credential"></a>

MCP 憑證功能就像是「幫每個客戶設定專屬的通行證」。當多個客戶需要使用同一個工具查詢他們自己的資料時，每個人需要有自己的「鑰匙」（憑證），這樣才能確保每個人只能看到自己的資料，不會看到別人的。

**簡單比喻**\
就像公寓大樓，所有住戶都用同一個電梯（MCP 工具），但每個人要刷自己的門禁卡（憑證）才能進入自己的樓層。

#### 為什麼需要此功能 <a href="#why-this-feature-is-needed" id="why-this-feature-is-needed"></a>

* **保護客戶隱私** — 每個客戶使用自己的憑證，確保資料不會混在一起
* **個別化服務** — 不同客戶可以有不同的使用權限
* **方便管理** — 當客戶的憑證過期或需要更換時，只需要更新那一個客戶的設定

#### 使用場景舉例 <a href="#use-case-examples" id="use-case-examples"></a>

**場景 1：個人資料查詢**\
客戶 A 和客戶 B 都要查詢自己的消費記錄，但他們各自有不同的帳號密碼

**場景 2：部門權限管理**\
不同部門使用同一個查詢工具，但有不同的查看權限

**場景 3：分級服務**\
VIP 客戶可以查詢更詳細的資料，一般客戶只能查詢基本資料

***

### 二、功能位置與使用準備 <a href="#section-2-location-and-prerequisites" id="section-2-location-and-prerequisites"></a>

#### 在哪裡找到這個功能 <a href="#where-to-find-this-feature" id="where-to-find-this-feature"></a>

**操作路徑**\
聯絡人管理 → 點擊編輯聯絡人 → 切換到「MCP 憑證」標籤頁

<figure><img src="/files/d08wiPo8K2gHuBFVaXni" alt=""><figcaption></figcaption></figure>

**重要提醒**\
需要先建立並儲存聯絡人後，才能設定 MCP 憑證（確保憑證能正確綁定到聯絡人）

#### 使用前的準備 <a href="#prerequisites" id="prerequisites"></a>

在開始設定之前，請確認以下事項：

1. 系統中已經有建立好的 MCP 工具（AI功能 → 工具 → MCP）

   <figure><img src="/files/7MvKydX8L6UYaJKv2jgU" alt=""><figcaption></figcaption></figure>
2. 要配置憑證的聯絡人已經建立並儲存
3. 已經拿到該聯絡人的憑證資訊（通常由客戶或有權限的人員提供）

> **權限說明**\
> 系統管理員可以根據組織需求，彈性分配「工具」和「聯絡人」的功能權限。

***

### 三、操作說明 <a href="#section-3-instructions" id="section-3-instructions"></a>

#### 3.1 查看可以設定的工具 <a href="#view-configurable-tools" id="view-configurable-tools"></a>

**操作步驟**

1. 點開要編輯的聯絡人
2. 點擊上方的「MCP 憑證」標籤
3. 會看到所有可以設定的工具列表

**工具列表說明**

每個工具會顯示：

* **工具名稱**（例如：「客戶資料庫查詢」）
* **工具說明**（如果有的話，會以灰色小字顯示在名稱下方）
* **編輯按鈕**（右側的鉛筆圖示）

**如何分辨設定狀態**

* **已設定過** → 工具名稱右邊會出現綠色的「已設定」標籤
* **還沒設定** → 工具名稱右邊沒有任何標籤

***

#### 3.2 新增或修改憑證 <a href="#add-or-edit-credential" id="add-or-edit-credential"></a>

**步驟 1：打開設定區**

點擊工具右邊的「編輯」按鈕（鉛筆圖示），會展開設定區域

**步驟 2：填寫 Headers（憑證資訊）**

在文字框中貼上憑證資訊，格式是 JSON：

```json
{"Authorization": "Bearer 這裡是鑰匙代碼"}
```

不確定格式的話，可以點「**格式化 JSON**」按鈕自動整理

{% hint style="info" %}
**什麼是 Headers？**\
Headers 就是「身份證明文件」，裡面包含了這個聯絡人的專屬鑰匙。就像你去銀行辦事需要帶身份證，系統需要這個 Headers 來確認「這個人是誰」。
{% endhint %}

{% hint style="info" %}
**什麼是 JSON？**\
JSON 是一種資料格式，看起來像：`{"欄位名稱": "內容"}`。不用擔心，通常會有人直接提供給你，你只需要複製貼上就好。
{% endhint %}

**步驟 3：注意事項**

* Headers 是**必填**的（有紅色 \* 號標記）
* 填入的 Headers 會**取代**工具原本的預設設定

{% hint style="info" %}
**重要**：不同 MCP 工具需要的 Headers 格式不一樣，請務必確認你拿到的憑證格式跟這個工具相符
{% endhint %}

**步驟 4：儲存或取消**

**儲存設定**

* 確認沒問題後，點右下角的「**儲存**」按鈕
* 系統會檢查格式是否正確
* 儲存成功後：
  * 編輯區會自動收起
  * 工具名稱右邊會出現**綠色的「已設定」標籤**（第一次設定時才會新出現）

**取消編輯**

* 如果不想儲存，點「取消」即可

***

#### 3.3 重置憑證（清除已設定的憑證） <a href="#reset-credential" id="reset-credential"></a>

**什麼時候會用到？**

當憑證設定錯誤，或是不再需要這個憑證時，可以重置。

**如何操作**

1. 點擊工具的「編輯」按鈕，展開編輯區
2. 如果這個工具已經設定過憑證（有綠色「已設定」標籤），左下角會出現紅色的「**重置憑證**」按鈕
3. 點擊後確認，憑證就會被清除
4. 清除後，工具名稱右邊的綠色「已設定」標籤會消失

**⚠️ 重要提醒**

* 重置後**無法復原**
* 建議重置前先把 Headers 內容複製保存
* 如果只是要修改內容，直接編輯就好，不需要重置

***

### 四、操作範例 <a href="#section-4-examples" id="section-4-examples"></a>

#### 範例 1：為客戶設定資料庫查詢憑證 <a href="#example-1-database-query-credential" id="example-1-database-query-credential"></a>

**情境說明**

客戶 A 要查詢他自己的消費記錄，你拿到了一組憑證代碼。

**Headers 內容**

```json
{
  "apikey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**操作步驟**

1. 找到聯絡人「客戶 A」，點擊編輯
2. 切換到「MCP 憑證」標籤
3. 找到「客戶資料庫查詢」工具，點編輯按鈕
4. 把憑證代碼貼上
5. 點「格式化 JSON」確保格式整齊
6. 點儲存

***

#### 範例 2：為部門設定專用查詢憑證 <a href="#example-2-department-specific-credential" id="example-2-department-specific-credential"></a>

**情境說明**

業務部需要查客戶資料，但只能看基本資料，不能看財務資料。

**Headers 內容**

```json
{
  "X-API-Key": "dept_sales_abc123",
  "X-Department": "sales"
}
```

**欄位說明**

* `X-API-Key` — 業務部的專用鑰匙
* `X-Department` — 標示這是業務部在用

***

#### 範例 3：設定多個欄位的憑證 <a href="#example-3-multi-field-credential" id="example-3-multi-field-credential"></a>

**Headers 內容**

```json
{
  "Authorization": "Bearer token_xyz",
  "X-Client-ID": "client_12345",
  "Content-Type": "application/json"
}
```

**欄位說明**

* `Authorization` — 主要的身份驗證鑰匙
* `X-Client-ID` — 客戶編號
* `Content-Type` — 資料格式說明（通常固定是這個）

***

### 五、聯絡人 MCP vs 工具 MCP 的差異 <a href="#section-5-contacts-mcp-vs-tool-mcp" id="section-5-contacts-mcp-vs-tool-mcp"></a>

#### 功能比較表 <a href="#feature-comparison-table" id="feature-comparison-table"></a>

| 比較項目      | 工具 → MCP                              | 聯絡人 → MCP 憑證                         |
| --------- | ------------------------------------- | ------------------------------------ |
| **是什麼**   | 建立工具本身                                | 幫個別聯絡人設定專屬憑證                         |
| **設定範圍**  | 整個系統都能用                               | 只給特定聯絡人用                             |
| **設定內容**  | <p>• 工具的網址<br>• 預設的憑證<br>• 可以做哪些事</p> | <p>• 只設定這個人的憑證<br>• 會取代預設憑證</p>      |
| **什麼時候用** | 第一次要接入新工具時                            | 每個客戶要用不同憑證時                          |
| **誰可以操作** | 有權限即可操作                               | 有權限即可操作                              |
| **在哪裡設定** | 工具管理頁面                                | 聯絡人編輯頁面                              |
| **常見用途**  | <p>• 新增一個查詢工具<br>• 設定工具的基本資料</p>      | <p>• 每個客戶用自己的帳密<br>• VIP 客戶有特殊權限</p> |

#### 簡單理解：電腦教室比喻 <a href="#analogy-computer-lab" id="analogy-computer-lab"></a>

想像一下學校的電腦教室：

**工具 MCP（有權限的人員建立）**

* 在電腦教室安裝軟體
* 設定所有電腦都能用這個軟體
* 決定軟體有哪些功能

**聯絡人 MCP 憑證**

* 幫每個學生建立自己的帳號
* 每個學生用自己的帳號登入
* 不同學生可以有不同的使用權限

#### 實際工作流程 <a href="#actual-workflow" id="actual-workflow"></a>

```
第一步：建立 MCP 工具（有建立工具權限的人員）
    ↓
建立「客戶資料庫查詢」工具
- 設定工具網址
- 設定預設憑證（如果有的話）
    ↓
第二步：為每個聯絡人設定專屬憑證（有設定憑證權限的人員）
    ↓
客戶 A：設定 A 的專屬憑證
客戶 B：設定 B 的專屬憑證
客戶 C：設定 C 的專屬憑證
    ↓
結果：大家用同一個工具，但各自用自己的憑證
```

> **權限彈性**\
> 系統管理員可以根據組織需求，決定誰可以建立工具、誰可以設定憑證。可以是同一批人，也可以分開管理。

#### 重點整理 <a href="#key-summary" id="key-summary"></a>

* **工具 MCP** — 先有「工具」才能用
* **聯絡人 MCP 憑證** — 再給每個人「鑰匙」

***

### 六、常見問題 <a href="#section-6-faq" id="section-6-faq"></a>

#### Q1：為什麼我看不到「MCP 憑證」標籤？ <a href="#faq-1-cannot-see-mcp-credential-tab" id="faq-1-cannot-see-mcp-credential-tab"></a>

**可能原因**

* 你是在「新增聯絡人」（要先儲存聯絡人後，再進來編輯才看得到）
* 系統裡還沒有建立任何 MCP 工具
* 聯絡人資料還沒儲存

**解決方法**

1. 先把聯絡人基本資料填好並儲存
2. 確認系統有 MCP 工具（請有權限的人員確認）
3. 重新進入編輯模式

***

#### Q2：Headers 格式錯誤怎麼辦？ <a href="#faq-2-headers-format-error" id="faq-2-headers-format-error"></a>

**常見錯誤範例**

* ❌ 錯誤：`{'key': 'value'}`（用了單引號）
* ❌ 錯誤：`{key: value}`（沒有引號）
* ❌ 錯誤：`{"key": "value",}`（最後多了逗號）
* ✅ 正確：`{"key": "value"}`

**解決方法**

1. 點「格式化 JSON」按鈕，系統會自動檢查
2. 如果還是有問題，請把憑證重新複製一次
3. 或是請提供憑證的人再確認一次格式

***

#### Q3：我怎麼知道要填什麼內容？ <a href="#faq-3-what-to-fill-in" id="faq-3-what-to-fill-in"></a>

**取得憑證的方式**

1. 請客戶提供他們的憑證資訊
2. 請負責人員提供或協助建立
3. 詢問負責這個工具的同事
4. 參考其他已經設定成功的聯絡人（但不要直接複製！）

**⚠️ 不要自己亂填**

憑證都是有特定格式和內容的，填錯了工具會無法使用，還可能造成資料錯誤。

***

#### Q4：為什麼我看不到「已設定」標籤？ <a href="#faq-4-cannot-see-configured-badge" id="faq-4-cannot-see-configured-badge"></a>

**顯示條件**

* 只有「已經設定過憑證」的工具才會顯示這個綠色標籤
* 第一次設定時，在儲存成功前不會看到
* 儲存成功後，標籤才會出現

**工具列表都沒有標籤？**

代表這個聯絡人還沒有設定過任何 MCP 憑證，這是正常的。

***

#### Q5：找不到「重置憑證」按鈕？ <a href="#faq-5-cannot-find-reset-credential-button" id="faq-5-cannot-find-reset-credential-button"></a>

**顯示條件（需同時滿足）**

1. 這個工具已經設定過憑證（工具名稱右邊有綠色「已設定」標籤）
2. 你有點擊「編輯」按鈕展開編輯區

**按鈕位置**

展開編輯區後，紅色的「重置憑證」按鈕在左下角，「取消」和「儲存」按鈕在右下角。

**工具還沒設定憑證？**

不會有「重置憑證」按鈕，因為沒有憑證可以重置。這時候左下角會是空白的。

***

#### Q6：按了「重置憑證」會怎樣？ <a href="#faq-6-what-happens-after-reset" id="faq-6-what-happens-after-reset"></a>

**會發生的事**

* 這個聯絡人的專屬憑證會被清除
* 工具名稱右邊的綠色「已設定」標籤會消失
* 如果工具有預設憑證，會改用預設的（但通常沒有）
* ⚠️ **刪除後無法復原**

**建議做法**

* 先把 Headers 內容複製備份
* 想清楚是否真的要刪除
* 如果只是要修改內容，用「編輯」就好

***

#### Q7：多個聯絡人可以用同一組憑證嗎？ <a href="#faq-7-multiple-contacts-share-credential" id="faq-7-multiple-contacts-share-credential"></a>

**技術上可以**

系統不會擋你複製同樣的憑證給不同人

**但是不建議**

* 沒辦法知道是誰在使用
* 資料可能會混在一起
* 有人出問題時，不知道是誰的問題

**正確做法**

* 每個聯絡人用自己的憑證
* 保持資料清楚分開
* 方便追蹤和管理

***

#### Q8：工具列表是空的，顯示「暫無可用工具」？ <a href="#faq-8-tool-list-empty" id="faq-8-tool-list-empty"></a>

**可能原因**

* 系統還沒有建立 MCP 工具
* 所有工具都是「全域」類型（全域工具不需要個別設定憑證）

**解決方法**

1. 請有建立工具權限的人員確認是否已建立 MCP 工具
2. 確認工具類型設定正確
3. 如果都正常但還是看不到，請聯繫技術支援

***

### 附錄：操作檢查清單 <a href="#appendix-checklist" id="appendix-checklist"></a>

#### 設定前確認 <a href="#pre-setup-checklist" id="pre-setup-checklist"></a>

* [ ] 聯絡人已經建立並儲存了
* [ ] 系統有可用的 MCP 工具
* [ ] 已經拿到憑證資訊（從客戶或負責人員那裡）
* [ ] 確認憑證格式正確

#### 設定時確認 <a href="#during-setup-checklist" id="during-setup-checklist"></a>

* [ ] Headers 格式正確（可以用格式化按鈕檢查）
* [ ] 該填的欄位都有填
* [ ] 沒有多餘或錯誤的內容
* [ ] 點格式化後沒有出現錯誤訊息

#### 設定後確認 <a href="#post-setup-checklist" id="post-setup-checklist"></a>

* [ ] 工具名稱右邊出現綠色「已設定」標籤
* [ ] 實際測試工具可以正常使用
* [ ] 把設定資訊記錄下來（日期、聯絡人、工具名稱）
* [ ] 如果需要，通知相關人員已完成設定


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/tools/setup-contacts-mcp-credentials.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.