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

# MaiAgent MCP：讓外部 AI 工具操作平台

讓 Claude、Cursor 等支援 MCP 的 AI 工具透過 MaiAgent MCP 操作平台：服務端點與提供的工具、API Key 與 OAuth 兩種連法、驗證與疑難排解

本頁寫給要讓 Claude Code、Claude Desktop、Cursor 等 AI 工具透過 MaiAgent MCP 操作平台的開發者：服務端點與提供的工具、API Key 與 OAuth 兩種連法的設定、連線驗證與疑難排解。MCP 本身的概念見 [MCP（Model Context Protocol）](/tech/mcp/mcp-model-context-protocol.md)。

## <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 平台，例如：

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

| 項目       | 說明                                                       |
| -------- | -------------------------------------------------------- |
| **服務端點** | `https://mcp.maiagent.ai/mcp`                            |
| **傳輸方式** | Streamable HTTP（遠端連線，無需在本機安裝任何程式）                        |
| **認證方式** | API Key（放在 HTTP 標頭），或 OAuth 2.1（成員在瀏覽器登入 MaiAgent 並同意授權） |
| **涵蓋範圍** | MaiAgent 平台完整 API：Agent、知識庫、對話、工具、組織管理等 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 分鐘會自動更新） |

#### 工具的輸入格式 <a href="#tool-schemas" id="tool-schemas"></a>

| 工具                                                  | 輸入欄位                                                                                           | 說明                                                   |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `debug_auth`、`list_api_categories`、`refresh_schema` | 無                                                                                              | —                                                    |
| `search_apis`                                       | `category`（string，選填）、`search`（string，選填）、`limit`（number，選填，預設 20）                             | `search` 可填多個詞，以空格分隔，每個詞都要命中；回傳符合的端點與 `operation_id` |
| `get_api_details`                                   | `operation_id`（string，必填）                                                                      | 回傳該端點的路徑、方法、參數、請求與回應結構                               |
| `call_api`                                          | `operation_id`（string，必填）、`path_params`（object，選填）、`query_params`（object，選填）、`body`（object，選填） | 實際呼叫；三個物件都是「名稱→值」的平面物件                               |

`call_api` 的規則：

* `operation_id` 是 API 文件各端點標示的 operationId，例如 `v1KnowledgeBasesFilesList`。
* `path_params` 的 key 對應路徑中的 `{…}` 名稱（例如 `knowledgeBasePk`），值會經 URL 編碼後代入；缺少路徑參數時呼叫失敗，不會送出。
* `query_params` 直接成為查詢字串；`body` 以 JSON 送出，只有 `POST`／`PUT`／`PATCH` 需要。
* 認證沿用連線時的 API Key 或 OAuth 權杖，不需要在參數裡帶金鑰；權限等同該成員的角色。
* 回應超過 50,000 bytes 時會被截斷並標示，請用分頁參數或篩選縮小結果。
* API 回傳的錯誤（`400`、`403`、`404` 等）會原樣帶回給 AI，內容格式見 [API 共通規範：錯誤回應](https://docs.maiagent.ai/api/preparation/conventions#errors)。

以「列出某個知識庫的 PDF 檔案」為例，AI 會依序呼叫：

```json
// 1. search_apis
{"search": "knowledge base files", "limit": 5}

// 2. get_api_details
{"operation_id": "v1KnowledgeBasesFilesList"}

// 3. call_api
{
  "operation_id": "v1KnowledgeBasesFilesList",
  "path_params": {"knowledgeBasePk": "550e8400-e29b-41d4-a716-446655440000"},
  "query_params": {"fileType": "pdf", "pageSize": 20}
}
```

{% hint style="info" %}
**方向不要搞混了**：本頁教的是「把 MaiAgent 接進**外部** AI 工具」。如果您想做的是相反方向 —— 在 MaiAgent 的 Agent 裡掛上其他 MCP 工具，後台操作請參考使用者手冊的 [建立 MCP 工具](https://docs.maiagent.ai/build/tools/mcp-setup)，自家系統要做成 MCP Server 的規格見 [自架 MCP Server 接入規格](/tech/mcp/self-hosted-mcp-server.md)。
{% endhint %}

***

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

開始前，先決定用哪一種方式認證：

| 認證方式        | 適合誰                           | 要準備什麼                                                    |
| ----------- | ----------------------------- | -------------------------------------------------------- |
| **API Key** | 個人或自動化腳本，所有支援自訂標頭的 MCP 客戶端都能用 | 一把 API Key，見下方[取得 API Key](#get-api-key)                 |
| **OAuth**   | 讓多位成員用自己的帳號連線，不必把金鑰貼進設定檔      | 管理員先建立 OAuth 應用程式，見下方[準備 OAuth 應用程式](#prepare-oauth-app) |

兩種方式的操作權限都等同成員自己的角色權限。

{% hint style="warning" %}
API Key 會綁定「**建立金鑰當下所在的組織**」，MCP 的所有操作都會作用在這個組織上。若您隸屬多個組織，請先在後台左上角切換到要操作的組織，再建立金鑰。每位成員可以持有多把金鑰，管理方式見使用者手冊的 [API Key 管理](https://docs.maiagent.ai/org/developer/api-keys)。
{% 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。

詳細說明見使用者手冊的 [個人帳號設定：API 金鑰](https://docs.maiagent.ai/start/profile#api-keys)；由管理員代發金鑰的方式見 [API Key 管理](https://docs.maiagent.ai/org/developer/api-keys#create-api-key)。

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

### 準備 OAuth 應用程式 <a href="#prepare-oauth-app" id="prepare-oauth-app"></a>

用 OAuth 連線前，需要由具「OAuth 應用程式管理權限」的管理員在組織建立一個應用程式：

1. 到 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">組織概覽</mark> → <mark style="color:blue;">管理操作</mark> → <mark style="color:blue;">OAuth 應用程式</mark>，點選 <mark style="color:blue;">建立應用程式</mark>。
2. <mark style="color:blue;">應用程式類型</mark> 選 <mark style="color:blue;">Public</mark>。
3. <mark style="color:blue;">Redirect URIs</mark> 填 MCP 客戶端授權完成後導回的網址，必須和客戶端實際使用的網址完全相同，例如 Claude 網頁版的 `https://claude.ai/api/mcp/auth_callback`；Claude Code 見下方[用 OAuth 連線](#setup-oauth)。
4. 建立後把 <mark style="color:blue;">Client ID</mark> 提供給要連線的成員。

完整步驟見使用者手冊的 [OAuth 應用程式](https://docs.maiagent.ai/org/developer/oauth-applications#create-application)。

{% hint style="warning" %}

* 透過 OAuth 連線時，操作的是**應用程式所屬的組織**。要操作另一個組織，請使用該組織建立的應用程式。
* 授權頁只提供 Email 與密碼登入。只用 SSO 登入、沒有登入密碼的成員無法完成授權，請改用 API Key，見[只用 SSO 登入的成員](https://docs.maiagent.ai/org/developer/oauth-applications#sso-only-members)。
  {% endhint %}

***

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

依您使用的 AI 工具選擇對應的設定方式。以下範例使用 API Key，請將 `<YOUR_API_KEY>` 替換成您在前置準備取得的 API Key；改用 OAuth 請見[用 OAuth 連線](#setup-oauth)。

{% 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 %}          |                               |

### 用 OAuth 連線 <a href="#setup-oauth" id="setup-oauth"></a>

用 OAuth 連線時，設定裡**不要**帶 `Authorization` 標頭。MCP 客戶端第一次連線時會收到 MaiAgent MCP 要求授權的回應，接著開啟瀏覽器讓您登入 MaiAgent；授權頁會顯示應用程式名稱、所屬組織與目前登入的帳號，確認後按「授權」即完成。之後客戶端會自動續期，不需要每次登入。

MaiAgent 不支援動態用戶端註冊，MCP 客戶端必須能填入預先建立的 Client ID。

{% tabs %}
{% tab title="Claude Code" %}
在終端機執行（`8765` 可換成任一固定的連接埠）：

```bash
claude mcp add --transport http maiagent https://mcp.maiagent.ai/mcp \
  -s user \
  --client-id <CLIENT_ID> \
  --callback-port 8765
```

OAuth 應用程式的 <mark style="color:blue;">Redirect URIs</mark> 要登記 `http://localhost:8765/callback`，連接埠必須和 `--callback-port` 相同。

設定完成後在 Claude Code 輸入 `/mcp`，選擇 `maiagent` 並依提示完成瀏覽器授權。
{% endtab %}

{% tab title="Claude（網頁版／Desktop）" %}
在 Claude 的連接器設定新增自訂連接器：網址填 `https://mcp.maiagent.ai/mcp`，在進階設定填入 OAuth Client ID，再依提示連線並完成授權。

OAuth 應用程式的 <mark style="color:blue;">Redirect URIs</mark> 要登記 `https://claude.ai/api/mcp/auth_callback`。
{% endtab %}

{% tab title="其他 MCP 工具" %}
客戶端需支援 MCP 的 OAuth 授權（授權碼＋PKCE），並能填入預先註冊的 Client ID：

| 設定項             | 值                             |
| --------------- | ----------------------------- |
| Server URL      | `https://mcp.maiagent.ai/mcp` |
| Transport       | Streamable HTTP               |
| OAuth Client ID | OAuth 應用程式的 Client ID         |
| Redirect URI    | 客戶端實際使用的回呼網址，須登記在 OAuth 應用程式  |

授權伺服器的端點與協定細節見 [MaiAgent 作為 OAuth 2.1 授權伺服器](/tech/identity-and-access/maiagent-oauth-server.md)。
{% 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` 代表設定的認證已帶上。用 OAuth 連線時，`auth_header_preview` 會以 `Bearer` 開頭。`organization_id` 顯示 `null` 是正常的：要操作的組織由 API Key，或 OAuth 應用程式所屬的組織決定。實際能否呼叫成功，可以接著請 AI 執行一個查詢（例如「列出我的所有 Agent」）確認。

***

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

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

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

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

***

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

| 症狀                                | 可能原因與解法                                                                                                               |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 呼叫 API 時回應 **401**                | API Key 錯誤、已撤銷或停用。請確認格式為 `Api-Key <YOUR_API_KEY>`（`Api-Key` 與金鑰之間有一個空格）。                                              |
| 使用 API Key，客戶端卻要求登入或顯示需要驗證        | 設定裡沒有帶到 `Authorization` 標頭，MaiAgent MCP 因此要求客戶端改走 OAuth。請檢查標頭的設定方式；要用 OAuth 則依[用 OAuth 連線](#setup-oauth)設定 Client ID。 |
| OAuth 授權時出現 Redirect URI 不符       | 客戶端的回呼網址和 OAuth 應用程式登記的不一致。請確認 scheme、主機、連接埠與路徑完全相同。                                                                  |
| OAuth 授權頁無法登入                     | 授權頁只提供 Email 與密碼登入，只用 SSO 登入的帳號請改用 API Key。                                                                           |
| 操作到錯誤的組織（查不到預期的 Agent／知識庫）        | API Key 綁定的是「建立金鑰當下所在的組織」，請切換到正確的組織後重新建立金鑰，並更新設定檔。OAuth 操作的是應用程式所屬的組織，請改用正確組織的 Client ID。                             |
| 工具清單是空的                           | 連線未成功建立，請重新啟動 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 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/tech/mcp/maiagent-mcp.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.