Ctrlk
註冊/登入
For the complete documentation index, see llms.txt. This page is also available as Markdown.

建立 MCP 工具

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

MCP 是什麼？

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

MCP 解決方案

同一個 MCP 伺服器開發一次，所有支援 MCP 的 AI 平台都能使用；協定的運作原理、MaiAgent 支援的傳輸方式與限制，見技術手冊的 MCP（Model Context Protocol）。

快速建立 MCP 工具

1. 進入工具管理介面

首先，請從左側選單進入 AI 功能 → 工具。進入工具列表頁面後，點選右上角的 新增工具 按鈕。

工具列表頁面與新增按鈕
點擊「新增工具」開始建立

2. 選擇工具類型

工具類型請選擇 MCP。

3. 設定顯示名稱

為工具設定清晰的顯示名稱，這邊設為 Composio mcp for google calendar。

  • 用途：此名稱將會顯示在平台介面中，供所有用戶查看。

  • 建議：選擇一個能清晰表達工具主要功能的名稱，方便用戶理解。此名稱沒有嚴格的格式限制。

4. 填寫 MCP 配置

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

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

伺服器的驗證方式
怎麼設定

OAuth 登入（使用者登入對方服務並同意授權）

在「選擇要連接的服務」選擇連接器，見 b. OAuth 連接器與授權對象

固定的 API Key 或 Token（全組織共用），或不需驗證

在「或直接輸入（無認證 / Service Account）」下方輸入網址，見 a. MCP 伺服器網址；金鑰填在 c. 標頭 (JSON)

每位聯絡人使用自己的 API Key 或 Token

依上一列建立工具，再到聯絡人的「MCP 憑證」分頁設定，見 聯絡人 MCP 憑證設定

a. 🔗MCP 伺服器網址

  • 用途：Agent 透過這個網址連線 MCP 伺服器，取得並呼叫伺服器提供的工具。

  • 填寫位置：

    • 伺服器使用 OAuth：在「選擇要連接的服務」點選連接器卡片，網址會自動帶入，見下方 b. OAuth 連接器與授權對象。

    • 伺服器不需驗證或使用固定金鑰：在「或直接輸入（無認證 / Service Account）」下方的輸入框貼上完整網址，例如 https://mcp.example.com/mcp。

  • 格式：必須以 https:// 開頭，且是可從網際網路連線的遠端伺服器位址。localhost 與內部網路位址無法儲存；地端部署若需連線內部網路的 MCP 伺服器，請洽 MaiAgent 協助開放。

  • 注意：此欄位為必填。

如何獲得 MCP 網址，請參考技術人員手冊—Remote MCP 服務概述

若 MCP 伺服器需要辨識「目前對話的使用者」：訪客以 Keycloak 登入 Web Chat 時，可在對話平台開啟 沿用 Keycloak 登入身分呼叫工具，並把此 MCP 伺服器的主機加入允許名單，平台會以 Authorization 標頭帶上訪客本人的 Keycloak 憑證。

直接輸入網址的工具，儲存時系統會用網址與「標頭 (JSON)」連線伺服器並取得工具清單；連線失敗時會出現「MCP 工具驗證失敗，無法連接 MCP 伺服器」，請檢查網址與標頭。使用 OAuth 連接器的工具會先儲存，完成授權後才取得工具清單。

b. 🔐 OAuth 連接器與授權對象

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

1

選擇連接器

在「選擇要連接的服務」點選要連接的服務卡片（標示 OAuth 2.0），伺服器網址會自動帶入。清單包含平台已驗證的服務，以及組織自訂的連接器。

2

找不到服務時自訂連接器

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

欄位
必填
說明

名稱

是

連接器的識別名稱，只能包含英文字母、數字、底線和連字符，例如 my-mcp-server

顯示名稱

否

顯示在卡片上的名稱

描述

否

簡述此 MCP 伺服器的用途

工具類別

否

此伺服器的工具未個別歸類時套用的預設類別，影響對話中工具卡片的顯示文案

Logo

否

卡片圖示

伺服器 URL

是

MCP 伺服器網址，必須使用 https://

OAuth 伺服器 URL

否

授權伺服器的網址。留空時系統會從 MCP 伺服器公告的資訊自動找到；只有自動偵測失敗，或授權伺服器與 MCP 伺服器位在不同網域時才需要填寫（例如 Supabase 的 MCP 在 mcp.supabase.com，授權伺服器在 api.supabase.com）

Resource Identifier

否

向授權伺服器申請權杖時指定的資源識別碼。留空時自動偵測；只有偵測失敗或伺服器公告的資訊有誤時才需要填寫（例如 Asana 為 https://mcp.asana.com）

OAuth Client ID

否

伺服器支援自動註冊用戶端時留空。伺服器不支援時，先在對方的 OAuth 服務建立應用程式，再把取得的 Client ID 填在這裡

OAuth Client Secret

否

搭配 Client ID 使用，對方要求機密用戶端（confidential client）時才需要填寫。已設定過時欄位顯示為遮罩，留空會保留原值，重新輸入則覆蓋

建立後的連接器可在「工具」頁面的「管理連接器」修改或刪除。變更「伺服器 URL」會讓使用此連接器的工具失去授權，請謹慎修改。

3

選擇授權對象

選定連接器後，在「授權對象」選擇 Agent 要用誰的帳號操作這個服務：

授權對象
說明

組織共用

全組織共用同一組授權，由管理員或成員先授權一次。之後所有透過這個 Agent（LINE、Web Chat 等）的使用者，都會以授權者的帳號存取服務，因此每個人該用自己帳號的個人帳號型服務請勿選擇

聯絡人個別授權

每位聯絡人在對話中各自登入授權，Agent 以該聯絡人本人的身分操作。需要已登入的使用者：未登入的匿名訪客對話中，Agent 不會取得這個工具

4

完成授權

  • 組織共用：點擊「前往授權」。工具尚未儲存時會先儲存，再開啟對方服務的授權視窗；完成登入與同意後，畫面顯示「已授權」，系統會自動取得工具清單並儲存，然後關閉編輯視窗。要改用其他帳號時，再次開啟工具，點擊「註銷」後重新授權。

  • 聯絡人個別授權：不需要在這裡授權，每位聯絡人會在對話中各自登入授權。授權狀態可在「聯絡人」編輯視窗的「Connector 授權」分頁查看、撤銷或觸發重新授權。

授權視窗以彈出式視窗開啟。若出現「彈出式視窗被封鎖，請允許彈出式視窗後重試」，請在瀏覽器允許此網站開啟彈出式視窗後再點一次「前往授權」。

c. 📰 標頭 (JSON)

  • 用途：設定每次連線 MCP 伺服器時都要帶上的 HTTP 標頭，例如固定的 API Key 或 Token。

  • 格式：有效的 JSON 物件，鍵 (Key) 是標頭名稱，值 (Value) 是標頭內容 (字串)。不需要時維持 {}。

  • 直接輸入網址時：在這裡填入伺服器要求的驗證標頭，金鑰請直接填實際的值：

  • 選定 OAuth 連接器時：驗證已自動處理，這裡只需填寫額外的自訂標頭（選填）。授權對象為「組織共用」時，請不要在這裡填 Authorization，否則會取代自動帶入的授權。

  • 共用與個別憑證：這裡的標頭由所有對話共用。若每位聯絡人要用自己的金鑰，請在 聯絡人 MCP 憑證 為每位聯絡人設定；呼叫時同名標頭以聯絡人的設定為準。

  • 可用的變數：值可以使用欄位下方「可用的情境變數」列出的變數（例如 {{contact_id}}、{{conversation_id}}），系統會在每次對話時代換為實際值。其他 {{…}} 名稱不會被代換，儲存時會出現「包含未知的範本變數」錯誤，因此金鑰不能用自訂變數代替，請填實際的值。

  • 誰看得到：儲存後重新開啟編輯視窗時，每個標頭值只顯示前後各 4 個字元，中間以 **** 取代；直接儲存不會改變原值。標頭不會提供給 AI 模型，MCP 工具的執行紀錄也不保存請求標頭。

5. 找到「允許的工具(JSON 數組)」，點按重新取得

  • 用途：指定在此 MCP 客戶端下，Agent 被授權可以使用的具體子工具列表。一個 MCP 客戶端可能提供多個不同的功能或子工具。

  • 取得與選擇工具：點擊「重新取得」後，系統會用目前的伺服器網址與標頭連線，列出伺服器提供的所有工具。以每個工具右側的開關決定 Agent 可以使用哪些工具，也可以用「全部啟用」、「全部停用」一次切換；儲存前至少要啟用一個工具。

  • OAuth 連接器：授權對象為「組織共用」時，完成授權後系統會自動取得並儲存工具清單。

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

6. 💾 儲存工具

確認所有設定無誤後，捲動到頁面底部，點擊「確認」按鈕。您的新工具就建立完成了！

MCP 伺服器若為工具附上互動介面，Agent 呼叫後對話中會多出一張可直接操作的卡片，不需要額外設定，見 MCP 互動卡片（MCP Apps）。

⚠️ 重要提醒

連線測試

  • 建立工具後，建議先測試 MCP 連線是否正常

  • 可在測試環境中驗證工具功能

權限管理

  • 謹慎選擇允許的工具，避免授權過多不必要的功能

  • 定期檢查工具使用狀況

故障排除

  • 如果連線失敗，請檢查 MCP 伺服器網址是否正確

  • 確認「標頭 (JSON)」是有效的 JSON 物件，且金鑰填的是實際的值

  • 使用 OAuth 連接器（組織共用）時，確認工具已顯示「已授權」

上一頁工具功能概覽
下一頁MCP 互動卡片（MCP Apps）

最後更新於

這有幫助嗎？