建立 MCP 工具

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

MCP 是什麼？

MCP，全名為 Model Context Protocol，可用於整合多雲平台服務或執行本地客戶端應用程式。

可以把工具使用想像成插頭，插上插頭通電後才能使用服務，傳統上，每個 LLM 會自己開發出不同的工具使用方式，就像不同規格的插頭一樣，會需要多種插座才能使用，若想要讓 OpenAI 和 Claude 都能使用 Google Calendar 的服務，會需要開發人員設計出多種腳本讓不同的 AI 使用。

當 Google Calendar 更新時，開發人員可能需要：

1. 需要同時更新 3 個不同版本的整合

2. 維護 3 份不同的技術文件

導致開發時程過長，成本過高。

MCP 解決方案

MCP 就是設計來解決此問題的標準化協定，透過

1. 標準化的工具定義格式

2. 統一的通訊協定

3. 一致的錯誤處理機制

等以上的處理，簡化開發流程。

使用 MCP 後，開發一個工具只需要：

1. 建立 MCP Server (一次開發)

2. 定義標準化的工具規格

3. 實作統一的業務邏輯

4. 所有支援 MCP 的 AI 平台都能使用

MCP 整合前後差異

MCP 本質上是為了標準化 AI 工具整合而設計的協定，讓開發團隊能夠「一次開發，處處使用」，大幅降低了 AI 助理工具生態系統的複雜度和維護成本。

快速建立 MCP 工具

1. 進入工具管理介面

首先，請從左側導航欄進入「 AI 功能」區塊，然後點擊「🔧 工具」。進入工具列表頁面後，點選右上角的「➕ 新增工具」按鈕。

點擊「➕ 新增工具」開始建立

2. 選擇工具類型

工具類型請選擇 MCP。

3. 設定顯示名稱

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

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

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

4. 填寫 MCP 配置

a. 🔗MCP 伺服器網址

• 用途：MaiAgent 目前接受外部的 MCP 伺服器，透過提供 MCP 伺服器的服務位址(URL)， AI 助理就可以調用 MCP 服務連結外部應用。

• 格式：

  • 請填寫完整的 URL (例如：https://mcp.dev/maiagent/mcp_service)。

• 注意：此欄位為必填。

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

在此處貼上您的 MCP server 網址，系統將會自動抓取該 server 內已連結的工具列表：

b. 🎛️ MCP 命令參數 (mcp_args)

如果不需要設定特定的環境變數，此欄位可以留空。

• 用途：定義在執行 MCP 命令或呼叫 MCP 服務時需要傳遞的參數名稱，內容由 AI 助理自動產生。

• 格式：建議使用 JSON 陣列 (Array) 的格式，其中每個元素都是一個字串代表一個參數。

  • 範例 (JSON 陣列)：

    [
        "--user",
        "admin",
        "--config",
        "/path/to/config.yaml"
    ]

  • 實際執行時：AI 助理會將這些參數按順序傳遞給 MCP 工具

  • 如果您輸入的是一個以逗號分隔的字串 (例如：arg1,arg2,arg3)，系統會嘗試將其解析為參數列表。為避免歧義，推薦使用 JSON 陣列。

設定 MCP 命令參數

c. 🌳 MCP 環境變數 (mcp_env)

如果不需要設定特定的環境變數，此欄位可以留空。

• 用途：為 MCP 命令的執行環境設定必要的環境變數。

• 格式：必須是有效的 JSON 物件，其中鍵 (Key) 是環境變數的名稱，值 (Value) 是環境變數的內容 (字串)。

  • 範例：

    {
      "API_KEY": "{{SECRET_MCP_API_KEY}}",
      "REGION": "us-west-1",
      "DEBUG_MODE": "true"
    } 

設定 MCP 環境變數

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

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

• 自動偵測/留空：如果此欄位留空或未提供，系統在初次連接 MCP 客戶端時，會嘗試自動偵測所有可用的子工具，並預設允許所有偵測到的子工具。若您希望限制 AI 助理只能使用特定的子工具，請在此明確列出。

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

mcp 定義好的工具名稱

6. 💾 儲存工具

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

⚠️ 重要提醒

連線測試

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

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

權限管理

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

• 定期檢查工具使用狀況

故障排除

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

• 確認環境變數和參數格式符合要求