> 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/developer/maiagent-mcp.md).

# MaiAgent MCP

## <mark style="color:blue;">一、MaiAgent MCP 是什麼？</mark> <a href="#what-is-maiagent-mcp" id="what-is-maiagent-mcp"></a>

MaiAgent MCP 是 MaiAgent 官方提供的遠端 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/)服務。將它加入 Claude Code、Claude Desktop、Cursor 等支援 MCP 的 AI 工具後，您就可以直接用自然語言操作 MaiAgent 平台，例如：

* 「幫我建立一個客服 AI 助理，使用 Claude Sonnet 模型」
* 「列出我組織裡所有的知識庫，並把這份 FAQ 上傳到產品知識庫」
* 「查詢昨天的對話紀錄，整理出使用者最常問的問題」

| 項目       | 說明                                               |
| -------- | ------------------------------------------------ |
| **服務端點** | `https://mcp.maiagent.ai/mcp`                    |
| **傳輸方式** | Streamable HTTP（遠端連線，無需在本機安裝任何程式）                |
| **認證方式** | MaiAgent API Key（HTTP Header）                    |
| **涵蓋範圍** | MaiAgent 平台完整 API：AI 助理、知識庫、對話、工具、組織管理等 300 多個端點 |

### 提供的工具 <a href="#available-tools" id="available-tools"></a>

連線成功後，您的 AI 工具會取得以下 6 個工具。AI 會自動組合使用它們（先搜尋 API、再查規格、最後執行），您不需要記住任何 API 細節：

| 工具                    | 用途                                            |
| --------------------- | --------------------------------------------- |
| `debug_auth`          | 檢查認證狀態是否正確                                    |
| `list_api_categories` | 列出所有 API 分類                                   |
| `search_apis`         | 依分類或關鍵字搜尋 API 端點                              |
| `get_api_details`     | 取得特定 API 的完整規格（參數、請求體、回應格式）                   |
| `call_api`            | 實際執行 API 呼叫                                   |
| `refresh_schema`      | 強制重新載入 API 清單（找不到剛上線的新 API 時使用；平常每 5 分鐘會自動更新） |

{% hint style="info" %}
**方向不要搞混了**：本頁教的是「把 MaiAgent 接進**外部** AI 工具」。如果您想做的是相反方向 —— 在 MaiAgent 的 AI 助理裡掛上其他 MCP 工具，請參考 [建立 MCP 工具](/tools/mcp-setup.md)。
{% endhint %}

***

## <mark style="color:blue;">二、前置準備</mark> <a href="#prerequisites" id="prerequisites"></a>

開始前，您只需要準備一把 **API Key**。

{% hint style="warning" %}
API Key 會綁定「**建立金鑰當下所在的組織**」，MCP 的所有操作都會作用在這個組織上。若您隸屬多個組織，請先在後台左上角切換到要操作的組織，再建立金鑰。每位成員在同一個組織內只能有一把有效金鑰。
{% endhint %}

### 取得 API Key <a href="#get-api-key" id="get-api-key"></a>

登入 [MaiAgent 管理後台](https://admin.maiagent.ai)，點擊右上角頭像 → <mark style="color:blue;">個人資料</mark> → 切換到 <mark style="color:blue;">API 金鑰</mark> 頁籤 → 點擊 <mark style="color:blue;">建立新金鑰</mark>，複製產生的 API Key。

<figure><img src="/files/KMl5Y8UIscg9z4O51mxJ" alt="個人資料的 API 金鑰頁籤"><figcaption><p>個人資料 → API 金鑰頁籤</p></figcaption></figure>

{% hint style="danger" %}
API Key 建立後只會顯示一次，請立即複製並妥善保存。API Key 等同您的登入身分，請勿分享給他人，也不要提交到版本控制（git）中。
{% endhint %}

***

## <mark style="color:blue;">三、連線設定</mark> <a href="#setup" id="setup"></a>

依您使用的 AI 工具選擇對應的設定方式。以下範例中，請將 `<YOUR_API_KEY>` 替換成您在前置準備取得的 API Key。

{% tabs %}
{% tab title="Claude Code" %}
在終端機執行：

```bash
claude mcp add --transport http maiagent https://mcp.maiagent.ai/mcp \
  -s user \
  --header "Authorization: Api-Key <YOUR_API_KEY>"
```

`-s user` 代表在所有專案都能使用；若只想在目前專案使用，改成 `-s project`（設定會寫入專案根目錄的 `.mcp.json`）。

也可以直接手動編輯 `.mcp.json`：

```json
{
  "mcpServers": {
    "maiagent": {
      "type": "http",
      "url": "https://mcp.maiagent.ai/mcp",
      "headers": {
        "Authorization": "Api-Key <YOUR_API_KEY>"
      }
    }
  }
}
```

{% hint style="warning" %}
使用 `-s project` 時，Claude Code 第一次啟動會詢問是否信任此專案的 MCP server，請選擇同意。若 `.mcp.json` 所在目錄是 git 專案，請將 `.mcp.json` 加入 `.gitignore`，避免 API Key 被提交。
{% endhint %}
{% endtab %}

{% tab title="Claude Desktop" %}
編輯 Claude Desktop 設定檔（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`；Windows：`%APPDATA%\Claude\claude_desktop_config.json`），加入：

```json
{
  "mcpServers": {
    "maiagent": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.maiagent.ai/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Api-Key <YOUR_API_KEY>"
      }
    }
  }
}
```

儲存後重新啟動 Claude Desktop。

{% hint style="info" %}
此方式需要本機已安裝 [Node.js](https://nodejs.org/)。`Authorization` 的值透過 `env` 傳入，是為了避免設定檔中含空白字元的參數被錯誤切割。
{% endhint %}
{% endtab %}

{% tab title="Cursor" %}
編輯 `~/.cursor/mcp.json`（全域）或專案下的 `.cursor/mcp.json`，加入：

```json
{
  "mcpServers": {
    "maiagent": {
      "url": "https://mcp.maiagent.ai/mcp",
      "headers": {
        "Authorization": "Api-Key <YOUR_API_KEY>"
      }
    }
  }
}
```

儲存後到 <mark style="color:blue;">Cursor Settings</mark> → <mark style="color:blue;">MCP</mark> 確認 `maiagent` 顯示為已連線。
{% endtab %}

{% tab title="其他 MCP 工具" %}
任何支援 **Streamable HTTP** 遠端連線的 MCP 客戶端都可以使用，設定要點：

| 設定項                    | 值                             |
| ---------------------- | ----------------------------- |
| Server URL             | `https://mcp.maiagent.ai/mcp` |
| Transport              | Streamable HTTP               |
| Header：`Authorization` | `Api-Key <YOUR_API_KEY>`      |
| {% endtab %}           |                               |
| {% endtabs %}          |                               |

***

## <mark style="color:blue;">四、驗證連線</mark> <a href="#verify" id="verify"></a>

設定完成後，在您的 AI 工具中請 AI 呼叫 `debug_auth` 工具（例如直接輸入「請呼叫 maiagent 的 debug\_auth 工具檢查連線」），預期會看到：

```json
{
  "has_auth_header": true,
  "auth_header_preview": "Api-Key xxxxxxxx...",
  "has_organization_id": false,
  "organization_id": null
}
```

`has_auth_header` 是 `true` 就代表連線與認證都成功了（`organization_id` 顯示 `null` 是正常的——要操作的組織由 API Key 本身決定）。

***

## <mark style="color:blue;">五、開始使用</mark> <a href="#usage" id="usage"></a>

連線成功後，直接用自然語言下指令即可。AI 會自動透過 `search_apis` → `get_api_details` → `call_api` 的流程找到並執行對應的 API。一些實用的指令範例：

* **查詢**：「列出我的所有 AI 助理」、「這個組織有哪些成員？」
* **建立**：「建立一個名為『產品客服』的 AI 助理，角色指令是……」
* **知識庫**：「建立一個新知識庫，並列出目前有哪些檔案」
* **維運**：「查一下『產品客服』助理最近的對話，幫我摘要常見問題」

{% hint style="warning" %}
透過 MCP 執行的操作與您在後台手動操作**具有相同效力**（權限等同您的帳號）。進行刪除、修改等變更前，建議先請 AI 說明它即將執行的操作內容。
{% endhint %}

***

## <mark style="color:blue;">六、疑難排解</mark> <a href="#troubleshooting" id="troubleshooting"></a>

| 症狀                                | 可能原因與解法                                                                                             |
| --------------------------------- | --------------------------------------------------------------------------------------------------- |
| 連線失敗、回應 **401**                   | API Key 錯誤、已被刪除，或 `Authorization` header 沒帶到。請確認格式為 `Api-Key <YOUR_API_KEY>`（`Api-Key` 與金鑰之間有一個空格）。 |
| 操作到錯誤的組織（查不到預期的助理／知識庫）            | API Key 綁定的是「建立金鑰當下所在的組織」。請切換到正確的組織後重新建立金鑰，並更新設定檔。                                                  |
| 工具清單是空的                           | 連線未成功建立，請重新啟動 AI 工具；Claude Code 可用 `/mcp` 指令檢查連線狀態。                                                 |
| Claude Code 顯示 `Pending approval` | 專案層級（`-s project`）的 MCP 需要先信任才會連線，啟動互動式 Claude Code 依提示同意即可。                                        |
| 執行 API 時出現權限錯誤                    | `call_api` 使用您的身分執行，只能操作您帳號有權限的資源。請確認您在該組織的角色權限。                                                    |

{% hint style="info" %}
若您使用的是專屬部署（On-Premise）環境，MCP 服務端點會與雲端版不同，請聯絡您的 MaiAgent 服務窗口確認。
{% endhint %}


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/developer/maiagent-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.