# 建立 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 平台都能使用

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0e7f13f7d59130a0b84c569ec1e913694500768a%2Fplayma%20(9).png?alt=media" alt=""><figcaption><p>MCP 整合前後差異</p></figcaption></figure>

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

## 快速建立 MCP 工具

### 1. 進入工具管理介面

首先，請從左側導航欄進入「 <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-dd5576c2a8c64ec454893eb5c08dcae07b072918%2FMCP%E5%B7%A5%E5%85%B7%20(1).png?alt=media" alt="工具列表頁面與新增按鈕"><figcaption><p>點擊「➕ 新增工具」開始建立</p></figcaption></figure>

### 2. 選擇工具類型

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-21f5fad84196cbd53b9cbadbfc800bc6bf91cace%2FMCP%E5%B7%A5%E5%85%B7%20(2).png?alt=media" alt=""><figcaption></figcaption></figure>

### 3. 設定顯示名稱

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e8c3fa5bce7f8f1fb3ca523bded8c98c302ccaf1%2FMCP%E5%B7%A5%E5%85%B7%20(3).png?alt=media" alt=""><figcaption></figcaption></figure>

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

### 4. 填寫 MCP 配置

#### a. 🔗MCP 伺服器網址

* **用途**：MaiAgent 目前接受外部的 MCP 伺服器，透過提供 MCP 伺服器的服務位址(URL)， AI 助理就可以調用 MCP 服務連結外部應用。
* **格式**：
  * 請填寫完整的 URL (例如：`https://mcp.dev/maiagent/mcp_service`)。
* **注意**：此欄位為必填。

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

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-62093033fa0e37063fdd1a0caa7b36b45e847b9f%2FMCP%E5%B7%A5%E5%85%B7%20(4).png?alt=media" alt=""><figcaption></figcaption></figure>

#### b. 🎛️ MCP 命令參數 (mcp\_args)

{% hint style="warning" %}
如果不需要設定特定的環境變數，此欄位可以留空。
{% endhint %}

* **用途**：定義在執行 MCP 命令或呼叫 MCP 服務時需要傳遞的參數名稱，內容由 AI 助理自動產生。
* **格式**：建議使用 JSON 陣列 (Array) 的格式，其中每個元素都是一個字串代表一個參數。
  * **範例** (JSON 陣列)：

    ```json
    [
        "--user",
        "admin",
        "--config",
        "/path/to/config.yaml"
    ]
    ```
  * **實際執行時**：AI 助理會將這些參數按順序傳遞給 MCP 工具
  * 如果您輸入的是一個以逗號分隔的字串 (例如：`arg1,arg2,arg3`)，系統會嘗試將其解析為參數列表。為避免歧義，推薦使用 JSON 陣列。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-a965eab143b54049703197d49a7dc6479b562056%2FMCP%E5%B7%A5%E5%85%B7%20(5).png?alt=media" alt="MCP 命令參數設定示意圖"><figcaption><p>設定 MCP 命令參數</p></figcaption></figure>

#### c. 🌳 MCP 環境變數 (mcp\_env)

{% hint style="warning" %}
如果不需要設定特定的環境變數，此欄位可以留空。
{% endhint %}

* **用途**：為 MCP 命令的執行環境設定必要的環境變數。
* **格式**：必須是有效的 JSON 物件，其中鍵 (Key) 是環境變數的名稱，值 (Value) 是環境變數的內容 (字串)。
  * **範例**：

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-14cb970b83ae5611c86b25508ccdeabc052e120d%2FMCP%E5%B7%A5%E5%85%B7%20(6).png?alt=media" alt="MCP 環境變數設定示意圖"><figcaption><p>設定 MCP 環境變數</p></figcaption></figure>

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

* **用途**：指定在此 MCP 客戶端下，AI 助理被授權可以使用的具體子工具列表。一個 MCP 客戶端可能提供多個不同的功能或子工具。
* **自動偵測/留空**：如果此欄位留空或未提供，系統在初次連接 MCP 客戶端時，會嘗試自動偵測所有可用的子工具，並預設允許所有偵測到的子工具。若您希望限制 AI 助理只能使用特定的子工具，請在此明確列出。

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-3b8a4967a0e6681a061212c15ff364f3be30e48c%2FMCP%E5%B7%A5%E5%85%B7%20(7).png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-cdb6eda7289d961c6228647418f17eee69a0e801%2Fimage%20(113).png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-3eb68a486703debfc7142bb3afb4404e255076da%2FMCP%E5%B7%A5%E5%85%B7%20(8).png?alt=media" alt=""><figcaption><p>mcp 定義好的工具名稱</p></figcaption></figure>

### 6. 💾 儲存工具

確認所有設定無誤後，捲動到頁面底部，點擊「<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-15e837afde2b4925f1e73faf41021e7d81b2fee5%2FMCP%E5%B7%A5%E5%85%B7%20(9).png?alt=media" alt=""><figcaption></figcaption></figure>

## ⚠️ 重要提醒

**連線測試**

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

**權限管理**

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

**故障排除**

* 如果連線失敗，請檢查 MCP 伺服器網址是否正確
* 確認環境變數和參數格式符合要求


---

# Agent Instructions: 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/mcp-setup.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.