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

# 建立 MCP 工具

本指南將引導您在平台中建立新的 MCP 工具。

## MCP 是什麼？ <a href="#what-is-mcp" id="what-is-mcp"></a>

MCP（Model Context Protocol）是讓 AI 連接外部工具的標準協定：Agent 透過網址連線遠端的 MCP 伺服器，就能使用該服務提供的工具。

### **MCP 解決方案** <a href="#mcp-solution" id="mcp-solution"></a>

同一個 MCP 伺服器開發一次，所有支援 MCP 的 AI 平台都能使用；協定的運作原理、MaiAgent 支援的傳輸方式與限制，見技術手冊的 [MCP（Model Context Protocol）](https://docs.maiagent.ai/tech/mcp/mcp-model-context-protocol)。

## 快速建立 MCP 工具 <a href="#quick-create-mcp-tool" id="quick-create-mcp-tool"></a>

### 1. 進入工具管理介面 <a href="#step-1-enter-tool-management" id="step-1-enter-tool-management"></a>

首先，請從左側選單進入 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">工具</mark>。進入工具列表頁面後，點選右上角的 <mark style="color:blue;">新增工具</mark> 按鈕。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-804dd5ac3ff8177e6576f5a48ecf21d57dc3ee79%2Fmcp-tools-list.png?alt=media" alt="工具列表頁面，左側有工具列表與管理連接器，右上角有新增工具按鈕"><figcaption><p>點擊「新增工具」開始建立</p></figcaption></figure>

### 2. 選擇工具類型 <a href="#step-2-select-tool-type" id="step-2-select-tool-type"></a>

工具類型請選擇 <mark style="color:blue;">MCP</mark>。

### 3. 設定顯示名稱 <a href="#step-3-set-display-name" id="step-3-set-display-name"></a>

為工具設定清晰的顯示名稱，這邊設為 <mark style="color:blue;">Composio mcp for google calendar</mark>。

* **用途**：此名稱將會顯示在平台介面中，供所有用戶查看。
* **建議**：選擇一個能清晰表達工具主要功能的名稱，方便用戶理解。此名稱沒有嚴格的格式限制。

### 4. 填寫 MCP 配置 <a href="#step-4-configure-mcp" id="step-4-configure-mcp"></a>

MaiAgent 以網址連接遠端的 MCP 伺服器（支援 SSE 與 Streamable HTTP 串流協定），不支援以 `npx`、`node` 等本機指令啟動的 MCP 伺服器，因此「<mark style="color:blue;">MCP 配置</mark>」只需要設定伺服器網址與驗證方式，伺服器需要的金鑰一律透過標頭或 OAuth 授權提供。

請先確認 MCP 伺服器的驗證方式，再依下表設定：

| 伺服器的驗證方式                         | 怎麼設定                                                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| OAuth 登入（使用者登入對方服務並同意授權）         | 在「<mark style="color:blue;">選擇要連接的服務</mark>」選擇連接器，見 [b. OAuth 連接器與授權對象](#oauth-connector)                                                  |
| 固定的 API Key 或 Token（全組織共用），或不需驗證 | 在「<mark style="color:blue;">或直接輸入（無認證 / Service Account）</mark>」下方輸入網址，見 [a. MCP 伺服器網址](#mcp-server-url)；金鑰填在 [c. 標頭 (JSON)](#mcp-headers) |
| 每位聯絡人使用自己的 API Key 或 Token       | 依上一列建立工具，再到聯絡人的「<mark style="color:blue;">MCP 憑證</mark>」分頁設定，見 [聯絡人 MCP 憑證設定](/build/tools/setup-contacts-mcp-credentials.md)              |

#### a. 🔗MCP 伺服器網址 <a href="#mcp-server-url" id="mcp-server-url"></a>

* **用途**：Agent 透過這個網址連線 MCP 伺服器，取得並呼叫伺服器提供的工具。
* **填寫位置**：
  * 伺服器使用 OAuth：在「<mark style="color:blue;">選擇要連接的服務</mark>」點選連接器卡片，網址會自動帶入，見下方 [b. OAuth 連接器與授權對象](#oauth-connector)。
  * 伺服器不需驗證或使用固定金鑰：在「<mark style="color:blue;">或直接輸入（無認證 / Service Account）</mark>」下方的輸入框貼上完整網址，例如 `https://mcp.example.com/mcp`。
* **格式**：必須以 `https://` 開頭，且是可從網際網路連線的遠端伺服器位址。`localhost` 與內部網路位址無法儲存；地端部署若需連線內部網路的 MCP 伺服器，請洽 MaiAgent 協助開放。
* **注意**：此欄位為必填。

{% hint style="info" %}
如何獲得 MCP 網址，請參考[技術人員手冊—Remote MCP 服務概述](https://docs.maiagent.ai/tech/mcp/remote-mcp)
{% endhint %}

{% hint style="info" %}
若 MCP 伺服器需要辨識「目前對話的使用者」：訪客以 Keycloak 登入 Web Chat 時，可在對話平台開啟 [沿用 Keycloak 登入身分呼叫工具](/build/choose-channel/web-chat.md#keycloak-token-passthrough)，並把此 MCP 伺服器的主機加入允許名單，平台會以 `Authorization` 標頭帶上訪客本人的 Keycloak 憑證。
{% endhint %}

直接輸入網址的工具，在「<mark style="color:blue;">允許的工具 (JSON 數組)</mark>」取得工具清單時，系統會用網址與「<mark style="color:blue;">標頭 (JSON)</mark>」連線伺服器；連線失敗時畫面會顯示原因，例如「<mark style="color:blue;">MCP 伺服器回應 HTTP 405。請確認網址指向 MCP 端點。</mark>」，請依提示檢查網址與標頭。儲存時系統會再連線驗證一次，失敗時出現「<mark style="color:blue;">MCP 工具驗證失敗，無法連接 MCP 伺服器</mark>」。使用 OAuth 連接器的工具會先儲存，完成授權後才取得工具清單。

#### b. 🔐 OAuth 連接器與授權對象 <a href="#oauth-connector" id="oauth-connector"></a>

MCP 伺服器使用 OAuth 時，MaiAgent 會代為完成授權流程，呼叫時自動帶入存取權杖，不需要在標頭填寫金鑰。

{% stepper %}
{% step %}

### 選擇連接器 <a href="#oauth-select-connector" id="oauth-select-connector"></a>

在「<mark style="color:blue;">選擇要連接的服務</mark>」點選要連接的服務卡片（標示 <mark style="color:blue;">OAuth 2.0</mark>），伺服器網址會自動帶入。清單包含平台已驗證的服務，以及組織自訂的連接器。
{% endstep %}

{% step %}

### 找不到服務時自訂連接器 <a href="#oauth-custom-connector" id="oauth-custom-connector"></a>

點選最後一張「<mark style="color:blue;">自訂連接器來源</mark>」，填寫下列欄位後點擊「<mark style="color:blue;">新增連接器</mark>」。系統會先測試能否連線該伺服器，成功後回到卡片清單並自動選定新的連接器。

| 欄位                                                   | 必填 | 說明                                                                                                                                       |
| ---------------------------------------------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">名稱</mark>                  | 是  | 連接器的識別名稱，只能包含英文字母、數字、底線和連字符，例如 `my-mcp-server`                                                                                           |
| <mark style="color:blue;">顯示名稱</mark>                | 否  | 顯示在卡片上的名稱                                                                                                                                |
| <mark style="color:blue;">描述</mark>                  | 否  | 簡述此 MCP 伺服器的用途                                                                                                                           |
| <mark style="color:blue;">工具類別</mark>                | 否  | 此伺服器的工具未個別歸類時套用的預設類別，影響對話中工具卡片的顯示文案                                                                                                      |
| <mark style="color:blue;">Logo</mark>                | 否  | 卡片圖示                                                                                                                                     |
| <mark style="color:blue;">伺服器 URL</mark>             | 是  | MCP 伺服器網址，必須使用 `https://`                                                                                                                |
| <mark style="color:blue;">OAuth 伺服器 URL</mark>       | 否  | 授權伺服器的網址。留空時系統會從 MCP 伺服器公告的資訊自動找到；只有自動偵測失敗，或授權伺服器與 MCP 伺服器位在不同網域時才需要填寫（例如 Supabase 的 MCP 在 `mcp.supabase.com`，授權伺服器在 `api.supabase.com`） |
| <mark style="color:blue;">Resource Identifier</mark> | 否  | 向授權伺服器申請權杖時指定的資源識別碼。留空時自動偵測；只有偵測失敗或伺服器公告的資訊有誤時才需要填寫（例如 Asana 為 `https://mcp.asana.com`）                                                  |
| <mark style="color:blue;">OAuth Client ID</mark>     | 否  | 伺服器支援自動註冊用戶端時留空。伺服器不支援時，先在對方的 OAuth 服務建立應用程式，再把取得的 Client ID 填在這裡                                                                        |
| <mark style="color:blue;">OAuth Client Secret</mark> | 否  | 搭配 Client ID 使用，對方要求機密用戶端（confidential client）時才需要填寫。已設定過時欄位顯示為遮罩，留空會保留原值，重新輸入則覆蓋                                                        |

建立後的連接器可在「<mark style="color:blue;">工具</mark>」頁面的「<mark style="color:blue;">管理連接器</mark>」修改或刪除。變更「伺服器 URL」會讓使用此連接器的工具失去授權，請謹慎修改。
{% endstep %}

{% step %}

### 選擇授權對象 <a href="#oauth-auth-subject" id="oauth-auth-subject"></a>

選定連接器後，在「<mark style="color:blue;">授權對象</mark>」選擇 Agent 要用誰的帳號操作這個服務：

| 授權對象                                     | 說明                                                                                                |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">組織共用</mark>    | 全組織共用同一組授權，由管理員或成員先授權一次。之後所有透過這個 Agent（LINE、Web Chat 等）的使用者，都會以授權者的帳號存取服務，因此每個人該用自己帳號的個人帳號型服務請勿選擇 |
| <mark style="color:blue;">聯絡人個別授權</mark> | 每位聯絡人在對話中各自登入授權，Agent 以該聯絡人本人的身分操作。需要已登入的使用者：未登入的匿名訪客對話中，Agent 不會取得這個工具                           |
| {% endstep %}                            |                                                                                                   |

{% step %}

### 完成授權 <a href="#oauth-authorize" id="oauth-authorize"></a>

* **組織共用**：點擊「<mark style="color:blue;">前往授權</mark>」。工具尚未儲存時會先儲存，再開啟對方服務的授權視窗；完成登入與同意後，畫面顯示「<mark style="color:blue;">已授權</mark>」，系統會自動取得工具清單並儲存，然後關閉編輯視窗。要改用其他帳號時，再次開啟工具，點擊「<mark style="color:blue;">註銷</mark>」後重新授權。
* **聯絡人個別授權**：不需要在這裡授權，每位聯絡人會在對話中各自登入授權。授權狀態可在「<mark style="color:blue;">聯絡人</mark>」編輯視窗的「<mark style="color:blue;">Connector 授權</mark>」分頁查看、撤銷或觸發重新授權。

{% hint style="warning" %}
授權視窗以彈出式視窗開啟。若出現「<mark style="color:blue;">彈出式視窗被封鎖，請允許彈出式視窗後重試</mark>」，請在瀏覽器允許此網站開啟彈出式視窗後再點一次「前往授權」。
{% endhint %}
{% endstep %}
{% endstepper %}

#### c. 📰 標頭 (JSON) <a href="#mcp-headers" id="mcp-headers"></a>

* **用途**：設定每次連線 MCP 伺服器時都要帶上的 HTTP 標頭，例如固定的 API Key 或 Token。
* **格式**：有效的 JSON 物件，鍵 (Key) 是標頭名稱，值 (Value) 是標頭內容 (字串)。不需要時維持 `{}`。
* **直接輸入網址時**：在這裡填入伺服器要求的驗證標頭，金鑰請直接填實際的值：

  ```json
  {
    "Authorization": "Bearer 這裡貼上服務商提供的 Token"
  }
  ```
* **選定 OAuth 連接器時**：驗證已自動處理，這裡只需填寫額外的自訂標頭（選填）。授權對象為「組織共用」時，請不要在這裡填 `Authorization`，否則會取代自動帶入的授權。
* **共用與個別憑證**：這裡的標頭由所有對話共用。若每位聯絡人要用自己的金鑰，請在 [聯絡人 MCP 憑證](/build/tools/setup-contacts-mcp-credentials.md) 為每位聯絡人設定；呼叫時同名標頭以聯絡人的設定為準。
* **可用的變數**：值可以使用欄位下方「<mark style="color:blue;">可用的情境變數</mark>」列出的變數（例如 `{{contact_id}}`、`{{conversation_id}}`），系統會在每次對話時代換為實際值。其他 `{{…}}` 名稱不會被代換，儲存時會出現「<mark style="color:blue;">包含未知的範本變數</mark>」錯誤，因此金鑰不能用自訂變數代替，請填實際的值。
* **誰看得到**：儲存後重新開啟編輯視窗時，每個標頭值只顯示前後各 4 個字元，中間以 `****` 取代；直接儲存不會改變原值。標頭不會提供給 AI 模型，MCP 工具的執行紀錄也不保存請求標頭。

### 5. 找到「<mark style="color:blue;">允許的工具 (JSON 數組)</mark>」，點按重新取得 <a href="#step-5-fetch-allowed-tools" id="step-5-fetch-allowed-tools"></a>

* **用途**：指定在此 MCP 客戶端下，Agent 被授權可以使用的具體子工具列表。一個 MCP 客戶端可能提供多個不同的功能或子工具。
* **取得與選擇工具**：點擊「<mark style="color:blue;">重新取得</mark>」（尚未取得過時，也可點清單中的「<mark style="color:blue;">取得工具</mark>」）後，系統會用目前的伺服器網址與標頭連線，列出伺服器提供的所有工具。以每個工具右側的開關決定 Agent 可以使用哪些工具，也可以用「<mark style="color:blue;">全部啟用</mark>」、「<mark style="color:blue;">全部停用</mark>」一次切換；儲存前至少要啟用一個工具。
* **OAuth 連接器**：授權對象為「組織共用」時，完成授權後系統會自動取得並儲存工具清單。

點按後，系統會自動抓取與該 server 連結的工具內容，並顯示在列表中：

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-a71a8d1d54f524bfea21124d1732678c1956b626%2Fmcp-allowed-tools.png?alt=media" alt="編輯工具視窗的允許的工具 (JSON 數組) 區塊，顯示已啟用 3 / 3 個工具、全部啟用與全部停用按鈕，每個工具右側有開關；上方標頭 (JSON) 的值以 **** 遮罩"><figcaption><p>取得工具清單後，以每個工具右側的開關決定 Agent 可使用的工具</p></figcaption></figure>

### 6. 💾 儲存工具 <a href="#step-6-save-tool" id="step-6-save-tool"></a>

確認所有設定無誤後，捲動到頁面底部，點擊「<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>），再按一次 <mark style="color:blue;">確認</mark> 即可建立；組織共用的 OAuth 工具按「<mark style="color:blue;">前往授權</mark>」時也會先經過這道確認。編輯既有工具時不會出現這道確認。

MCP 伺服器若為工具附上互動介面，Agent 呼叫後對話中會多出一張可直接操作的卡片，不需要額外設定，見 [MCP 互動卡片（MCP Apps）](/build/tools/mcp-apps.md)。

## ⚠️ 重要提醒 <a href="#important-notes" id="important-notes"></a>

**連線測試**

* 建立工具後，建議先測試 MCP 連線是否正常
* 可在測試環境中驗證工具功能

**權限管理**

* 謹慎選擇允許的工具，避免授權過多不必要的功能
* 定期檢查工具使用狀況

**故障排除**

* 如果連線失敗，請檢查 MCP 伺服器網址是否正確
* 確認「標頭 (JSON)」是有效的 JSON 物件，且金鑰填的是實際的值
* 使用 OAuth 連接器（組織共用）時，確認工具已顯示「<mark style="color:blue;">已授權</mark>」


---

# 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/build/tools/mcp-setup.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.